Stats
Actions
Tags
From ideaflow-skills
Step-by-step guide for building high-quality skills for Claude. Use when user asks to "create a skill", "write a SKILL.md", "build a new skill", "convert this into a skill", "skill best practices", "make a skill from this workflow", "help me package this as a skill", or "how do I structure a skill". Covers frontmatter, descriptions, file structure, progressive disclosure, testing, and distribution.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ideaflow-skills:skill-crafting-guideThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A skill is a folder containing instructions that teach Claude how to handle specific tasks or workflows. Instead of re-explaining preferences every conversation, you teach Claude once and benefit every time.
A skill is a folder containing instructions that teach Claude how to handle specific tasks or workflows. Instead of re-explaining preferences every conversation, you teach Claude once and benefit every time.
This guide walks you through building a skill from scratch. Follow these steps in order. For deeper reference material, consult the files in references/.
These are the most costly mistakes. Violating any of these will break your skill or cause silent failures:
my-cool-skill/, the frontmatter must have name: my-cool-skill. A mismatch can cause upload failures or skill-loading errors.SKILL.md (case-sensitive). Not skill.md, not Skill.md.>-, |).references/.Before writing anything, identify 2-3 concrete use cases your skill should enable.
Write them down in this format:
Use Case: [Name]
Trigger: User says "[example phrase]" or "[example phrase]"
Steps:
1. [First action]
2. [Second action]
3. [Third action]
Result: [Expected outcome]
Ask yourself:
Decide: generic or project-specific?
YOUR_API_KEY, YOUR_TEAM_ID), write for broad audiences, and are suitable for public distribution.disable-model-invocation: true, and are valid when the skill is a reference card for a specific deployment or codebase.Three common skill categories:
your-skill-name/ # kebab-case, no spaces/underscores/capitals
SKILL.md # Required - main skill file (exact spelling)
scripts/ # Optional - executable code (Python, Bash, etc.)
references/ # Optional - documentation loaded as needed
assets/ # Optional - templates, fonts, icons
Critical naming rules:
name field in frontmatter. This is the single most common breaking error. If the folder is notion-project-setup/, the frontmatter must say name: notion-project-setup.notion-project-setup is correct. Notion Project Setup, notion_project_setup, NotionProjectSetup are all wrong.launching-ios-app is preferred over ios-app-launcher. processing-pdfs over pdf-processor. This follows Anthropic's recommended convention. However, matching folder name to name field is MORE important than gerund convention -- never create a mismatch to achieve a gerund name.SKILL.md (case-sensitive). Not skill.md, not SKILL.MD.The frontmatter is how Claude decides whether to load your skill. This is the most important part to get right.
---
name: your-skill-name
description: What it does and when to use it. Include trigger phrases.
---
Required fields:
name - kebab-case, no spaces or capitals. MUST match folder name exactly.description - Must include WHAT the skill does AND WHEN to use it (trigger conditions). Under 1024 characters. Use a single-line string.The description formula:
[What it does] + [When to use it] + [Key capabilities]
Write descriptions that include specific task phrases users would actually say. Mention relevant file types if applicable. See references/description-examples.md for good and bad examples.
Optional fields: license, compatibility, allowed-tools, disable-model-invocation, metadata (author, version, mcp-server, category, tags). See references/yaml-frontmatter.md for the complete reference.
When to use disable-model-invocation: true:
When set, Claude cannot auto-trigger the skill. Users must invoke it manually via /skill-name.
Security restrictions - NEVER include:
After the frontmatter closing ---, write the actual instructions in Markdown.
Recommended structure:
# Your Skill Name
## Instructions
### Step 1: [First Major Step]
Clear explanation of what happens.
### Step 2: [Next Step]
Include specific commands, parameters, or actions.
## Examples
### Example 1: [Common scenario]
User says: "[trigger phrase]"
Actions:
1. [Action]
2. [Action]
Result: [Outcome]
## Common Issues
### [Error type]
If you see "[error message]":
1. [Fix step]
2. [Fix step]
Best practices for instructions:
Run python scripts/validate.py --input {filename} not Validate the data before proceeding.Before writing queries, consult references/api-patterns.md for rate limiting guidance## Important or ## Critical headersAvoid ambiguous language:
Bad: Make sure to validate things properly
Good: CRITICAL: Before calling create_project, verify: project name is non-empty, at least one team member assigned, start date is not in the past
Skills use a three-level system to minimize token usage:
The rule: Keep SKILL.md focused on core instructions. Keep it under 500 lines / 5,000 words. Move detailed documentation, API references, extended examples, and lookup tables to references/ and link to them from SKILL.md.
Token economics: Every token in a skill competes with conversation history. Do not explain things Claude already knows (what JWT is, how REST APIs work, basic programming concepts). Only add context Claude does not have: specific endpoints, non-obvious field types, gotchas from real experience.
The "router SKILL.md" pattern (recommended): Keep SKILL.md as a lean ~120-200 line overview that routes to reference files. Include a workflow overview table, the top 5-7 critical gotchas, and a reference index. All detailed code, API documentation, and extended procedures live in reference files. This minimizes the token footprint when the skill loads while still providing enough context to start working.
The "climax step" exception: If your skill has one critical step that is the whole point of the workflow (e.g., the final submission call, the deploy command), keep that code directly in SKILL.md even when everything else is in references. Claude needs the most important step without an extra file read.
Surfacing critical info at level 2: Always put the top 5-7 most important items (gotchas, warnings, breaking issues) directly in SKILL.md, even when a reference file has the full list. This prevents the most costly mistakes without requiring reference file loads.
How you organize reference files matters for Claude's ability to find and load the right content.
Split by DOMAIN, not by phase number. Claude navigates by relevance, not sequence. When a user asks about screenshot errors, Claude should load gotchas.md, not phase-6.md.
Recommended guidelines:
api-setup.md not phase-2.md. gotchas-and-errors.md not appendix-a.md.When you have related skills (e.g., a generic workflow skill and a project-specific reference skill), use negative triggers to point users to the right one:
# In the generic skill's description:
description: ... Do NOT use for Cortex-specific builds -- use app-store-submission-guide instead.
# In the project-specific skill's description:
description: ... Do NOT use for general iOS app publishing -- use ios-app-store-launch instead.
Most skills follow one of five proven patterns. Pick the one that fits your use case. See references/patterns.md for full examples of each.
| Pattern | Use When |
|---|---|
| Sequential Workflow | Multi-step processes in a specific order |
| Multi-MCP Coordination | Workflows spanning multiple services |
| Iterative Refinement | Output quality improves with iteration |
| Context-Aware Tool Selection | Same outcome, different tools depending on context |
| Domain-Specific Intelligence | Specialized knowledge beyond tool access |
| Router SKILL.md | Complex skills with many reference files |
Problem-first vs. Tool-first framing:
Before considering your skill complete, run through this checklist. See references/quick-checklist.md for the full version with severity ratings.
CRITICAL (breaks skill if violated):
name field matches folder name exactly--- delimiters (opening and closing)HIGH (degrades quality significantly):
description includes WHAT and WHEN with trigger phrasesMEDIUM (optimization):
disable-model-invocation: true for side-effect workflowsTriggering checks:
See references/testing-guide.md for the full testing methodology. The short version:
Pro tip: Iterate on a single task before expanding. Get one workflow working perfectly, then extract the winning approach into a skill.
Iteration signals:
See references/distribution-guide.md for full details.
For individual use: Place in Claude Code skills directory or upload via Claude.ai Settings at Capabilities then Skills.
For teams: Admins can deploy skills workspace-wide with automatic updates and centralized management.
For public sharing:
For programmatic use: The API provides /v1/skills endpoint and container.skills parameter for the Messages API.
Folder is my-cool-skill/ but frontmatter says name: cool-skill-helper. Fix: make them identical. The name field MUST match the folder name exactly.
SKILL.md (case-sensitive). Verify with ls -la.--- delimiters, unclosed quotes, or other YAML formatting errors.Revise description field. Ask: Is it too generic? Does it include trigger phrases users would actually say? Does it mention relevant file types?
Description debugging technique: Ask Claude "When would you use the [skill name] skill?" Claude will quote the description back. Compare what it says with what you intended. Adjust based on the gap.
Keep instructions concise. Use bullet points. Put critical instructions at the top. Move detailed reference to separate files. Consider bundling validation scripts for critical checks.
For the complete troubleshooting reference, see references/troubleshooting.md.
npx claudepluginhub ideaflowco/ideaflow-skills-marketplace --plugin ideaflow-skillsStep-by-step walkthrough for designing, writing, testing, and maintaining Claude Skills, including how to write trigger descriptions and structure SKILL.md files.
Guides creating effective, portable skills with YAML frontmatter, markdown instructions, and bundled resources. Useful when authoring or updating skills.
Guides creation, improvement, auditing, testing, and distribution of Claude Code skills using Anthropic's official methodology.