Create Skill

When to use

Use this skill when you need to create a new skill under skills/ and want a valid, maintainable SKILL.md.

Typical triggers:

• “Create a skill for …”
• “Scaffold skills/<name>/SKILL.md“
• “Add a new skill with proper metadata and guardrails”
• “Help me create a skill that helps create other skills”

When not to use

Do not use this skill for:

• Editing product/application code outside skills/
• Large refactors of existing skills unless explicitly requested
• Running destructive commands or making unrelated repository changes

Required inputs

Collect before writing files:

• Base skill name in kebab-case (<skill-name>, without prefix)
• Prefix choice (ask explicitly; suggest custom- by default unless the repository has its own convention)
• Final skill name (custom-<skill-name> unless the user chooses a different prefix or none)
• Target path (skills/<final-skill-name>/, skills/.experimental/<final-skill-name>/, or skills/.curated/<final-skill-name>/)
• Initial semantic version for frontmatter metadata (MAJOR.MINOR.PATCH, default 0.0.0 for skills created in this repository)
• License for frontmatter (MIT by default, or repository-specific choice)
• One-sentence purpose for frontmatter description
• Expected output (files, commands, summary)
• Safety boundaries

Validate metadata constraints:

• name: <= 64 chars, lowercase letters/numbers/hyphens only, no XML tags, and no platform-reserved words
• description: non-empty, <= 1024 chars, no XML tags, includes both what it does and when to use it
• metadata.version: semantic version string (MAJOR.MINOR.PATCH) in quoted YAML format
• metadata: primarily string key/value map; arrays allowed for explicit relationship fields, avoid nested objects
  • metadata.role: "orchestrator" or "subordinate" (subordinates cannot run without their orchestrator)
  • metadata.orchestrator: required orchestrator skill name (subordinates only)
  • metadata.skills: list of subordinate skill names (orchestrators only)
  • metadata.tags: optional list of lowercase kebab-case strings for discoverability
  • metadata.mcp: optional map for MCP server needs (required and suggested lists)
• license and compatibility: optional top-level frontmatter fields (not inside metadata)

If required inputs are missing, ask concise targeted questions first. Use assets/follow-up-questions.md as the default question bank.

Instructions

1. Check whether an existing skill already covers the request:
   • Run npx -y skills add . --list
   • If an existing skill matches, recommend using/updating that skill instead of creating a duplicate
   • If a skill almost matches, open/recommend a repository issue to request tweaks to that existing skill instead of creating a new custom skill
   • Prioritize reuse of repository skills to avoid proliferation of one-off custom skills
2. Confirm scope, base skill name, prefix choice, and target path.
3. Derive <final-skill-name> from prefix choice.
4. Create <target>/<final-skill-name>/SKILL.md.
5. Create resource directories as needed:
   • references/ for longer guidance and detailed docs
   • assets/ for templates/checklists/static resources
   • scripts/ only when deterministic automation is required
6. Write frontmatter (name, description) that satisfies constraints.
7. Add the core sections:
   • When to use
   • When not to use
   • Required inputs
   • Instructions
   • Expected output
   • Safety & constraints
8. Keep SKILL.md concise; move long guidance/examples to references/.
9. Use assets/ for templates, sample files, and static resources used by the skill.
10. Add scripts/ only when deterministic automation is required.
11. When inputs are missing, ask from assets/follow-up-questions.md and proceed once answered.

Expected output

Return:

• Created/updated file paths
• Validation command(s) run
• Pass/fail result with interpretation
• Any required follow-up actions
• Any unresolved follow-up questions (if user input was still missing)
• Whether an existing skill was reused, and if an issue was created/recommended for an almost-match

For a newly scaffolded skill, the default structure should be:

skills/<final-skill-name>/
├── SKILL.md
├── references/
└── assets/

Use this baseline for generated SKILL.md files:

---
name: <final-skill-name>
description: <what it does + when to use it>
license: MIT
metadata:
   version: "<initial-version>"
---

# <Skill Title>

## When to use

## When not to use

## Required inputs

## Instructions

## Expected output

## Safety & constraints

Validation

Run from repo root:

npx -y skills add . --list

Pass criteria:

• Exit code is 0
• New skill appears discoverable/valid
• No metadata/path errors

If validation fails:

• Fix frontmatter (name, description)
• Verify path and SKILL.md existence
• Re-run and report final status

Ready-to-merge checklist

Use assets/ready-to-merge-checklist.md as a lightweight PR gate.

Safety & constraints

Never:

• Request or expose secrets/credentials
• Run destructive commands without explicit user confirmation
• Invent validation results
• Modify unrelated files outside requested scope
• Add hidden network-fetch or unsafe script guidance without explicit request