AI Agent Skills — a practical guide

What they are, how to use them, and where to find them

What is a "skill"? A skill is a small, reusable instruction file (usually SKILL.md) that teaches an AI coding agent how to perform a specific task — following your team's conventions. When a request matches a skill's description, the agent loads it and follows it.

How skills work

Leading AI coding agents (like Claude Code, Cursor and other capable agents) support project-level skills. A skill lives in a folder with a SKILL.md file that has two parts:

Frontmatter — a name and a third-person description that says what the skill does and when to use it (with trigger words).
Instructions — the actual rules, examples and conventions the agent should follow.

Because only the description is always loaded, skills are efficient: the full body loads on demand (progressive disclosure).

Skill categories

🧪

Testing

How to write tests in your repo — patterns, fixtures, commands.

🎨

Frontend & UI

Component conventions, styling systems and accessibility rules.

🔌

API & Backend

Endpoints, validation, error handling and DB conventions.

📝

Docs & Content

Tone of voice, formatting, changelog and SEO rules.

🔒

Security

Secret handling, input validation and safe patterns.

🚀

DevOps & CI

Build, deploy, and pipeline conventions.

Minimal example

---
name: frontend-tests
description: Use when writing or modifying frontend tests. Covers the
  repo's React Testing Library patterns and test commands.
---

# Frontend testing

- Place tests next to components: `Component.test.tsx`
- Use React Testing Library, query by role/label
- Run: `npm test -- path/to/file`

Where to find skills (trusted sources)

There is no single official, always-current "marketplace" for skills — they are shared by teams and the community. Use these trustworthy starting points and always review a skill before using it:

Claude Code documentation — Skills (official overview and format)
GitHub — search for SKILL.md in public repos
Your own team's repos — the most valuable skills encode your conventions

Safety tip: Only install skills from sources you trust. Read the SKILL.md before enabling it — a skill can instruct the agent to run commands. Prefer official docs and well-reviewed repos, and never run skills that ask for secrets or destructive commands.

Best practices

One skill, one job. Keep each skill focused on a single concern.
Great description. Write it in the third person with concrete trigger words — it's the only part always loaded.
Short body. Keep SKILL.md to a few hundred lines; push long references to separate files.
Show examples. A tiny before/after example beats paragraphs of rules.
Version them. Store skills in the repo so they evolve with the code.

Skills vs. tools vs. plugins

Concept	What it is
Skill	Markdown instructions that teach the agent conventions for a task.
Tool	A capability the agent can call (read file, run command, fetch URL).
Plugin / extension	Packaged integration that adds tools or features to the agent.