skill-creator

## When to Create a Skill Create a skill when: - A pattern is used repeatedly and AI needs guidance - Project-specific conventions differ from generic best practices - Complex workflows need step-by-step instructions - Decision trees help AI choose the right approach **Don't create a skill when:** - Documentation already exists (create a reference instead) - Pattern is trivial or self-explanatory - It's a one-off task --- ## Skill Structure ``` skills/{skill-name}/ ├── SKILL.md # Required - main skill file ├── assets/ # Optional - templates, schemas, examples │ ├── template.py │ └── schema.json └── references/ # Optional - links to local docs └── docs.md # Points to docs/developer-guide/*.mdx ``` --- ## SKILL.md Template ```markdown --- name: {skill-name} description: > {One-line description of what this skill does}. Trigger: {When the AI should load this skill}. license: Apache-2.0 metadata: author: gentleman-programming version: "1.0" --- ## When to Use {Bullet points of when to use this skill} ## Critical Patterns {The most important rules - what AI MUST know} ## Code Examples {Minimal, focused examples} ## Commands ```bash {Common commands} ``` ## Resources - **Templates**: See [assets/](assets/) for {description} - **Documentation**: See [references/](references/) for local docs ``` --- ## Naming Conventions | Type | Pattern | Examples | |------|---------|----------| | Generic skill | `{technology}` | `pytest`, `playwright`, `typescript` | | Project-specific | `{project}-{component}` | `myapp-api`, `myapp-ui` | | Testing skill | `{project}-test-{component}` | `myapp-test-sdk`, `myapp-test-api` | | Workflow skill | `{action}-{target}` | `skill-creator`, `jira-task` | --- ## Decision: assets/ vs references/ ``` Need code templates? → assets/ Need JSON schemas? → assets/ Need example configs? → assets/ Link to existing docs? → references/ Link to external guides? → references/ (with local path) ``` **Key Rule**: `references/` should point to LOCAL files, not web URLs. --- ## Frontmatter Fields | Field | Required | Description | |-------|----------|-------------| | `name` | Yes | Skill identifier (lowercase, hyphens) | | `description` | Yes | What + Trigger in one block | | `license` | Yes | Always `Apache-2.0` | | `metadata.author` | Yes | `gentleman-programming` | | `metadata.version` | Yes | Semantic version as string | --- ## Content Guidelines ### DO - Start with the most critical patterns - Use tables for decision trees - Keep code examples minimal and focused - Include Commands section with copy-paste commands ### DON'T - Add Keywords section (agent searches frontmatter, not body) - Duplicate content from existing docs (reference instead) - Include lengthy explanations (link to docs) - Add troubleshooting sections (keep focused) - Use web URLs in references (use local paths) --- ## Registering the Skill After creating the skill, add it to `AGENTS.md`: ```markdown | `{skill-name}` | {Description} | [SKILL.md](skills/{skill-name}/SKILL.md) | ``` --- ## Checklist Before Creating - [ ] Skill doesn't already exist (check `skills/`) - [ ] Pattern is reusable (not one-off) - [ ] Name follows conventions - [ ] Frontmatter is complete (description includes trigger keywords) - [ ] Critical patterns are clear - [ ] Code examples are minimal - [ ] Commands section exists - [ ] Added to AGENTS.md ## Resources - **Templates**: See [assets/](assets/) for SKILL.md template