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: sw:architect
description: System Architect expert...
allowed-tools: Read, Write, Edit
context: fork
model: opus
---

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

---
name: sw: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.