An AI agent skill is a reusable package of instructions and supporting material that teaches a coding agent when and how to perform a particular workflow. Instead of pasting the same long prompt into every conversation, you give the agent a durable procedure it can discover when relevant.
A skill is more than a saved prompt
A prompt usually handles one request in one conversation. A well-formed skill describes the requests that should trigger it, the inputs it needs, the ordered workflow, expected outputs, safety boundaries, and what to do when a prerequisite is missing. References and examples can live beside the main instructions without occupying every conversation by default.
The common anatomy
- Name and description: concise discovery metadata that distinguishes the workflow from near misses.
- When to use: realistic situations where the procedure is appropriate.
- Workflow: ordered, executable steps with decision points and constraints.
- Outputs: the files, reports, or state the agent should produce.
- Guardrails: boundaries around destructive actions, secrets, permissions, and unsupported claims.
- References and tests: deeper evidence plus examples that check whether the skill triggers correctly.
Skills, rules, tools, and agents solve different problems
| Mechanism | Best use | Key distinction |
|---|---|---|
| Skill | Reusable workflow or specialized knowledge | Loaded when the task calls for it |
| Project rules | Always-relevant repository conventions | Present across ordinary project work |
| Tool or MCP server | Accessing an external capability or system | Provides an action, not the complete procedure |
| Subagent | Delegated work with separate context | A worker, not a reusable instruction package |
Claude Code's official feature overview makes a similar distinction: skills provide reusable knowledge and workflows, while MCP connects tools and subagents run isolated work. See the official comparison.
How XSkills targets different coding agents
XSkills compiles separate native packages for Claude Code, Codex, and Cursor. The shared workflow and evidence remain consistent, while the install root and harness-specific metadata follow the selected destination. A Claude Code package installs under ~/.claude/skills; Codex uses ~/.agents/skills; Cursor uses ~/.cursor/skills.
Cross-harness output is not produced by blindly copying a folder. XSkills validates that a package does not contain metadata intended for another agent and records the target in its manifest before delivery.
When a skill is worth keeping
Create a skill when the workflow is repeated, benefits from consistent sequencing, or contains constraints the agent should not rediscover every time. Keep a one-off answer as a prompt when it is unlikely to recur. Avoid turning vague inspiration into a skill: durable instructions amplify both good assumptions and bad ones.
The safest workflow preserves the source, tests the activation boundary, and requires a person to approve the exact version that will be installed. That is the model used by XSkills.
Next, read how XSkills turns X bookmarks into Claude Code skillsor inspect the review and installation safeguards.