Agent Skill Creator

Skill Creator

A skill is a folder that teaches an agent how to handle a specific task or workflow:

your-skill-name/
├── SKILL.md       # Required — YAML frontmatter + Markdown instructions
├── scripts/       # Optional — executable code (Python, Bash, ...)
├── references/    # Optional — docs loaded only when needed
└── assets/        # Optional — templates, fonts, icons used in output

Skills rely on progressive disclosure: the frontmatter is always in context (so it decides when the skill loads), the SKILL.md body loads when relevant, and linked files load only on demand. Keep each level as small as it can be.

Workflow: Creating a New Skill

Step 1: Define 2-3 concrete use cases

Before writing anything, pin down with the user:

• What does the user want to accomplish? (outcome, not feature)
• What triggers it? Collect literal phrases users would say.
• What steps does the workflow require, in order?
• Which tools are needed (built-in, scripts, MCP servers)?
• What domain knowledge or best practices must be embedded?

Write each use case as: Trigger → Steps → Result. If the user is vague, propose use cases and confirm rather than guessing silently.

Identify the category — it shapes the structure:

1. Document & asset creation — embed style guides, templates, quality checklists.
2. Workflow automation — step-by-step process with validation gates.
3. MCP enhancement — orchestrate MCP tool calls in sequence with domain expertise.

Step 2: Plan the folder structure

• Folder name: kebab-case only (my-skill — no spaces, capitals, or underscores) and it should match the frontmatter name.
• SKILL.md must be named exactly that, case-sensitive.
• Never put a README.md inside the skill folder.
• Keep SKILL.md under ~5,000 words; move detail to references/ and link to it.
• For critical validations, prefer a bundled script over prose — code is deterministic, language interpretation isn't.

Step 3: Write the frontmatter

The frontmatter is the single most important part — it alone decides whether the skill ever loads.

---
name: your-skill-name
description: [What it does] + [When to use it, with literal trigger phrases] + [negative triggers if needed]
---

Rules (hard requirements):

• description MUST state both WHAT the skill does and WHEN to use it, under 1024 characters.
• Include specific phrases users would actually say, and file types if relevant.
• No XML angle brackets anywhere in frontmatter (it is injected into the system prompt).
• name must not use reserved prefixes ("claude", "anthropic").

Weak: description: Helps with projects. Strong: description: Manages Linear sprint workflows including planning, task creation, and status tracking. Use when the user mentions "sprint", "Linear tasks", or asks to "create tickets".

Optional disable-model-invocation: true makes the skill user-only: the agent never sees it (no skill catalog entry, no skill_search hit, and the skill tool refuses it), while /skill-name still works for the user. Use it for a long or interrupting workflow whose timing the user should control — a multi-phase orchestration, a deploy, anything with side effects. Leave it off by default; a skill the agent cannot see is a skill it cannot offer. Keep the "only when the user asks" rule in the description and body as well, so the skill still behaves if the flag is ever removed.

For all optional fields (license, compatibility, metadata, allowed-tools) and more good/bad examples, read references/frontmatter.md.

Step 4: Write the instructions

Recommended body structure:

# Skill Name

## Instructions
### Step 1: [First major step]
Exact commands / tool calls, with expected output described.

## Examples
User says X → actions → result.

## Troubleshooting
Error → cause → fix.

Best practices:

• Be specific and actionable: give exact commands with flags and expected output, not vibes ("validate the data").
• Put critical instructions at the top; use ## Important headers for must-not-skip rules.
• Include error handling for the failures users will actually hit.
• Reference bundled resources explicitly ("Before writing queries, read the API-patterns file in references/").
• Number steps that must happen in order; state data dependencies between steps.

For proven structural patterns (sequential orchestration, multi-MCP coordination, iterative refinement, context-aware tool selection, domain-specific intelligence), read references/patterns.md.