What makes a Claude Code Skill different?
A skill packages instructions for a job that may recur: reviewing a pull request, applying a style guide, investigating an incident, preparing a release, or following a team-specific checklist. Instead of pasting the same directions into every conversation, you keep the workflow in a named directory.
Claude Code makes the skill's short description available for discovery. The complete instructions are loaded when the skill is invoked, which keeps detailed, occasional guidance out of the active context until it is useful. A skill can be invoked explicitly as /skill-name; Claude can also select it when its description matches the current task, unless its configuration disables automatic invocation.
That is more durable than an ordinary one-off prompt. It does not mean the skill is an autonomous program or that its output is guaranteed. The model still interprets the instructions, works within available tools and permissions, and needs appropriate review for consequential work.
What does a Skill contain?
At minimum, a portable Agent Skill is a directory containing SKILL.md. The file starts with YAML frontmatter and continues with Markdown instructions. Under the Agent Skills specification, name and description are required. Claude Code supports additional frontmatter for invocation controls, tools, model choice, arguments, paths, subagent execution, and other Claude-specific behavior.
A larger skill can include supporting material:
references/for documentation that should be read only when needed;scripts/for deterministic helpers or validation commands;assets/for templates, schemas, examples, or other resources;- focused files linked from
SKILL.mdrather than one oversized instruction document.
The description deserves particular care. It tells Claude what the skill does and when it applies. A title such as “Useful helper” gives the discovery system little signal; a description such as “Review a TypeScript API change for validation, authorization, error handling, and regression tests” defines a recognizable trigger and boundary.
How does Claude discover and use Skills?
Claude Code discovers skills from supported locations and exposes them in its skill list. Descriptions help Claude choose relevant skills. Full instructions load when invoked, either by the user or by Claude. After invocation, those instructions remain in the conversation context, while temporary tool approvals apply only for their documented duration.
This discovery model makes scope important. A broad description can cause a skill to trigger too often; a narrow or vague one can prevent it from appearing when needed. Test both positive prompts that should trigger the skill and nearby prompts that should not.
Personal, project, and plugin Skills
| Scope | Typical location | Best use |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | Your own reusable workflow across projects |
| Project | .claude/skills/<name>/SKILL.md | Repository-specific conventions shared with a team |
| Plugin | <plugin>/skills/<name>/SKILL.md | Versioned distribution with other plugin capabilities |
Claude Code also supports enterprise-managed and nested project skills. Current Anthropic documentation states that enterprise scope takes precedence over personal scope, and personal scope over project scope when names collide. Plugin skills use a namespaced command, reducing collisions with local skills. Because these rules can evolve, check the linked official documentation before designing a naming scheme that depends on precedence.
Common use cases
Good skills usually encode one clear, repeatable job. Examples include a release checklist that runs the project's real verification commands, a documentation review aligned with a house style, a debugging workflow that gathers evidence before proposing a fix, or a data-analysis procedure that uses a known schema.
PiSkill's verified directory provides concrete examples without republishing their bodies. Skill Creator focuses on creating and evaluating skills. Writing Agent Skills applies a test-driven approach to skill behavior. Find Skills helps discover relevant ecosystem resources. Review every original source and its permissions before installation.
Claude Skills versus ordinary prompts
| Question | Skill | Ordinary prompt |
|---|---|---|
| Reuse | Stored as a named package | Usually copied or written for one conversation |
| Discovery | Can be listed and selected by description | Depends on the user supplying it |
| Supporting files | Can bundle references, scripts, and assets | Usually limited to the current message and attachments |
| Scope | Personal, project, managed, or plugin | Conversation-specific unless stored elsewhere |
| Maintenance | Version and test the package | Update copies separately |
Prompts remain useful for a specific request, variables, or desired output. A skill is appropriate when the same operating procedure should be discoverable and repeatable. The prompt directory includes source-linked prompt patterns, while the skills directory focuses on reusable packages.
Limitations and safety
A skill is instruction content, not a trust certificate. Read downloaded SKILL.md files and supporting scripts before enabling them. Check tool grants, shell commands, external URLs, dependencies, and assumptions about credentials. Keep secrets out of skill files. Test destructive workflows with safe fixtures and require explicit user control where side effects are possible.
Skills can also become stale as command-line tools, APIs, or repository conventions change. Treat them like maintained code: keep ownership clear, review changes, test expected behavior, and remove packages that are no longer needed. For installation details, continue with how to install Claude Code Skills.