How to Create Your Own Agent Skills [Complete SKILL.md Guide]

After using existing skills, you might think "I want a skill that fits my workflow."

Agent Skills can be created just by writing a SKILL.md file. No programming required—if you can write documentation, you can create skills.

This article covers the process from creating to publishing your own skills.

Skill Creation Basics

Minimal Structure

A skill only needs one SKILL.md file:

Copymy-skill/
└── SKILL.md

How to Write SKILL.md

Copy---
name: daily-standup
description: Create a summary for daily standup meetings
---

## Purpose

Generate a summary to share at team standup meetings.

## Steps

1. Check yesterday's commit history
2. List in-progress PRs
3. Generate summary in the following format

## Output Format

### What I did yesterday
- [Commit contents as bullet points]

### What I'm doing today
- [Inferred from PR status]

### Blockers
- [If none, write "None"]

Section Roles

Advanced Skill Structure

Adding Reference Files

Larger skills can split details into separate files:

Copymy-skill/
├── SKILL.md
└── references/
    ├── coding-standards.md
    └── review-checklist.md

Reference from SKILL.md:

Copy## Detailed Rules

See `references/coding-standards.md` for coding standards.

Adding Scripts

You can include executable scripts:

Copymy-skill/
├── SKILL.md
└── scripts/
    └── generate-report.sh

However, script execution varies by tool. Works in Claude Code but may not work in other tools.

Adding Templates

Provide templates for Claude to fill in:

Copymy-skill/
├── SKILL.md
└── templates/
    └── pr-description.md

Writing Good Descriptions

The description is crucial—Claude uses it to decide whether to auto-apply the skill.

Bad Example

Copydescription: Check code

Too vague to know when to use.

Good Example

Copydescription: Review TypeScript pull requests for security, performance, and type safety

Specific enough to auto-apply for related tasks.

Tips

• State clearly what the skill does
• Write so readers can imagine when to use it
• Include keywords ("PR", "review", "TypeScript", etc.)

Best Practices

Keep Size Small

• SKILL.md body: Under 5,000 tokens
• Line count: Under 500 lines

If it gets larger, split details into references/.

One Skill, One Responsibility

A skill that "reviews code AND writes tests AND deploys" is too complex. Split into separate skills.

Write Specific Instructions

Copy# ❌ Vague
Check the code.

# ⭕ Specific
1. Check for unused imports
2. List any usage of 'any' type
3. Check for remaining console.log statements

Show Expected Output

Copy## Output Example

```json
{
  "issues": [
    {
      "file": "src/index.ts",
      "line": 42,
      "type": "unused-import",
      "message": "'lodash' is imported but never used"
    }
  ]
}

Copy
## Testing Your Skill

### 1. Place Locally

```bash
mkdir -p ~/.claude/skills/my-skill
cp SKILL.md ~/.claude/skills/my-skill/

2. Invoke in Claude Code

Copy/my-skill

Or try requesting a related task in natural language.

3. Verify Behavior

• Is the skill recognized? (Check with /skills)
• Does it produce expected output?
• Does it work for edge cases?

Publishing Your Skill

Publishing on GitHub

1. Create a new repository
2. Push SKILL.md and related files
3. Document usage in README
4. (Optional) Submit to Skill Gallery

README Should Include

• Skill overview
• Installation instructions
• Usage examples
• Supported tools (Claude Code, Codex CLI, etc.)
• License

FAQ

Skill Not Working

• Verify frontmatter name is correct
• Verify filename is SKILL.md (uppercase)
• Verify directory structure is correct

Want It to Work Across Tools

The basic SKILL.md format is shared, but execution features like scripts/ vary by tool. For maximum compatibility, make skills that work with just the SKILL.md body.

Summary

Agent Skills can be created just by writing a SKILL.md file.

1. Write frontmatter (name, description)
2. Write instructions in the body
3. Place locally and test
4. Publish on GitHub

Start by choosing one task you repeat often and turn it into a skill.

Browsing the Skills list for inspiration is also recommended.

Related Articles

• How to Share Skills with Your Team - Use your skills across the team
• Skill Security Best Practices - Create safe skills
• 7 Tips for Better Productivity - Master skill usage
• Migrating from CLAUDE.md - Convert existing config to skills