AI agent skills
Introduction
Skills narrow the assistant to a repeatable job family: they complement wide workspace rules and ephemeral chat turns by naming a playbook the agent can select when intent matches. Compared to pasting a long brief every session, the bundle stays discoverable, attributable, and easy to sunset.
Cursor’s skills docs illustrate one concrete loader layout; other clients may vary paths, yet the contract is the same split— standing policy, live session state, and named procedures you version like code.
What are agent skills?
In this context, a skill is a checked-in bundle that walks a coding assistant through a narrow specialty—think security review cadence, framework migrations, or release checklist—while optionally carrying scripts, scaffolds, and reading lists the runtime may unlock only for that workflow.
Same playbook, any compatible client
Share one skill folder across editors and automation: everyone reads the same steps instead of maintaining separate write-ups per vendor.
Ship it like regular code
Plain files mean pull requests, tags, and installs from a repo—no hidden state-only copies living in one machine's settings.
Guidance the agent can run
Pair instructions with scripts or checks the assistant already invokes through tools so "what to do" lines up with verifiable outcomes.
Heavy reading only when it fits
Long annexes stay closed until the skill is active; the model opens them for that task so ordinary turns stay lighter.
What belongs in a skill
A skill should encode one coherent workflow or domain: when to use it, steps to follow, constraints (never touch certain paths, never call certain tools), output shape, and pointers to deeper references. If the text is only two sentences, it probably belongs in contextual engineering as standing instructions instead of a separate skill.
- 🔥 Trigger — what user intent or file context should activate the skill.
- 🔥 Procedure — ordered checks, commands, or sub-tasks the agent should run.
- 🔥 Guardrails — scopes, secrets, destructive actions, and escalation (human confirm, ticket).
- 🔥 Artifacts — templates, small scripts, or links the agent may read when the skill is active.
Skills vs loop patterns
Agent loop patterns describe runtime control flow (think–act–observe, planning, reflection). Skills are content: they do not replace the loop; they specialize what the loop should do for a task family. You can reference a pattern inside a skill (“follow ReAct with explicit confirmation before writes”) so behavior stays consistent.
When to add a skill
Add a skill when the same multi-step guidance repeats across sessions and you want discovery, versioning, and sharing—not when a single prompt or a short rule in repo docs is enough.
Where to add skills (skill directories)
Conventions differ by product, but the pattern is consistent: each skill is its own directory, and the entry file is SKILL.md. A common layout nests skills under .agents/skills/ or .cursor/skills/at project or user scope—check your client's docs for the exact roots you should use.
Minimal layout
One subfolder per skill; the manifest sits at the skill root:
.agents/
└── skills/
└── my-skill/
└── SKILL.mdOptional folders
Add sibling directories when the agent should run helpers, read long annexes, or copy templates—keep bulk material here instead of inflating SKILL.md.
.agents/
└── skills/
└── deploy-app/
├── SKILL.md
├── scripts/
│ ├── deploy.sh
│ └── validate.py
├── references/
│ └── REFERENCE.md
└── assets/
└── config-template.jsonA parent “category” folder is optional and only helps you group work visually. The skill itself is defined by the folder that holds SKILL.md—names like land-it, tdd, or deploy-app—not whatever sits above it in the tree.
Optional directories
Beyond SKILL.md, most stacks recognize a small set of helper folders inside each skill:
| Directory | Purpose |
|---|---|
scripts/ | Runnable helpers the agent can execute when the skill is active. |
references/ | Longer docs or specs pulled in on demand instead of living in the main manifest. |
assets/ | Static payloads—templates, sample data, binaries, or images the workflow may copy or cite. |
Keep SKILL.md lean: put deep dives under references/ or assets/ so the client can load them progressively and keep idle context smaller.
SKILL.md file format
The manifest is plain Markdown with YAML frontmatter at the top. Clients read name and description for discovery; the headings and lists below teach the runtime how to behave once the skill is active.
---
name: my-skill
description: One line on what the skill does and which situations should trigger it.
---
# Onboarding checks for legacy services
Use this body as procedural guidance, not marketing text.
## When to use
- The user is touching deploys, migrations, or config for this subsystem.
- You need a consistent checklist before suggesting edits across the repo.
## Instructions
- State assumptions, then verify against the repo before file changes.
- Follow team naming, logging, and test patterns spelled out in references/.
- Ask for confirmation before destructive commands or production-impacting steps.Frontmatter fields
| Field | Required | Description |
|---|---|---|
name | Yes | Stable identifier: lowercase letters, digits, and hyphens. Should match the parent skill folder name. |
description | Yes | What the skill does and when it applies; runtimes use this text to decide whether the skill fits the current task. |
paths | No | Glob patterns (comma-separated string or YAML list) that tie the skill to certain files; when set, the skill is surfaced mainly while those paths are in play. |
disable-model-invocation | No | When true, the skill is included only after an explicit /skill-name-style call—not from automatic matching alone. |
metadata | No | Open key–value map for extra labels, owners, or integration hints your stack understands. |
Scoping a skill to specific files
Use paths in the frontmatter with one or more glob patterns. When set, the client usually offers the skill while the user (or agent) is focused on files that match—so TSX-specific guidance does not crowd unrelated sessions.
---
name: ui-layer-conventions
description: How we structure React components and shared UI in this monorepo.
paths:
- "**/*.tsx"
- "packages/ui/**/*.ts"
---
# UI layer conventions
…The same field can be a single comma-separated string if you prefer a compact line:
---
name: python-style
description: House style for Python modules and tooling scripts.
paths: "**/*.py, scripts/**/*.py"
---Patterns use ordinary glob rules. Omit paths entirely when the skill should stay eligible regardless of which files are open.
Older bundles may still read a legacy globs field; new skills should standardize on paths.
Disabling automatic invocation
By default, many clients consider skills whenever context looks relevant. Set disable-model-invocation: true in the frontmatter when you want a manual gate instead: the pack is injected only after an explicit /skill-name (or equivalent) invocation, similar to a classic slash command.
Including scripts in skills
A scripts/ folder beside SKILL.md can hold executables the agent runs through its tool surface. Point to them with paths relative to the skill root so the same bundle works when copied or checked out elsewhere.
---
name: deploy-app
description: Deploy the application to staging or production when the operator requests a release.
---
# Deploy app
Use the bundled helpers in this skill folder.
## Usage
Run `scripts/deploy.sh <environment>` with `staging` or `production`.
## Pre-deploy checks
Before shipping, run `python scripts/validate.py`.The runtime follows the Markdown body and runs those script paths when the skill is active. Languages are not prescribed—shell, Python, Node, or any binary the host allows is fine as long as entry points are clear.
Conclusion
Treat skills as mini products: clear scope, explicit triggers, and stable ownership. Keep them small enough to audit; link out to longer docs instead of stuffing the skill body. That keeps agents predictable as models and tools change underneath.