Skill Format Specification

Complete reference for SKILL.md file format and YAML frontmatter schema

Skills are defined in SKILL.md files with YAML frontmatter. This format follows the Agent Skills specification for cross-agent compatibility.

Basic Structure

A skill consists of a markdown file with YAML frontmatter:

---
name: skill-name
description: What this skill does and when to use it
---

# Skill Title

Instructions for the agent to follow when this skill is activated.

## When to Use

Describe the scenarios where this skill should be used.

## Steps

1. First step
2. Second step
3. Additional steps as needed

YAML Frontmatter Schema

The frontmatter contains metadata that helps agents discover and understand your skill.

Required Fields

name · string · required

Unique identifier for the skill. Must be lowercase with hyphens (kebab-case).

Examples:

• frontend-design
• pr-review-helper
• deploy-to-vercel

Skill names must be unique within a repository. Duplicate names will be skipped during installation.

description · string · required

Brief explanation of what the skill does and when to use it. This appears in skill listings and helps agents decide when to activate the skill.

Best practices:

• Keep it concise (1-2 sentences)
• Focus on the “what” and “when”
• Mention key capabilities or use cases

Example:

description: Helps create and review GitHub pull requests following team conventions and best practices

Optional Fields

metadata · object

Additional metadata for skill behavior and visibility.

Subfields:

metadata.internal · boolean · default: false

Set to true to hide the skill from normal discovery. Internal skills are only visible when INSTALL_INTERNAL_SKILLS=1 is set.

Use cases:

• Work-in-progress skills
• Internal tooling not meant for public use
• Experimental features under development

Example:

metadata:
  internal: true

Markdown Content

The body of the SKILL.md file contains instructions for the agent. Use standard markdown formatting.

Recommended Sections

Skill Title

A clear, descriptive title (H1) that matches or expands on the skill name.

# Frontend Design System

When to Use

Describe scenarios where this skill should be activated.

## When to Use

Use this skill when:
- Creating new UI components
- Implementing design system guidelines
- Ensuring accessibility compliance

Instructions / Steps

Detailed instructions for the agent to follow.

## Instructions

1. Review the design system documentation
2. Identify the appropriate component patterns
3. Implement using the design tokens
4. Verify accessibility requirements

Examples

Code examples or templates (optional but helpful).

## Example

\`\`\`typescript
// Example component implementation
export const Button = ({ variant, children }) => {
  return <button className={styles[variant]}>{children}</button>
}
\`\`\`

Resources

Links to relevant documentation or tools (optional).

## Resources

- [Design System Docs](https://example.com/design-system)
- [Component Library](https://example.com/components)

Complete Example

Here’s a complete example of a well-structured skill:

---
name: pr-review-helper
description: Helps review pull requests by checking code quality, tests, and documentation
---

# Pull Request Review Helper

This skill guides thorough code reviews following best practices.

## When to Use

Activate this skill when:
- Reviewing a teammate's pull request
- Preparing your own PR for review
- Checking if a PR meets merge requirements

## Review Checklist

### Code Quality

1. **Readability**: Is the code easy to understand?
2. **Consistency**: Does it follow project conventions?
3. **Complexity**: Is the logic unnecessarily complex?

### Testing

1. Are new features covered by tests?
2. Do existing tests still pass?
3. Are edge cases considered?

### Documentation

1. Are public APIs documented?
2. Are breaking changes noted?
3. Is the PR description clear?

## Review Comments

When leaving feedback:

- **Be specific**: Point to exact lines and suggest improvements
- **Be kind**: Assume good intent and use collaborative language
- **Be clear**: Distinguish between required changes and suggestions

## Example Feedback

```markdown
**Required:** This function needs error handling for null values.
Suggestion: Consider extracting this logic into a separate helper.

Resources

• Code Review Guidelines
• Testing Best Practices

## Skill Discovery Locations

The Skills CLI searches for `SKILL.md` files in these locations within a repository:

<Tabs>
  <Tab title="Priority Locations">
    These directories are searched first:
    
    - Root directory (if it contains `SKILL.md`)
    - `skills/`
    - `skills/.curated/`
    - `skills/.experimental/`
    - `skills/.system/`
  </Tab>
  
  <Tab title="Agent-Specific">
    Agent configuration directories:
    
    - `.agents/skills/`
    - `.agent/skills/`
    - `.claude/skills/`
    - `.cline/skills/`
    - `.codex/skills/`
    - `.cursor/skills/`
    - `.goose/skills/`
    - And 20+ more agent directories
  </Tab>
  
  <Tab title="Plugin Manifests">
    Skills can also be declared in plugin manifests:
    
    - `.claude-plugin/marketplace.json`
    - `.claude-plugin/plugin.json`
    
    See [Plugin Manifest Discovery](#plugin-manifest-discovery) below.
  </Tab>
  
  <Tab title="Recursive Search">
    If no skills are found in priority locations, the CLI performs a recursive search of the entire repository (excluding `node_modules`, `.git`, etc.).
    
    Use `--full-depth` flag to search all subdirectories even when a root `SKILL.md` exists.
  </Tab>
</Tabs>

## Plugin Manifest Discovery

For compatibility with the [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces), skills can be declared in manifest files:

### `.claude-plugin/marketplace.json`

```json
{
  "metadata": {
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "my-plugin",
      "skills": [
        "./skills/review",
        "./skills/test"
      ]
    }
  ]
}

.claude-plugin/plugin.json

Similar structure for individual plugin definitions.

Skills discovered via plugin manifests are associated with their parent plugin, making it easy to group related skills.

Best Practices

Keep it focused

Each skill should do one thing well. Create multiple focused skills rather than one large skill.

Be specific

Provide concrete instructions and examples. Avoid vague guidance like “follow best practices.”

Use sections

Organize instructions with clear headings and numbered steps. This helps agents parse and follow the guidance.

Test thoroughly

Test your skill with your target agent to ensure it works as expected. Different agents may interpret instructions differently.

Validation Rules

The Skills CLI validates skills during discovery:

1. Frontmatter must be valid YAML

   Use a YAML validator to check syntax. Common issues:

   • Missing closing quotes
   • Incorrect indentation
   • Invalid special characters
2. Required fields must exist

   Both name and description must be present and be strings (not numbers or booleans).

3. Name must be lowercase

   Use kebab-case: my-skill-name (not My Skill Name or my_skill_name)

4. No path traversal in names

   Names cannot contain .., /, or other path manipulation characters.

Skills that fail validation are silently skipped during discovery. Use --list flag to see which skills were found.

Internal Skills

Skills can be hidden from normal discovery:

---
name: experimental-feature
description: Work-in-progress feature for internal testing
metadata:
  internal: true
---

To install internal skills:

INSTALL_INTERNAL_SKILLS=1 npx skills add owner/repo --list
INSTALL_INTERNAL_SKILLS=1 npx skills add owner/repo

Creating a New Skill

Use the init command to create a skill template:

# Create in current directory
npx skills init

# Create in subdirectory
npx skills init my-awesome-skill

This generates a SKILL.md template with proper frontmatter structure.

Related Documentation

CLI Options

Learn how to install and manage skills

Agent Config

Understand agent-specific configurations

Contributing

Guidelines for creating and sharing skills

Agent Skills Spec

Official specification for agent skills