Export Skills to Agent Skills Standard

Overview

Export SpecWeave skills to the Agent Skills open standard format. This enables skill portability across:

• GitHub Copilot (VS Code integration)
• Gemini CLI
• Cursor
• Claude Code
• Other Agent Skills-compatible tools

Usage

/sw:export-skills [options]

Options

| Option | Description | |--------|-------------| | --output <dir> | Output directory (default: .agent-skills/) | | --plugin <name> | Export specific plugin (default: all) | | --skill <name> | Export specific skill (default: all) | | --dry-run | Preview without writing files | | --validate | Validate output against Agent Skills spec |

Output Structure

.agent-skills/
├── architect/
│   └── SKILL.md
├── security/
│   └── SKILL.md
├── qa-lead/
│   └── SKILL.md
└── pm/
    └── SKILL.md

Field Mapping

| SpecWeave Field | Agent Skills Field | Notes | |-----------------|-------------------|-------| | name | name | Direct mapping | | description | description | Direct mapping (max 1024 chars) | | allowed-tools | allowed-tools | Convert comma to space-delimited | | N/A | license | Add Apache-2.0 by default | | N/A | compatibility | Add "Designed for Claude Code" | | N/A | metadata.author | Use plugin manifest author | | N/A | metadata.source | Add "SpecWeave" | | visibility | (not mapped) | Agent Skills uses file placement | | invocableBy | (not mapped) | Agent Skills discovery is implicit |

Execution Steps

Step 1: Discover Skills

# Find all SKILL.md files in plugins
find plugins -name "SKILL.md" -type f

Step 2: Convert Each Skill

For each SKILL.md:

1. Parse YAML frontmatter
2. Extract description (truncate to 1024 chars if needed)
3. Convert allowed-tools from comma to space-delimited
4. Generate Agent Skills-compliant frontmatter
5. Preserve markdown body content

Step 3: Validate Output

Each exported skill must:

• Have name matching directory name
• Have description between 1-1024 characters
• Have name using only a-z and -
• Not have -- in name
• Not start/end with -

Step 4: Write Files

Write to output directory with structure:

{output}/{skill-name}/SKILL.md

Conversion Script

interface SpecWeaveSkill {
  name: string;
  description: string;
  'allowed-tools'?: string;
  visibility?: string;
  invocableBy?: string[];
  context?: string;
  model?: string;
}

interface AgentSkill {
  name: string;
  description: string;
  license?: string;
  compatibility?: string;
  metadata?: Record<string, string>;
  'allowed-tools'?: string;
}

function convertSkill(specweave: SpecWeaveSkill, pluginName: string): AgentSkill {
  return {
    name: specweave.name,
    description: specweave.description.slice(0, 1024),
    license: 'Apache-2.0',
    compatibility: 'Designed for Claude Code (or similar products)',
    metadata: {
      author: 'specweave',
      source: 'SpecWeave',
      plugin: pluginName
    },
    'allowed-tools': specweave['allowed-tools']?.replace(/,\s*/g, ' ')
  };
}

Example Output

Input (plugins/specweave/skills/architect/SKILL.md):

---
name: architect
description: System Architect expert...
allowed-tools: Read, Write, Edit
context: fork
model: opus
---

Output (.agent-skills/architect/SKILL.md):

---
name: architect
description: System Architect expert...
license: Apache-2.0
compatibility: Designed for Claude Code (or similar products)
metadata:
  author: specweave
  source: SpecWeave
  plugin: sw
allowed-tools: Read Write Edit
---

Post-Export Actions

After exporting:

1. Commit to repo: Skills can be discovered from any subdirectory
2. Push to GitHub: Enable Copilot skill discovery
3. Publish: Consider publishing to skill registries

Limitations

• SpecWeave-specific fields (context, model, invocableBy) are not exported
• Progressive disclosure phases (sub-files) are not included
• Skill memory files are not exported (they're runtime state)

Project-Specific Learnings

Before starting work, check for project-specific learnings:

# Check if skill memory exists for this skill
cat .specweave/skill-memories/export-skills.md 2>/dev/null || echo "No project learnings yet"

Project learnings are automatically captured by the reflection system when corrections or patterns are identified during development. These learnings help you understand project-specific conventions and past decisions.