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