Research checked on June 7, 2026.

How to use AI Agent Skills

A practical setup guide for SKILL.md, AGENTS.md, Claude Code, Codex, Cursor, Windsurf, Copilot, Gemini CLI, OpenCode, Zed, Continue, Cline and Aider.

Back to the skills catalog

Setup flow

1. Pick the right layer

Do not make every instruction a skill. A skill is best when the agent needs a repeatable workflow, optional files, scripts, examples or a checklist.

  • Use AGENTS.md, CLAUDE.md or GEMINI.md for stable repository context.

  • Use Cursor, Copilot, Continue or Cline rules for coding conventions and file-scoped guidance.

  • Use SKILL.md when the agent should load a procedure only when a task matches.

  • Use workflows or slash commands for actions that must stay explicitly triggered.

2. Write a narrow description

The description is the trigger surface. Keep it specific enough that the agent chooses the skill for the right jobs and ignores it for nearby tasks.

  • Good: "Review pull requests for correctness bugs and missing verification."

  • Weak: "Helps with code."

  • Mention user words that should activate the skill: review, deploy, PDF, Figma, CI failed.

3. Keep SKILL.md short

Put the decision flow in `SKILL.md`, then move long background material into lazy-loaded folders.

  • scripts/ for repeatable commands or generators.

  • references/ for long docs, rubrics, examples and API notes.

  • assets/ for reusable templates, images or sample files.

4. Add explicit verification

Every useful coding skill should tell the agent how to know it is done. Verification belongs in the skill, not only in memory.

  • List focused test commands, browser smoke checks or lint commands.

  • Say what to report if the command cannot run.

  • For production workflows, include rollback or backup checks.

5. Test activation

Try prompts that should trigger the skill and prompts that should not. Rename or narrow the description until the behavior is predictable.

  • Check one positive prompt, one adjacent prompt and one unrelated prompt.

  • Make dangerous workflows manual-only if the system supports it.

  • Review third-party skills before installing them.

Where to put the files

Claude Code

Project: .claude/skills/<name>/SKILL.md; personal: ~/.claude/skills/; memory: CLAUDE.md.

OpenAI Codex

Skills use the Agent Skills format. Project instructions live in AGENTS.md; installable bundles are plugins.

Cursor

Rules: .cursor/rules/*.mdc; project context can also use AGENTS.md.

Windsurf / Devin

Skills: .windsurf/skills/; rules: .devin/rules/; workflows: .windsurf/workflows/.

GitHub Copilot

Repo-wide: .github/copilot-instructions.md; path-specific: .github/instructions/*.instructions.md.

Gemini CLI

Context files use GEMINI.md across global, project and subdirectory levels.

OpenCode / Zed

OpenCode reads .opencode/skills/, .claude/skills/, .agents/skills/; Zed uses .agents/skills/.

Continue / Cline / Aider

Continue: .continue/rules/*.md; Cline: .clinerules/; Aider: convention files loaded with /read or config.

Starter files

SKILL.md

---
name: pr-review
description: Review pull requests for correctness bugs, risky behavior changes, and missing verification. Use when the user asks for PR review, code review, or risk analysis.
---

## Inputs
- Current diff or PR URL
- Project test commands
- Known invariants from AGENTS.md or repository docs

## Workflow
1. Read the diff before giving findings.
2. Prioritize correctness, security, data loss, and regressions.
3. Cite exact files and lines.
4. Separate required fixes from optional cleanup.
5. End with verification gaps.

AGENTS.md

# Project Instructions

## Commands
- Build: npm run build
- Test: npm test
- Lint: npm run lint

## Architecture
- Business logic lives in app/services.
- UI components live in src/components.

## Agent Rules
- Keep changes scoped to the requested task.
- Do not edit generated files unless generation is part of the task.
- Run the smallest relevant verification before reporting done.

Cursor .mdc rule

---
description: React component conventions for this codebase
globs: ["src/components/**/*.{ts,tsx}"]
alwaysApply: false
---

- Use existing design system components first.
- Keep server data fetching outside leaf UI components.
- Add tests for behavior, not implementation details.
- Prefer named exports for shared components.

GitHub Copilot instructions

---
applyTo: "app/**/*.php"
---

Use Laravel 11 conventions.
Prefer constructor injection for services.
Return typed responses from controllers.
For public write endpoints, fail closed and add feature tests.

Safety checklist

  • Inspect third-party skills before installing. A skill can change future agent behavior.

  • Keep deploy, deletion, payments and data export manual-only unless your approval policy is explicit.

  • Do not store API keys, passwords or customer data in skills, rules, prompt files or repository memory.

  • Move long references into references/ so the agent loads them only when needed.

  • Pin external scripts and document dependencies. Treat script-backed skills like code.

  • Test trigger behavior with prompts that should and should not activate the skill.

Official sources