Skill Builder

Builds a complete skill folder from a user request, following Claude skill requirements and best practices.

When to use

Use this skill when the user asks to create a skill, build a skill, or needs guidance on skill structure, SKILL.md frontmatter, testing, or distribution.

Operating principles

Follow the official requirements for skill naming, frontmatter, and folder structure.
Keep the SKILL.md body focused on instructions; move extended details into references/.
Use progressive disclosure: concise frontmatter, clear core instructions, optional references.
Be specific and actionable; include validation and error handling where helpful.

Workflow

1) Clarify intent and scope

If the request is unclear, ask one targeted question. Otherwise infer reasonable defaults.

Collect:

Primary use cases (2-3)
Target user prompts or trigger phrases
Required tools (built-in only vs MCP)
Inputs and outputs (file types, formats)
Success criteria

2) Choose skill category

Classify as one of:

Document and asset creation
Workflow automation
MCP enhancement

Use this to shape the instruction structure and testing approach.

3) Design the skill folder

Create a folder with:

SKILL.md (required)
scripts/ (optional)
references/ (optional)
assets/ (optional)

Do not include a README.md inside the skill folder.

4) Write YAML frontmatter

Frontmatter is required and must be valid YAML.

Requirements:

name is required and kebab-case only
description is required and must include what the skill does and when to use it
description must include specific trigger phrases
description must be under 1024 characters
no XML angle brackets (< or >) in frontmatter
do not use reserved names containing "claude" or "anthropic"

Minimal format:

name: your-skill-name description: What it does. Use when user asks to [specific phrases].

5) Draft the SKILL.md body

Include:

Purpose and when to use
Core steps with explicit outputs
Tool usage guidance (built-in or MCP)
Error handling and validation
References to bundled files (references/, scripts/, assets/)

Keep this concise and move long documentation to references/.

6) Add references or scripts (optional)

If the workflow needs templates, checklists, or detailed examples, place them in references/ and link them.

7) Test and iterate

Provide a short test plan covering:

Triggering tests (obvious and paraphrased queries)
Non-triggering tests (unrelated queries)
Functional checks for the expected output

Iterate based on under-triggering or over-triggering signals.

Output format

Return:

The folder name
SKILL.md content
Any optional files under references/ or scripts/
A short test plan

Common issues to prevent

Invalid frontmatter or missing required fields
Incorrect SKILL.md filename or folder naming
Overly broad description that causes over-triggering
Missing trigger phrases in description
Missing error handling for known edge cases

Patterns to apply

Use these structure patterns when drafting the skill instructions:

Sequential workflow orchestration: explicit step ordering, dependencies, validation per step, rollback guidance.
Multi-MCP coordination: phase separation, data passing between services, validation before each handoff, centralized error handling.
Iterative refinement: quality criteria, validation scripts, refinement loop with a stopping rule.
Context-aware tool selection: decision tree to choose tools by file type, size, or constraints, and explain the choice.
Domain-specific intelligence: embed specialized checks (compliance, governance, or quality gates) before action.

Troubleshooting guidance

Include a short troubleshooting section when relevant:

Skill will not upload: check SKILL.md spelling and YAML frontmatter delimiters.
Invalid frontmatter: fix YAML formatting and required fields.
Skill does not trigger: make description more specific and add trigger phrases; mention file types if relevant.
Skill triggers too often: add negative triggers and narrow scope.
Instructions not followed: move critical rules to the top and make them explicit.
MCP connection issues: verify connection, auth, tool names, and test MCP independently.
Large context issues: keep SKILL.md under 5,000 words and move detail to references/.

Validation checklist

SKILL.md exists and is case-sensitive
Folder and skill name are kebab-case and match
Frontmatter includes what it does and when to use
Description includes trigger phrases and relevant file types
No README.md inside the skill folder
SKILL.md body under 5,000 words

Suggested resources

When helpful, point users to:

Official skills documentation and best practices
MCP documentation for connected tools
Example skills repository for reference

skill-builder