How to Create Your First Agent Skill for Claude Code

What Is an Agent Skill?

An Agent Skill is a Markdown file (typically SKILL.md or *.skill.md) that teaches an AI coding agent how to perform a specific task. Think of it as a reusable prompt with structure — it tells the agent what to do, when to activate, and how to execute.

Unlike MCP servers (which require code and a running process) or custom rules (which are simple text constraints), agent skills sit in a sweet spot: powerful enough to encode complex workflows, simple enough that anyone can create one.

Who Uses Agent Skills?

• Claude Code — looks for SKILL.md files in .claude/commands/ or project root
• OpenAI Codex CLI — reads AGENTS.md files
• Gemini CLI — reads GEMINI.md files
• Cursor — reads .cursorrules files

The SKILL.md format works across all of these with minor adaptations.

Prerequisites

Before you start, make sure you have:

1. An AI coding agent installed — Claude Code, Codex CLI, or similar
2. A text editor — VS Code, Cursor, or any editor you prefer
3. A project directory — any folder where you want the skill available

Step 1: Create the SKILL.md File

Create a new file called SKILL.md in your project root (or in .claude/commands/ for Claude Code).

# Option A: Project root (works everywhere)
touch SKILL.md

# Option B: Claude Code commands directory
mkdir -p .claude/commands
touch .claude/commands/my-skill.md

The file name matters:

• SKILL.md — auto-discovered by agents scanning the project
• .claude/commands/code-review.md — becomes the /code-review slash command in Claude Code
• *.skill.md — recognized by TokRepo for publishing

Step 2: Define the Metadata

Every good skill starts with clear metadata in a YAML frontmatter block:

---
name: Code Review Skill
description: Performs adversarial code review on changed files
triggers:
  - /code-review
  - "review my code"
  - "check for bugs"
---

The key fields:

Step 3: Write the Instructions

The body of your SKILL.md is the actual prompt. Write it as clear instructions for the AI agent:

## Goal

Review all changed files in the current branch for bugs, security issues,
and code quality problems.

## Steps

1. Run `git diff --name-only HEAD~1` to find changed files
2. Read each changed file completely
3. For each file, check for:
   - Logic errors and edge cases
   - Security vulnerabilities (injection, auth bypass, etc.)
   - Performance issues (N+1 queries, unnecessary loops)
   - Code style violations
4. Output a structured report with severity levels

## Output Format

For each issue found:
- **File**: path/to/file.ts
- **Line**: 42
- **Severity**: 🔴 High | 🟡 Medium | 🟢 Low
- **Issue**: Description of the problem
- **Fix**: Suggested fix

Tips for Great Instructions

1. Be specific — "Check for SQL injection in all database queries" beats "look for security issues"
2. Use numbered steps — agents follow ordered lists more reliably than paragraphs
3. Include examples — show the expected output format
4. Set boundaries — tell the agent what NOT to do (e.g., "Do not modify any files, only report")

Step 4: Test Locally

Test your skill by invoking it in your AI agent:

In Claude Code:

# If placed in .claude/commands/code-review.md
claude /code-review

# If placed as SKILL.md in project root
claude "use the code review skill"

In Codex CLI:

codex "review my code using the skill in SKILL.md"

Iterate on the instructions based on the results. Common adjustments:

• Add more specific examples if the output format is wrong
• Add constraints if the agent is doing too much or too little
• Add error handling instructions for edge cases

Step 5: Publish to TokRepo

Once your skill works well locally, share it with the community:

# Install TokRepo CLI
npm install -g tokrepo

# Login with your API token
tokrepo login

# Push your skill
tokrepo push my-skill.skill.md --public

Your skill is now searchable and installable by anyone:

# Others can find and install it
tokrepo search "code review"
tokrepo install your-skill-name

FAQ

Can I use images or diagrams in my skill?

Yes, but most AI agents process skills as text only. Images are useful for documentation on TokRepo but won't be "seen" by the agent during execution.

How long should a skill be?

Most effective skills are 200-500 lines. Too short and the agent lacks context; too long and it may lose focus. If your skill exceeds 1000 lines, consider splitting it into multiple skills.

Can skills call other skills?

Not directly, but you can reference other skills in your instructions: "If you need to run tests, follow the testing skill at .claude/commands/test.md". The agent will read and follow those instructions.

What's the difference between SKILL.md and AGENTS.md?

SKILL.md is a single-purpose skill file. AGENTS.md is a project-level file that describes the overall project context and available capabilities. You can reference skills from within AGENTS.md.

How do I update a published skill?

# Update by UUID
tokrepo update <uuid> my-skill.skill.md

# Or use sync to auto-detect changes
tokrepo sync .

Related Skills on TokRepo

Explore these popular skills for inspiration: