Skill Creator

This skill guides you through building a well-structured, high-quality Agent Skill from scratch — covering both spec compliance and the practices that make a skill effective in production.

If available, use the skills-spec MCP server for documentation lookup; it is recommended but not required.

Core Principles

Apply these throughout the entire creation process, not just at a single step.

• Ground in real expertise. Do not generate skill content from LLM training knowledge alone. Complete the real task first or synthesize from actual artifacts: internal runbooks, API specs, code review comments, git diffs and patches, incident reports. Project-specific material dramatically outperforms generic best-practice articles.
• Add what the agent lacks; omit what it knows. Write about project-specific conventions, domain-specific procedures, non-obvious edge cases, and which exact tools or APIs to use. Skip explanations of what a CSV is, how HTTP works, or what a database migration does.
• Scope coherently. A skill should encapsulate one coherent unit of work. Too narrow forces multiple skills to load simultaneously and risks conflicting instructions. Too broad makes precise triggering unreliable. A skill that queries a database and formats results is likely one unit; a skill that also covers database administration is probably two.
• Calibrate specificity to fragility. Be prescriptive when an operation is fragile, must happen in a specific sequence, or consistency is critical. Give the agent freedom when multiple valid approaches exist — in those cases, explaining why is more useful than rigid step-by-step directives.
• Procedures over declarations. Teach the agent how to approach a class of problems, not what to produce for a specific instance. The approach should generalize even when individual details are specific.
• One default, brief fallback. When multiple tools or approaches could work, choose one as the default and mention alternatives in a single sentence. Do not present equal options — agents presented with menus make inconsistent choices.
• Moderate detail wins. Overly comprehensive skills hurt more than they help. An agent with exhaustive instructions may pursue unproductive paths triggered by clauses that don't apply to the current task. Concise, stepwise guidance with a working example consistently outperforms exhaustive documentation.

Instruction Patterns