Browse Trending New Collections Plugins Docs Blog
Sign In
● BLOG
← All posts

How to Create Your First Agent Skill (Step-by-Step)

8 min read

Agent skills are the most powerful way to customize AI coding tools. A single SKILL.md file can teach Claude Code, Cursor, Codex, or any of 16+ AI tools exactly how to work with your stack, enforce your conventions, and automate your workflows. Here’s how to create one from scratch.

What is an agent skill?

An agent skill is a markdown file (SKILL.md) that lives in your project’s .claude/skills/ directory. When an AI coding tool encounters it, the skill’s instructions become part of the agent’s context—giving it domain-specific knowledge it wouldn’t otherwise have.

Skills can range from simple (a one-page coding convention guide) to complex (a multi-agent game development studio with 48 specialized roles). The format is the same either way: a markdown file with YAML frontmatter.

Step 1: Create the directory structure

Every skill lives inside .claude/skills/. Create the directory and your skill file: 

mkdir -p .claude/skills
touch .claude/skills/SKILL.md

That’s the minimum. A skill is just a markdown file. You can also include supporting assets (scripts, reference docs, templates) alongside it: 

.claude/
├── skills/
│   ├── SKILL.md           # Main skill definition
│   ├── templates/         # Code templates the skill references
│   │   └── component.tsx
│   └── references/        # Documentation the agent can consult
│       └── api-spec.md
├── agents/                # Subagent definitions (optional)
├── hooks/                 # PreToolUse/PostToolUse hooks (optional)
├── rules/                 # Project rules (optional)
└── docs/                  # Reference documentation (optional)

Step 2: Write the frontmatter

The frontmatter tells AI tools when and how to activate your skill. Open .claude/skills/SKILL.md and add: 

---
name: my-react-conventions
description: Enforce our team's React conventions — file structure,
  naming patterns, testing requirements, and component architecture.
---

The name is a unique identifier (lowercase, hyphens). The description is critical—AI tools use it to decide when this skill is relevant. Be specific about what the skill does and when it should activate.

Step 3: Write the skill body

Below the frontmatter, write natural-language instructions. Be direct and specific. The AI agent will follow these instructions whenever the skill activates. 

# React Conventions

## File structure
- Components go in `src/components/{ComponentName}/`
- Each component folder has: `index.tsx`, `styles.module.css`, `test.tsx`
- Shared hooks go in `src/hooks/`
- No barrel exports — import directly from the component file

## Naming
- Components: PascalCase (`UserProfile.tsx`)
- Hooks: camelCase with `use` prefix (`useAuth.ts`)
- Utils: camelCase (`formatDate.ts`)

## Testing
- Every component must have a co-located test file
- Use React Testing Library, not Enzyme
- Test behavior, not implementation — query by role, not by class name
- Minimum: one render test, one interaction test per component

## Architecture rules
- No prop drilling beyond 2 levels — use context or state management
- Keep components under 150 lines — extract subcomponents if larger
- All API calls go through `src/api/` — never fetch directly in components

Notice the pattern: clear headers, specific rules, concrete examples. The more precise your instructions, the more reliably the AI will follow them.

Step 4: Test it locally

With the file saved in .claude/skills/SKILL.md, your skill is already active. Open Claude Code (or your AI tool of choice) in the same project directory and test it:

  • Ask the agent to create a new React component. Does it follow your file structure?
  • Ask it to write a test. Does it use React Testing Library and test behavior?
  • Ask it to refactor a component that’s too long. Does it extract subcomponents?

Iterate on the wording until the agent consistently follows your conventions. Skills are just text—you can edit and re-test in seconds.

Step 5: Add compatibility metadata (optional)

If you want your skill to be discoverable and filterable on Skill Vault, add compatibility tags to your frontmatter: 

---
name: my-react-conventions
description: Enforce our team's React conventions.
tools:
  - claude-code
  - cursor
  - codex
  - github-copilot
category: webdev
tags:
  - react
  - conventions
  - testing
---

Step 6: Publish to Skill Vault

Once your skill is working locally, share it with every developer who uses AI coding tools. Publishing takes under a minute:

  1. Push to GitHub. Make sure your .claude/ directory is committed to a public repo.
  2. Sign in to Skill Vault with your GitHub account.
  3. Import from GitHub. Paste your repo URL and we’ll automatically detect your SKILL.md, agents, hooks, rules, and docs.
  4. Review & publish. Add a tagline, choose a category, and hit publish.

Your skill is now searchable, installable, and discoverable by thousands of developers. Anyone can install it with: 

sv install your-username/my-react-conventions

Tips for writing great skills

  • Be specific, not vague. “Use good naming conventions” is useless. “Components use PascalCase, hooks use camelCase with use prefix” is actionable.
  • Include examples. Show the agent what good output looks like. A code snippet is worth a paragraph of explanation.
  • Set boundaries. Tell the agent what NOT to do. “Never use Enzyme” is as important as “use React Testing Library.”
  • Keep it focused. A skill that covers React conventions should not also cover database migrations. Create separate skills for separate domains.
  • Update regularly. Tools and frameworks evolve. A skill written for React 18 may need updates for React 19. Version your changes in the changelog.

Beyond skills: the full .claude/ ecosystem

Skills are just one part of the agent configuration ecosystem. The .claude/ directory supports:

  • Agents (.claude/agents/): Subagent definitions with specific roles and tool access.
  • Hooks (.claude/hooks/): Scripts that run before or after tool calls—great for validation, formatting, or logging.
  • Rules (.claude/rules/): Project-wide conventions that apply regardless of which skill is active.
  • Docs (.claude/docs/): Reference documentation the agent can consult when it needs context.

You can bundle all of these into a single Skill Vault package. The Claude Code Game Studios package is a great example—it ships skills, agents, hooks, rules, and docs together as one cohesive game development environment.

Start building

The Agent Skills ecosystem is young, and the best packages haven’t been built yet. Whatever domain you know well—React, DevOps, data science, game development, security—there are developers who need a skill for it.

Create your .claude/skills/SKILL.md, test it, and publish it on Skill Vault. It takes minutes, and your skill will be installable by any developer using any of 16+ AI coding tools.

PUBLISH YOUR SKILL