The Complete Guide to Building a Skill

What is a Skill?

A skill is a folder containing:

• SKILL.md (required): The main instruction file in Markdown with YAML frontmatter
• SKILL_HE.md (required for Skills IL): Hebrew version of the instructions
• metadata.json (required for Skills IL): Bilingual metadata (name, description, tags, category)
• scripts/ (optional): Executable code (Python, Bash, etc.)
• references/ (optional): Documentation loaded as needed
• assets/ (optional): Templates, fonts, icons used in output

Tip: Skip the manual setup. The Skill Creator generates a SKILL.md from a plain-language description.

Core Design Principles

Progressive Disclosure

Skills use a three-level system:

• First level (YAML frontmatter): Always loaded in the agent's system prompt. Provides just enough information for the agent to know when each skill should be used without loading all of it into context.
• Second level (SKILL.md body): Loaded when the agent determines the skill is relevant to the current task. Contains the full instructions and guidance.
• Third level (Linked files): Additional files bundled within the skill directory that the agent can navigate and discover only as needed.

Explain the Why

Effective skills don't just tell the agent what to do, but why. When the agent understands the intent behind an instruction, it can adapt to different contexts and unexpected situations. Instead of "Use DD/MM/YYYY format", write "Use DD/MM/YYYY format because this is the standard format in Israel, and using the American format could cause date errors."

Skill Types

Recognize the two main types of skills:

• Workflow Skills: Define a sequence of steps for completing a task. For example: "How to file a VAT report". These skills are highly portable across agents because they are based purely on textual instructions.
• Capability Skills: Rely on specific tools and capabilities of the agent (such as running Bash, file access, MCP tools). These skills may behave differently across agents depending on the tools available.

When writing a skill, ask yourself: Is this a sequence of instructions any agent can follow, or does it depend on specific tools? The answer will affect the level of portability.

Composability

AI agents can load multiple skills simultaneously. Your skill should work well alongside others, not assume it's the only capability available.

Portability

Skills work across all supported AI agents: Claude Code, Cursor, GitHub Copilot, Windsurf, OpenCode, Codex, OpenClaw, and Antigravity. Create a skill once and it works across all platforms without modification, provided the environment supports any dependencies the skill requires.

To maximize portability:

• Describe intents, not tools - Write "Check the file for syntax errors" instead of "Run eslint src/"
• Bundle scripts - If the skill requires complex operations, put them in a script in the scripts/ directory instead of assuming the agent has a specific tool
• Declare dependencies explicitly - If the skill requires an MCP or external tool, state it in the compatibility field and in the instructions

For a comprehensive guide on cross-agent portability, see the Multi-Agent Compatibility Guide.

Technical Requirements

File Structure

Critical Rules

SKILL.md naming:

• Must be exactly SKILL.md (case-sensitive)
• No variations accepted (SKILL.MD, skill.md, etc.)

Skill folder naming:

• Use kebab-case: notion-project-setup
• No spaces: Notion Project Setup
• No underscores: notion_project_setup
• No capitals: NotionProjectSetup

No README.md:

• Don't include README.md inside your skill folder
• All documentation goes in SKILL.md or references/
• When distributing via GitHub, you'll still want a repo-level README for human users (outside the skill folder)

YAML Frontmatter

The YAML frontmatter is how the agent decides whether to load your skill. Get this right.

Minimal Required Format

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

Required Fields

name (required):

• kebab-case only
• No spaces or capitals
• Should match folder name

description (required):

• MUST include BOTH:
  • What the skill does
  • When to use it (trigger conditions)
• Under 1024 characters
• No XML tags
• Include specific tasks users might say

Optional Fields

• license: MIT, Apache-2.0
• compatibility: Environment requirements (up to 500 characters)

Examples of Good Descriptions

# Good - specific and actionable
description: Analyzes Figma design files and generates developer
  handoff documentation. Use when user uploads .fig files, asks
  for "design specs" or "design-to-code handoff".

# Good - includes trigger phrases
description: Manages Linear project workflows including sprint
  planning, task creation, and status tracking. Use when user
  mentions "sprint", "Linear tasks", or "project planning".

# Bad - too vague
description: Helps with projects.

