create-skill

name	create-skill
description	Scaffold a new SKILL.md file with references and assets directories. Use when building a reusable skill for any agentic system. Guides through naming, procedure design, reference file creation, and validation.
argument-hint	Name and purpose of the skill to create

Create Skill

When to Use

• Building a new reusable skill for any agentic system
• Extracting a repeated workflow into a shareable skill
• Creating a domain-specific procedure that agents or users invoke via /skill-name

Procedure

1. Ask the user for the skill's name (kebab-case) and purpose (one sentence)
2. Determine what the skill needs:
   • References: domain knowledge files the skill reads at runtime (rules, schemas, examples)
   • Assets: template files the skill copies and fills (scaffolds, starter files)
3. Create the directory structure:

   .github/skills/{skill-name}/
   ├── SKILL.md
   ├── references/       # optional — domain knowledge
   └── assets/           # optional — template files to copy
   

4. Write SKILL.md with this structure:
   • Frontmatter: name, description (keyword-rich, includes trigger phrases), argument-hint
   • When to Use: 3-5 bullet points — when should a user or agent invoke this skill
   • Procedure: Numbered steps (5-10). Each step is one action. Reference files with relative links: [label](./references/file.md) or [label](./assets/file.md)
   • Validation Checklist: Checkbox list to verify the output is correct
5. Create reference files in references/ — one file per knowledge domain. Keep each under 200 lines. Use markdown tables for structured data, code blocks for schemas.
6. Create asset files in assets/ — template files with {PLACEHOLDER} markers that the procedure fills in
7. Verify against the checklist below

Skill Authoring Rules

• Frontmatter description must contain trigger phrases users would naturally say
• Procedure steps use imperative voice: "Create the file" not "You should create"
• Reference relative paths only — never absolute paths
• Each reference file covers one topic — split if over 200 lines
• Assets use {UPPER_SNAKE} placeholders — consistent, scannable
• No prose paragraphs in SKILL.md — bullets and numbered steps only

Validation Checklist

• name in frontmatter matches directory name (kebab-case)
• description is keyword-rich with natural trigger phrases
• argument-hint tells the user what input to provide
• When to Use has 3-5 specific scenarios
• Procedure has 5-10 numbered steps
• Every file reference uses relative [label](./path) links
• Reference files exist and are under 200 lines each
• Asset files use {PLACEHOLDER} markers consistently
• No prose paragraphs — bullets and steps only
• Imperative voice throughout