write-a-skill — Claude Code plugin: what it does, how to install
For people writing their own agent skills: walks a new skill through three phases and checks it with bundled Python scripts.
/plugin marketplace add alirezarezvani/claude-skills
/plugin install write-a-skill@claude-code-skillsWhat write-a-skill does
The plugin takes you through Gather, Draft, Review and lays out the files a skill needs: a SKILL.md, reference docs kept out of the main file, and a scripts folder. It treats the description as the part that matters most, since that is what the agent reads when picking a skill.
Three Python scripts do the checking. skill_description_validator.py tests the description against the length limit and the third-person, “Use when” wording. skill_structure_validator.py checks the folder, and skill_review_checklist_runner.py runs a six-item review checklist. Run any of them without a path and it falls back to an embedded sample.
There is also a cs-skill-author.md persona agent and a /cs-write-a-skill slash command that asks six questions. The core is Matt Pocock's MIT-licensed write-a-skill, extended with validators and references. Python is what the scripts need; they use the standard library, so no packages to add. A terminal without python on PATH will stop the checks.
What it helps with
- scaffold a new agent skill with the right file layout
- validate a skill description for length and trigger wording
- split an oversized skill into
SKILL.mdand references - run a review checklist before publishing a skill
- write a “Use when” trigger that matches how the agent picks skills
Example prompts for the agent
- Create a new skill for database migrations and lay it out the write-a-skill way
- Run the description validator on
SKILL.mdand tell me what to fix - Run
/cs-write-a-skillfor my skill about commit messages
How to install write-a-skill
Plugin marketplace
/plugin marketplace add alirezarezvani/claude-skills/plugin install write-a-skill@claude-code-skillsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about write-a-skill
How do I install write-a-skill in Claude Code?
Run /plugin marketplace add alirezarezvani/claude-skills, then /plugin install write-a-skill@claude-code-skills.
What does write-a-skill do?
It guides you through Gather, Draft and Review to build a new skill. It also validates the description, folder structure and a six-item checklist with Python scripts.
What do the validators need to run?
Python. All three scripts rely on the standard library, with no external packages.
Source text
write-a-skill · MIT
# write-a-skill Skill-author skill: create new agent skills with proper structure, progressive disclosure, and bundled resources. ## Attribution **Derived from [Matt Pocock's write-a-skill](https://github.com/mattpocock/skills/tree/main/skills/productivity/write-a-skill)** (MIT-licensed). Matt's [skills repo](https://github.com/mattpocock/skills) — *"Skills for Real Engineers. Straight from my .claude directory"* — is the original source. Matt's SKILL.md voice + 3-phase workflow (Gather → Draft → Review) preserved verbatim per his MIT license. ## What this adds on top of Matt's original | Addition | Where | Why | |---|---|---| | **3 stdlib Python validation tools** | `skills/write-a-skill/scripts/` | Operationalize Matt's review checklist (description validator, structure validator, review-checklist runner). Catches the common mistakes Matt names. | | **3 in-depth references** (5+ sources each) | `skills/write-a-skill/references/` | Progressive disclosure principles · Description design patterns · Quality gates for skills. Cites Anthropic skill docs + community precedent + research. | | **cs-skill-author persona agent** | `agents/cs-skill-author.md` | Surface skill-authoring as a forcing-question interrogation matching our cs-* persona pattern. | | **`/cs-write-a-skill` slash command** | `commands/cs-write-a-skill.md` | 6-question forcing interrogation that runs Matt's review checklist programmatically. | ## What Matt's original brings (preserved) - The 3-phase workflow: **Gather → Draft → Review** - The non-negotiable description rule: *"The description is the only thing your agent sees when deciding which skill to load."* - The 100-line SKILL.md ceiling + progressive-disclosure pattern (REFERENCE.md / EXAMPLES.md / scripts) - The good-example vs bad-example contrast for description writing - The 6-item review checklist - Matt's directness — no fluff, concrete patterns ## Quick start ```bash # Run Matt's review checklist on an existing skill python skills/write-a-skill/scripts/skill_review_checklist_runner.py path/to/SKILL.md # Validate description meets Matt's criteria (≤1024 chars, third person, "Use when" trigger) python skills/write-a-skill/scripts/skill_description_validator.py path/to/SKILL.md # Validate skill folder structure python skills/write-a-skill/scripts/skill_structure_validator.py path/to/skill-folder/ ``` All three tools run with embedded samples if no path provided. ## License MIT (matching Matt's upstream).
© Alireza Rezvani · MIT · alirezarezvani/claude-skills
