# Skill Authoring > Use when writing a new skill for an AI agent. Covers scoping, description writing for reliable triggering, progressive disclosure, and the difference between a skill and a prompt. - **Type:** Skill - **Install:** `agentstack add skill-nimadorostkar-claude-skills-collection-skill-authoring` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [nimadorostkar](https://agentstack.voostack.com/s/nimadorostkar) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [nimadorostkar](https://github.com/nimadorostkar) - **Source:** https://github.com/nimadorostkar/Claude-Skills-collection/tree/main/skills/agent-tooling/skill-authoring - **Website:** https://github.com/nimadorostkar/Claude-Skills-collection ## Install ```sh agentstack add skill-nimadorostkar-claude-skills-collection-skill-authoring ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Skill Authoring ## Purpose Write a skill that loads at the right time and materially changes the agent's behavior when it does. A skill that never triggers is dead weight; a skill that triggers constantly is a system prompt with extra steps. ## When to Use - Creating a new skill. - A skill that does not activate when it should, or activates when it should not. - Converting a recurring prompt into a reusable capability. - Reviewing a skill before publishing it. ## Capabilities - Scoping: what belongs in a skill and what does not. - Description writing, which is what determines triggering. - Structuring the body for an agent to act on. - Progressive disclosure through supporting files. - Testing that the skill triggers on real requests. ## Inputs - The capability the skill should provide. - The requests that should trigger it, phrased as a user would phrase them. - The requests that should *not* trigger it. ## Outputs - A `SKILL.md` with valid frontmatter and an actionable body. - A description that triggers reliably on the intended requests. - Supporting files for detail that is not always needed. ## Workflow 1. **Scope it to one capability** — A skill that covers "backend development" is too broad to trigger precisely and too shallow to be useful. A skill about API design is neither. 2. **Write the description last, and carefully** — It is the only part the agent sees before deciding whether to load the skill. It must state what the skill does *and* when to use it, using the words a user would actually use. 3. **Write the body as instructions, not as an essay** — The agent will act on it. Concrete steps, explicit constraints, worked examples. Prose about the philosophy of the domain is not actionable. 4. **Move detail into supporting files** — The main file is loaded whenever the skill triggers, so it should be the part that is always needed. Reference material goes in adjacent files the agent reads on demand. 5. **Test the triggering** — With real phrasings, including the ones that should *not* trigger it. A skill that fires on every mention of "code" is a nuisance. ## Best Practices - The description is the skill's entire interface. Include the domain terms, the tools, and the user-facing verbs — a user asking to "make the query faster" will not say "database performance optimization". - Name the negative cases in the description when there is a near neighbor: "Use for API design. Do not use for GraphQL schema design — see the graphql skill." - A skill that only restates what the model already does well adds tokens and no capability. The test is whether behavior changes when it loads. - Keep the main body focused. If it exceeds roughly 500 lines, the detail belongs in supporting files. - Worked examples do more than instructions. One good example of the output shape is worth three paragraphs describing it. - Write the constraints as constraints. "Prefer X" is advice; "Never do Y; always do Z" is a rule the agent will follow. ## Examples **A description that triggers, and one that does not:** ```yaml # Too vague: what is a "database helper"? A user will never phrase a request # in a way that matches this. description: A helpful skill for database stuff. # Precise, with the user's own vocabulary and an explicit boundary. description: > Use when a database query is slow or a table needs an index. Covers reading EXPLAIN output, composite and partial index design, N+1 detection, and lock contention. Trigger on "slow query", "add an index", "the page is slow and it's the database", or a pasted EXPLAIN plan. Do not use for schema design from scratch — see the data-modeling skill. ``` **Progressive disclosure — the main file stays small:** ```text skills/database-performance/ SKILL.md ~200 lines, always loaded when triggered references/ explain-plans.md read only when analyzing a plan index-types.md read only when choosing an index type lock-modes.md read only when diagnosing contention scripts/ slow_query_report.py executed, not read into context ``` In the body: "For the meaning of each node type in an execution plan, read `references/explain-plans.md`." The agent loads it when the task requires it, and not otherwise. **Testing that it triggers:** ```text Should trigger: "this endpoint takes 3 seconds and I think it's the database" -> yes "add an index to the orders table" -> yes "why is this query slow" -> yes [pastes an EXPLAIN ANALYZE output with no question] -> yes Should NOT trigger: "design a schema for a booking system" -> data-modeling "the frontend feels slow" -> web-performance "write a SQL query to find duplicates" -> sql ``` ## Notes - Triggering is determined entirely by the description. If a skill is not loading, the fix is always in the description — never in the body. - The most common authoring mistake is writing the skill as documentation for a human. The reader is an agent that will follow instructions literally; write instructions, not explanation. - A skill with no constraints and no examples rarely changes behavior. The value is in the specifics. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [nimadorostkar](https://github.com/nimadorostkar) - **Source:** [nimadorostkar/Claude-Skills-collection](https://github.com/nimadorostkar/Claude-Skills-collection) - **License:** MIT - **Homepage:** https://github.com/nimadorostkar/Claude-Skills-collection Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-nimadorostkar-claude-skills-collection-skill-authoring - Seller: https://agentstack.voostack.com/s/nimadorostkar - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.