# Bad - missing triggers
description: Creates sophisticated documentation systems.

Security Restrictions

Forbidden in frontmatter:

• XML angle brackets (< or >)
• Skills with "claude" or "anthropic" in name (reserved)

Writing Effective Instructions

Recommended Structure

---
name: your-skill
description: [...]
---

# Your Skill Name

## Instructions

### Step 1: [First Major Step]
Clear explanation of what happens.

Example:
python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [describe what success looks like]

## Examples

### Example 1: [common scenario]
User says: "Set up a new marketing campaign"
Actions:
1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters
Result: Campaign created with confirmation link

## Troubleshooting

### Error: [Common error message]
**Cause:** [Why it happens]
**Solution:** [How to fix]

Best Practices

Be Specific and Actionable:

# Good
Run \`python scripts/validate.py --input {filename}\` to check data format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)

# Bad
Validate the data before proceeding.

Include Error Handling:

## Common Issues

### MCP Connection Failed
If you see "Connection refused":
1. Verify MCP server is running
2. Confirm API key is valid
3. Try reconnecting

Use Progressive Disclosure:

Keep SKILL.md focused on core instructions. Move detailed documentation to references/ and link to it.

Common Skill Use Case Categories

Category 1: Document & Asset Creation

Used for creating consistent, high-quality output: documents, presentations, apps, designs, code.

• Embedded style guides and brand standards
• Template structures for consistent output
• Quality checklists before finalizing

Category 2: Workflow Automation

Used for multi-step processes with consistent methodology.

• Step-by-step workflow with validation gates
• Templates for common structures
• Iterative refinement loops

Category 3: MCP Enhancement

Used for workflow guidance to enhance the tool access an MCP server provides.

• Coordinates multiple MCP calls in sequence
• Embeds domain expertise
• Error handling for common MCP issues

Define Success Criteria

Quantitative Metrics

• Skill triggers on 90% of relevant queries
• Completes workflow in X tool calls
• 0 failed API calls per workflow

Qualitative Metrics

• Users don't need to prompt the agent about next steps
• Workflows complete without user correction
• Consistent results across sessions

Skills IL Requirements

If you want to publish your skill on Skills IL, there are additional requirements beyond the base standard.

metadata.json

A required file containing bilingual metadata for your skill. It's separate from the SKILL.md frontmatter because some agents (e.g., Claude Desktop) don't support metadata fields in YAML.

{
  "author": "github-username",
  "version": "1.0.0",
  "category": "developer-tools",
  "tags": {
    "he": ["אוטומציה", "כלי פיתוח"],
    "en": ["automation", "dev-tools"]
  },
  "display_name": {
    "he": "שם הסקיל בעברית",
    "en": "Skill Name in English"
  },
  "display_description": {
    "he": "תיאור קצר בעברית",
    "en": "Short description in English"
  },
  "supported_agents": ["claude-code", "cursor", "github-copilot", "windsurf", "opencode", "codex", "openclaw", "antigravity", "gemini-cli"]
}

Required fields:

• display_name and display_description - in both languages, with natural Hebrew (not literal translations)
• tags - equal-length arrays in Hebrew and English, no empty strings
• category - the category slug (e.g., tax-and-finance, developer-tools)
• supported_agents - list of compatible agents
• author - GitHub username
• version - semver format (e.g., 1.0.0)

SKILL_HE.md

A Hebrew version of the instructions. Must match the SKILL.md structure one-to-one: same headings, same sections, same order. This is not just a translation but an adaptation for the Israeli audience.

Automated Validation

Every category repo runs validate-skill.sh in CI. It checks:

1. SKILL.md file exists (case-sensitive)
2. Valid frontmatter with name and description
3. kebab-case name matching folder name
4. Description contains a trigger phrase (e.g., "Use when", "When user")
5. SKILL.md body under 5,000 words
6. No README.md in skill folder
7. No "claude" or "anthropic" in name
8. No hardcoded secrets
9. metadata.json exists with bilingual display_name
10. SKILL_HE.md exists

Tip: Run the validation locally before submitting to save CI round-trips.

Submit to the Platform

Once the skill is ready and passes validation, submit it for security review and publication on Skills IL. You can also use the Skill Creator to generate and iterate on skills.