write-a-skill
by mattpocockwrite-a-skill skill guide for Skill Authoring: create a reusable agent skill with clear scope, concise instructions, and optional support files. Use it to write, refine, or build a new skill with better triggers, structure, and workflow than a generic prompt.
This skill scores 67/100, which means it is listable but best presented with caution. It gives directory users a credible starting point for creating new skills, with a clear trigger and a basic workflow, but it does not yet offer enough bundled operational material to feel fully turnkey.
- Clear trigger: the description says to use it when users want to create, write, or build a new skill.
- Reasonable workflow outline: it walks through requirements gathering, drafting, and user review.
- Good structural guidance: it shows a template for SKILL.md and when to split content into reference files or scripts.
- No install command or supporting files, so adoption depends entirely on the markdown instructions.
- The repo is mostly guidance-level content; it lacks scripts, references, or concrete examples that reduce execution guesswork.
Overview of write-a-skill skill
What write-a-skill does
The write-a-skill skill helps you create a new agent skill with the right structure, concise instructions, and optional supporting files. It is built for people doing Skill Authoring who want more than a generic prompt: a repeatable way to package task logic so an agent can load and use it reliably.
Who should use it
Use write-a-skill if you need to turn a repeatable workflow into a reusable skill, especially when you already know the task domain and want a clean SKILL.md plus any extra references or scripts. It is a good fit for builders who care about installability, clear triggers, and progressive disclosure.
What makes it useful
The main value of the write-a-skill skill is that it pushes you to define scope, required inputs, and support files before you overbuild. That reduces vague instructions, makes the skill easier for an agent to trigger correctly, and helps you decide whether the skill should stay instruction-only or include executable helpers.
How to Use write-a-skill skill
Install the write-a-skill skill
Install it from the repository path for the write-a-skill skill, then confirm the skill folder loads cleanly in your environment. If your tool supports skill installation by repo path, use the write-a-skill install flow that matches your platform; if not, copy the skills/productivity/write-a-skill folder into the expected skills directory and verify the SKILL.md frontmatter is intact.
Start from the right files
Read SKILL.md first. It is the source of truth for the process, structure, and template. Then inspect any nearby documentation in the repo that explains when to add references, examples, or scripts. For this repo, the most decision-relevant content is the process section, the skill structure example, and the description requirements.
Turn a rough goal into a usable prompt
A strong write-a-skill request should name the task domain, the intended users, the expected output format, and the edge cases that matter. For example, instead of “write a skill for customer support,” ask for “a skill that drafts refund replies for e-commerce orders, handles missing order IDs, and uses a calm, policy-aligned tone.” That level of detail helps the skill authoring flow choose the right scope and supporting files.
Workflow that produces better output
Use write-a-skill in three passes: gather requirements, draft the skill, then review with the user. Keep the first draft small and focused, and only add reference files when the instructions would become too long or too repetitive. The best results come when you decide early whether the skill needs deterministic scripts or only instructional content.
write-a-skill skill FAQ
Is write-a-skill only for new skills?
No. The write-a-skill skill is also useful when you are revising an existing skill and want to tighten scope, simplify instructions, or split long content into references.
Do I need scripts to use it well?
Not always. The skill supports instruction-only skills as well as skills with scripts. Use scripts only when the task benefits from deterministic steps, repeatable formatting, or automation that would be hard to express reliably in prose.
How is this different from a normal prompt?
A normal prompt can describe a task once. The write-a-skill skill is meant to produce a reusable package with triggers, structure, and supporting files so the agent can load it consistently across sessions.
Is it beginner friendly?
Yes, if you already have a clear use case. It is less helpful when you are still exploring what the skill should do, because the process assumes you can answer questions about scope, inputs, and required behavior.
How to Improve write-a-skill skill
Provide stronger requirements up front
The biggest quality boost comes from better inputs: task domain, must-handle cases, tone, output format, and what the skill must not do. If you want a skill for Skill Authoring, say whether it should optimize for speed, depth, strict formatting, or broad coverage.
Avoid common failure modes
The most common mistake is asking for a skill that is too broad. That leads to unclear triggers and bloated instructions. Another failure mode is adding references too early without deciding whether the main SKILL.md can stay concise. Keep the core behavior in the main file and move only durable supporting detail elsewhere.
Review the first draft like an install decision
After the first output, check whether an agent could trigger the skill from the description alone, whether the instructions are short enough to follow, and whether any steps depend on unstated context. If the draft feels generic, tighten the use cases and rewrite the description around the exact job-to-be-done.
Iterate from real usage
After trying the skill once, update the prompt based on where the agent hesitated: missing inputs, wrong level of detail, or unclear formatting. The write-a-skill skill improves fastest when you revise the skill around actual failures instead of expanding it preemptively.