What are AI agent skills?

Have you ever asked your AI coding agent to “write tests for this module,” only for it to write something completely generic that ignores your project’s unique architecture?

What is an AI Agent Skill?

An AI agent skill is a specialized markdown file (typically named SKILL.md) that provides domain-specific instructions to coding assistants like Claude, Cursor, and Windsurf. By placing these files in your project directory, agents automatically learn your specific conventions, workflows, and rules without requiring repetitive prompting.

* How AI agent skills actually function under the hood * Where to place skill files for different IDEs (Claude, Cursor, Windsurf) * The sweet spot for when skills are most effective * How to install community skills via the CLI * Best practices for writing your own custom skills

.claude/skills/
  testing/SKILL.md       # how to write tests in this project
  deployment/SKILL.md    # deployment checklist and configs
  code-review/SKILL.md   # what to look for in reviews

The agent reads the file when the topic comes up, then follows those instructions instead of guessing.

How they actually work

There is no magic here. A skill file has two parts:

Frontmatter with a name and description (so the agent knows when to load it)
Instructions written in plain markdown (the actual knowledge)

Here is a real example, trimmed down:

---
name: testing
description: How to write and run tests in this project
---

# Testing in this project

We use Vitest. Run tests with `npm test`.

Rules:
- Every new function needs at least one test
- Mock external APIs, never call them in tests
- Put test files next to the source: `utils.test.ts` beside `utils.ts`

That is the whole format. The agent loads this file, reads the instructions, and changes its behavior accordingly. No SDK, no API calls, no configuration beyond the file itself.

Where skills run

Right now, several coding agents support SKILL.md files or something similar:

Agent	Skill location	How it works
Claude Code	`.claude/skills/`	Reads skills automatically based on context
Cursor	`.cursor/rules/`	Project-level rule files
Windsurf	`.windsurfrules`	Single rules file at project root
GitHub Copilot	`.github/copilot-instructions.md`	Repository-level instructions

The format is converging. A skill written for Claude usually works in Cursor with minor path changes.

When skills actually help (and when they don’t)

Skills work well for project-specific conventions that an AI cannot guess on its own. Things like:

Your deployment process has 6 steps and two of them require manual approval
Your team uses a specific error-handling pattern everywhere
Database queries need to go through a certain abstraction layer
Tests should follow a particular naming convention

Skills don’t help much when the task is generic enough that any competent developer (or AI) would handle it the same way. You don’t need a skill for “how to write a for loop.”

The sweet spot is knowledge that lives in your team’s heads but hasn’t been written down anywhere. Skills force you to document it, and then the AI can follow it too.

Finding skills you can use today

You can write your own skills from scratch, but there are also community skills available for common tasks:

docx - Generate and edit Word documents
pdf - Read, merge, split, and create PDFs
xlsx - Work with spreadsheets and formulas
mcp-builder - Build MCP servers for agent integrations
frontend-design - Create polished web interfaces

You install them with one command:

npx killer-skills add anthropics/skills/pdf

This copies the SKILL.md file into your project’s skills directory. The agent picks it up on the next conversation.

Writing your own skills

The best skills come from frustration. When your agent keeps doing something wrong, that is a signal you need a skill for it.

Start small. Write 10 lines about one specific thing. “When writing API routes in this project, always use our withAuth wrapper and return errors in this format.” That single instruction can save you from correcting the agent every time.

Over time, the file grows as you add more rules. Some of our most useful internal skills started as 5-line notes and grew into full reference documents.

What comes next

Skills are still early. The format is not standardized across all agents, error handling is primitive, and discoverability is limited. But the core idea (giving your AI assistant written instructions about your project) is here to stay.

If you want to browse existing skills or publish your own, check out the skill directory. There are currently over 1,000 community-contributed skills covering everything from database management to UI design.