# Skill Authoring > Use when writing or fixing a Claude Code skill, or when the user says "write a skill", "my skill never triggers", "the wrong skill loads", "skill description", "turn this into a skill", "extract a skill", "the skill is too long". Covers anatomy, trigger design, negative boundaries, context economy, and the router pattern for large skill sets. Writes the SKILL.md. - Skill: `guerrilla2799/skill-authoring` (Agent Skill) - Install (CLI): `npx skillmds@latest add guerrilla2799/skill-authoring` - Raw SKILL.md: https://api.skillmd.com/api/skills/guerrilla2799/skill-authoring/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: guerrilla2799 (https://skillmd.com/u/guerrilla2799) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/guerrilla2799/skill-authoring --- # Skill Authoring Write a skill that actually loads, does one thing, and stays maintainable. Selection happens on the description, so most skill failures are description failures. ## When to use - Writing a new skill - A skill exists and never fires - The wrong skill fires on a request - A skill set has grown past a dozen and collisions started ## Inputs - Reads: `workspace/agents//brief.md`, the context portfolio - Needs from user: the procedure, the phrases a real person uses to ask for it, and the output shape ## Workflow ### 1. Get the description right, because nothing else matters if it is wrong Selection happens on the description alone. The body is invisible until after selection. A description needs three things: ```yaml description: . Use when the user says "", "", "". ``` **Use the literal phrases people actually type, including the ungrammatical ones.** "our data is a mess" is a real trigger. "when the user requires data quality remediation" is not, because nobody says that. **State the output.** A description that says what it writes helps both selection and the reader. ### 2. Write the negative boundary Half of trigger problems are over-firing, not under-firing. ``` Do NOT use this skill when: - → use - → do it inline, no skill needed ``` If two descriptions in your set could match the same sentence, one of them is wrong. Add a "for X, see Y" pointer to both. ### 3. Follow the anatomy ``` --- name: kebab-case, matches the directory name description: as above --- # Title One or two sentences on what this does and the belief behind it. ## When to use Bullets. Concrete situations, not abstractions. ## Inputs - Reads: - Needs from user: ## Workflow ### 1. ### 2. Tables for reference data. Code blocks for output shapes and arithmetic. ## Output - Writes: - Prints: ## Rules & quality bar Bold-lead bullets. The non-negotiables. This is where the opinion lives. ## Related skills - Requires / Hands off to / See also ``` ### 4. One skill, one job The test: can you state what it does in one sentence with no "and"? If not, it is two skills. Symptoms of a skill that is doing too much: a workflow with more than about eight steps, two different output files, or a name containing "and" where the two halves are separable. ### 5. Manage the context cost Every loaded skill occupies context. - **Long reference material goes in `docs/` or `references/`.** The skill points at it. This keeps the loaded footprint small and makes the reference reusable - **Templates go in `templates/`.** Not pasted into the body - **Past roughly a dozen skills, add a router.** One skill holds the routing table and loads exactly one child. Flat sets above that size collide - **State goes in files.** Anything that should survive the session gets written to `workspace/` ### 6. Write the rules section like you mean it The "Rules & quality bar" section is what makes a skill more than a description of a process. It is where you say the unwelcome thing: what to refuse, what to always check, what people get wrong. A skill with a vague rules section produces vague output. Every rule should be checkable. ### 7. Verify it loads Never assume discovery. Skill loaders fail silently. ``` [ ] Directory name matches the frontmatter name [ ] The description contains phrases a real user would type [ ] It appears in a fresh session [ ] It fires on the intended phrase [ ] It does NOT fire on the adjacent phrase you wrote a boundary for [ ] Every path it references exists ``` The last two are the ones people skip, and they are the two that produce the "it works on my machine" failure. ## Output - Writes: `skills//SKILL.md` - Uses: `templates/skill-template.md` - Prints: the skill, plus the verification checklist result ## Rules & quality bar - **The description is the product.** Spend real time on it - **Literal user phrases, including sloppy ones** - **Every skill has a negative boundary** - **One skill, one job.** No "and" in the sentence that describes it - **Reference material lives outside the skill body** - **Router pattern past a dozen skills** - **Verify it loads and verify it does not over-fire.** Both - **Never hardcode positioning, ICP, or guardrails.** Read them from the context portfolio ## Related skills - Requires: `agent-scoping`, `context-portfolio` - Hands off to: `agent-guardrails`, then `agent-rollout` - See also: `docs/build-surface.md` on choosing between skill, subagent, hook, and script