Skill Development

When to Use This Skill

• Building a new skill for a specific domain or workflow
• Updating an existing skill with improvements
• Packaging skills for distribution

• You discovered something that took significant time to figure out
• Existing skill instructions were incomplete or led you astray
• You repeatedly solve the same undocumented problem

Part 1: Creating Skills

Skill Structure

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      - Executable code
    ├── references/   - Documentation loaded as needed
    └── assets/       - Files used in output

SKILL.md Requirements

---
name: skill-name
description: What this skill does. Use when [triggers]. 
---

# Skill Name

[Instructions in imperative form...]

• name

  : lowercase, hyphens, gerund form (e.g.,

  creating-skills

  )

• description

  : Lead with action verbs, end with "Use when [triggers]"

Writing Style

• ✅ "To accomplish X, do Y"
• ❌ "You should do X"

Progressive Disclosure

references/

1. Metadata (~100 words) - Always in context
2. SKILL.md body (<5k words) - When skill triggers
3. References (unlimited) - Loaded as needed by agent

Scripts

• Are repeatedly rewritten
• Require deterministic reliability
• Save significant tokens

Part 2: Contributing Skills

Core Philosophy

What to Contribute

Validation Checklist

• Is this generalizable beyond your specific context?
• Have you seen this pattern multiple times?
• Does this address a real gap vs. personal preference?
• Would this help an agent on a completely different project?

Contribution Process

1. Recognize - Notice patterns during work (time investment, repetition, corrections)
2. Validate - Confirm pattern is general, not specific to your context
3. Create branch -

   add/skill-name

   or

   fix/skill-name

4. Submit PR - Clear description with rationale and evidence

references/pr-workflow.md

Scripts

• scripts/init_skill.py

  - Initialize skill directory structure

• scripts/package_skill.py

  - Package skill for distribution

• scripts/quick_validate.py

  - Validate SKILL.md format

References

• references/recognizing-learnings.md

  - Patterns for spotting valuable learnings

• references/validation-criteria.md

  - Detailed validation guidelines

• references/pr-workflow.md

  - PR process and templates

• references/contribution-examples.md

  - Real contribution examples

• references/progressive-disclosure-research.md

  - Research on skill organization