How to Create Custom AI Agent Skills

Creating your own AI agent skills is a powerful way to standardize workflows, share knowledge, and contribute to the open-source community. If you're new to Skills, check out our guide on what Agent Skills are first.

Understanding the SKILL.md Format

A SKILL.md file is a markdown document with YAML frontmatter that provides structured instructions for AI assistants. According to Anthropic's official specification, every Skill requires two key fields:

• name: A short identifier (max 64 characters, lowercase with hyphens)
• description: When to use this skill (max 1024 characters)

Here's the basic structure:

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it.
---

# Your Skill Name

## Instructions
Step-by-step instructions for the AI to follow.

## Examples
Concrete examples of inputs and expected outputs.

Skill Directory Structure

For more complex skills, you can organize additional resources in a directory:

my-skill/
├── SKILL.md          # Required: main instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: additional documentation
└── assets/           # Optional: templates, resources

This structure enables progressive disclosure—the agent loads information in stages as needed, keeping the context window efficient.

Step-by-Step Guide

1. Identify the Use Case

Start by identifying a specific, repeatable task that you want to automate or standardize:

• What problem does this skill solve?
• Who is the target audience?
• What are the expected inputs and outputs?
• How often will this skill be used?

2. Write Clear Instructions

AI assistants work best with clear, unambiguous instructions. Be specific about workflows and best practices:

## Instructions

When asked to create a React component:

1. Use functional components with TypeScript
2. Include prop type definitions
3. Add JSDoc comments for documentation
4. Follow the project's naming conventions
5. Include basic error handling

3. Provide Concrete Examples

Examples help the AI understand the expected format and quality. Include both inputs and outputs:

## Example

**Input:** Create a button component

**Output:**
\`\`\`tsx
interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
}

export function Button({ label, onClick, variant = 'primary' }: ButtonProps) {
  return (
    <button 
      className={`btn btn-${variant}`}
      onClick={onClick}
    >
      {label}
    </button>
  );
}
\`\`\`

4. Test Your Skill

Before publishing, test your skill thoroughly:

• Try various inputs to ensure consistent behavior
• Check edge cases and error scenarios
• Verify the output quality meets your standards
• Get feedback from colleagues or community members

Best Practices

Following Anthropic's authoring guidelines, here are key recommendations:

1. Write descriptive descriptions: Include both what the skill does and when to use it
2. Keep instructions focused: One skill should handle one domain well
3. Use progressive disclosure: Reference additional files for complex workflows
4. Include error handling: Guide the AI on what to do when things go wrong
5. Version your skills: Use Git to track changes and improvements

Publishing Your Skill

Once your skill is ready, share it with the community:

1. Create a GitHub repository for your skill
2. Add your SKILL.md file (and any supporting files)
3. Write a clear README explaining the skill's purpose
4. Submit to the Awesome Skills directory for discovery
5. Consider contributing to Anthropic's official skills repository

Conclusion

Creating custom skills is a powerful way to leverage AI assistants for your specific needs. Start with simple skills and gradually build more complex ones as you gain experience.

Ready to explore existing skills for inspiration? Browse our curated collection of community-contributed skills.