Skill authoring guide
Create or refactor high-quality skills with lean frontmatter, progressive disclosure, and optional bundled helpers. Use when authoring reusable agent workflows.From its SKILL.md
npx -y skills add yeaight7/agent-powerups --skill skill-authoring-guideAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
3.9 KB, 850 tokens by cl100k_base, as published. Nobody here has run it
Skill Authoring Guide
Use this skill when creating or improving a reusable skill.
What Good Skills Do
- Trigger reliably from
nameanddescription— the description must be specific enough to avoid false triggers. - Stay short in
SKILL.mdand move bulk detail intoreferences/orscripts/. - Teach a workflow or decision pattern, not just dump background information.
- Include scripts or references only when they eliminate repeated work or prevent ambiguity.
Frontmatter Template
---
name: kebab-case-matching-directory-name
description: Use when [trigger condition]. Does [what it does]. [Optional: NOT for X.]
---
Body Format
Default to a pure Markdown body after the YAML frontmatter. Use headings such as ## Purpose, ## When to Use, ## Workflow, and ## Verification. Do not use XML-like tags such as <Purpose>, <Workflow>, or <Use_When> as normal top-level sections. XML-like tags are acceptable only when they strictly delimit nested examples, quoted input, external documents, or machine-readable prompt payloads.
Good description (specific, trigger-clear):
Use when designing or reviewing filesystem MCP access, path boundaries, allowed roots, and method allowlists.
Weak description (too broad, won't trigger reliably):
Helps with MCP things and file access.
Workflow
1. Define the job
- What specific problem does this skill solve?
- When should it trigger? (Be concrete — "when the user mentions X" or "when you're about to do Y".)
- What should it explicitly NOT handle? State the boundary.
2. Write strong frontmatter
namemust match the directory name exactly.descriptionmust say what the skill does AND when to use it in one sentence.
3. Keep the body lean
SKILL.mdshould be readable in one focused pass — target 50–120 lines.- Use Markdown headings for top-level structure.
- Move bulky reference material into
references/. - Move deterministic scripts (validators, init scripts) into
scripts/. - If
SKILL.mdexceeds 150 lines, split off the excess into a reference file.
4. Design progressive disclosure
SKILL.md: core workflow, when to use, safety constraints.references/: detailed patterns, full checklists, long examples.scripts/: automation helpers.
5. Validate before publishing
- Check that every file path mentioned in the skill actually exists.
- Remove any
references/links that point to non-existent files. - Verify the skill can be read in under 2 minutes.
- Test the trigger: does the description reliably route to this skill for the intended use case?
Skill Length Guide
| Section | Target |
|---|---|
| Frontmatter description | 1 sentence, 15–30 words |
SKILL.md body | 50–120 lines |
| Individual workflow steps | 1–3 lines each |
| References total | as needed, not in SKILL.md |
Bundled Helpers
scripts/init_skill.py— scaffold a new skill directoryscripts/package_skill.py— package for distributionscripts/quick_validate.py— check frontmatter and dead references
Use them as optional helpers if they fit your workflow.
Verification
- The name field matches the skill directory name exactly
- The description states the trigger condition and what the skill does in one sentence
- The body reads in one focused pass — within the length guide, with bulk detail moved to references
- Every file path mentioned in the skill exists; dead reference links were removed
- The trigger was tested: the description reliably routes the intended use case to this skill
Related Skill
Use hard-won-skill-extractor when the challenge is turning a hard-earned session into a reusable skill candidate.
What ships with it: 3 files
20.1 KB alongside SKILL.md, 3 of them executable
scripts/
- init_skill.pyruns13.7 KB
- package_skill.pyruns3.2 KB
- quick_validate.pyruns3.2 KB
Gives 2 of the 12 instructions most skill authoring skills give in 850 tokens
Counted across 408 of the 422 authors here whose files we hold, read 2026-09-06
- Keep SKILL.md under 500 lineshere, and in 118 of 408, across 104 files
- Write skill instructions in imperative formin 44 of 408, across 37 files
- Move detailed reference material into references fileshere, and in 41 of 408, across 34 files
- Run init_skill.py to initialize new skillsin 40 of 408, across 33 files
- Draft assertions while test runs are in progressin 32 of 408, across 25 files
- Keep description under 1024 charactersin 31 of 408, across 18 files
- Run package_skill.py once the skill is completein 29 of 408, across 23 files
- Spawn with-skill and baseline runs in the same turnin 28 of 408, across 21 files
- Test added scripts by actually running themin 27 of 408, across 21 files
- Follow the creation steps in orderin 24 of 408, across 17 files
- Generate the eval viewer before evaluating outputs yourselfin 24 of 408, across 17 files
- Write the description in third personin 24 of 408, across 18 files
Said here and by no other author read
- State trigger and purpose in one description sentence
- Use Markdown headings for top-level structure
- Define concrete trigger conditions and boundaries
- Teach a workflow, not background information
- Check every mentioned file path exists
- Remove references to non-existent files
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.