Skip to main content
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.
A clear, descriptive title (H1) that matches or expands on the skill name.
# Frontend Design System
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
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
Code examples or templates (optional but helpful).
## Example

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


## 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.

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

Build docs developers (and LLMs) love

Get started for freeTalk to us