Skill Creator

Guidance for building lean, effective agent skills and validating them before deployment.

Deployment (scope, target paths, verification in <available_skills>) is handled by skill-deployer. Finish creation and validation here first.

Quick Process

1. Understand — gather concrete usage examples (see creation-process.md Step 1)
2. Plan — identify scripts, references, and assets to bundle
3. Implement — write SKILL.md and bundled resources
4. Validate — python scripts/validate_skill.py <skill-folder> (see validation.md)
5. Deploy — hand off to skill-deployer when the skill should become available to agents
6. Iterate — refine after real usage, re-validate after edits

Validation (required before deploy)

python scripts/validate_skill.py <path/to/skill-folder>
python scripts/validate_skill.py <path/to/skill-folder> --strict   # before deployment

Checks frontmatter (same rules as the Rust scanner) and warns about common path mistakes. Full checklist: validation.md.

Core Rules

• Concise body: SKILL.md under ~150 lines; move detail to references/
• Triggers in frontmatter: all "when to use" guidance goes in description, not the body
• Cross-platform by default: never assume Linux/Bash; provide dual recipes (Bash + PowerShell) or OS-neutral commands/scripts
• Name matches folder: name: in frontmatter must equal the directory name
• Safe YAML: use double quotes in description when text contains apostrophes ("Telegram's", not 'Telegram\'s')
• No duplicate reads: information lives in SKILL.md or references, not both
• Imperative voice in body instructions
• No auxiliary docs: no README, CHANGELOG, or INSTALLATION_GUIDE in the skill folder

Structure

See anatomy.md for directory layout (SKILL.md, scripts/, references/, assets/).

Design Guidance

• design-principles.md — concision, degrees of freedom, progressive disclosure
• creation-process.md — full walkthrough
• validation.md — validate_skill.py usage and rules
• workflows.md — sequential and conditional workflow patterns
• output-patterns.md — template and example patterns

Frontmatter Checklist

---
name: skill-name
description: "What it does + specific triggers/contexts for when to use it."
---

Only name and description are required. The description is the primary trigger mechanism.