Write A Skill

Writing Skills

> Derived from Matt Pocock's write-a-skill (MIT). Matt's voice and 3-phase workflow preserved verbatim. Additions: validation tools + references + cs- wrapper (see Tooling + Companions* below).

Process

1. Gather requirements - ask user about:

• What task/domain does the skill cover?
• What specific use cases should it handle?
• Does it need executable scripts or just instructions?
• Any reference materials to include?

1. Draft the skill - create:

• SKILL.md with concise instructions
• Additional reference files if content exceeds 100 lines
• Utility scripts if deterministic operations needed

1. Review with user - present draft and ask:

• Does this cover your use cases?
• Anything missing or unclear?
• Should any section be more/less detailed?

Skill Structure

skill-name/
├── SKILL.md           # Main instructions (required)
├── REFERENCE.md       # Detailed docs (if needed)
├── EXAMPLES.md        # Usage examples (if needed)
└── scripts/           # Utility scripts (if needed)
    └── helper.js

SKILL.md Template

Copy-paste starting point: [references/skillmdtemplate.md](references/skillmdtemplate.md).

Description Requirements

The description is the only thing your agent sees when deciding which skill to load — see [references/descriptiondesignpatterns.md](references/descriptiondesignpatterns.md) for the four format rules and good/bad examples.

When to Add Scripts

Add utility scripts when:

• Operation is deterministic (validation, formatting)
• Same code would be generated repeatedly
• Errors need explicit handling

Scripts save tokens and improve reliability vs generated code.

When to Split Files

See [references/progressivedisclosureprinciples.md](references/progressivedisclosureprinciples.md) for the 100-line ceiling, the one-level-deep rule, and anti-patterns to avoid.

Review Checklist

After drafting, verify:

• [ ] Description includes triggers ("Use when...")
• [ ] SKILL.md under 100 lines
• [ ] No time-sensitive info
• [ ] Consistent terminology
• [ ] Concrete examples included
• [ ] References one level deep

Tooling + Companions

Validation tools + cs-* wrapper sit alongside this skill. Run all 6 review-checklist items programmatically:

python3 ~/.claude/skills/write-a-skill/scripts/skill_review_checklist_runner.py 

See [references/companiontooling.md](references/companiontooling.md) for the tool catalogue, cs-skill-author persona agent, and /cs:write-a-skill slash command.

Version: 1.0.0 — derived from Matt Pocock (MIT) + this repo's wrapper

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vahidkaargar
• Source: vahidkaargar/it-department-skills
• License: MIT

Install and usage instructions live in the source repository linked above.