On this page
Claude Skills
Learn how Claude Skills use SKILL.md, project and personal folders, supporting files, invocation rules, and governance controls in Claude Code.
12 min readHow Claude Skills Work
Claude Skills turn repeated procedures into discoverable Claude Code capabilities. They are strongest when the SKILL.md stays short, names the trigger clearly, and points to supporting files only when the task needs them.
Source checked against Claude Code skills docs
Claude Code skills are SKILL.md files that extend Claude with reusable instructions.
Skills can be invoked directly with slash commands or loaded automatically when relevant.
Personal, project, enterprise, and plugin scopes have different precedence and sharing behavior.
Primary file
SKILL.md
Common project path
.claude/skills/<skill-name>/SKILL.md
Invocation
Automatic relevance match or /skill-name
Can bundle
References, examples, templates, scripts
Good fit
Repeatable coding, review, docs, analysis, deployment, or verification workflows that teams keep prompting by hand.
Watch closely
Skills with allowed tools, shell injection, dynamic context commands, or references that can steer high-privilege changes.
Governance move
Treat project skills like code: code review them, version them, test trigger phrases, and document owners.
Claude Skills are reusable instruction packages for Claude Code. A skill teaches Claude when a workflow applies and what procedure to follow when it is active.
The key architectural point is progressive disclosure. Claude can see enough metadata to choose a skill, then load the detailed SKILL.md only when the task calls for it. That keeps everyday context smaller than a giant always-on CLAUDE.md file.
Where Claude Skills Live
Claude Code guide
Claude documents personal, project, enterprise, and plugin skill scopes. Project skills commonly live at .claude/skills/<skill-name>/SKILL.md and can be committed with the repository.
Claude also treats command files and skills as closely related. Existing .claude/commands files continue to work, while skills add richer folders, supporting resources, and invocation controls.
Personal skills apply across projects for one user.
Project skills apply to a repository and can be shared by the team.
Plugin skills are distributed with a plugin namespace.
Enterprise or managed skills can provide organization-wide guidance.
Discovery and Invocation
Claude Code guide
Claude can load a skill because the user's prompt explicitly invokes it or because the skill description matches the current task. The description is routing metadata, so it should be specific and front-load the use case.
Project skills are discovered from .claude/skills directories along the relevant project path. Claude Code also watches skill directories for SKILL.md changes during a session, with some plugin-related changes requiring plugin reloads.
Do not over-port platform behavior
What to Bundle
Claude Code guide
A Claude skill can include more than a single markdown file. Supporting examples, reference documents, templates, and scripts keep the main SKILL.md concise while still giving Claude reliable task-specific context.
The practical rule is to keep routing and the main procedure in SKILL.md, then reference heavier material by filename. If the model needs a spec, checklist, or helper script, tell it when to open or run that file.
Permissions and Security
Claude Code guide
Claude skill frontmatter can influence how a skill is invoked and which tools are available while it runs. That makes skill review a security activity, not just a documentation task.
Review allowed tools, command injection, scripts, and dynamic context carefully. A skill that pulls live diffs or runs shell helpers may be useful, but it also changes what the model sees and can do.
Require review for project skills before they land in the repository.
Use explicit stop conditions for production, secrets, and destructive actions.
Keep sensitive examples, tokens, and customer data out of skill folders.
Test whether the skill triggers too broadly before enabling implicit use.
Enterprise Governance Checklist
Claude Code guide
For enterprise Claude Code usage, the governance question is whether teams can explain which skill ran, what tool access it had, who approved it, and what output it produced.
Claude Skills fit best when paired with tracked work items, code review, audit logs, and a review cadence for skill changes.
Govern Claude Skills with tracked agent work
VibeFlow connects reusable agent workflows to work items, execution logs, commit records, security review, QA, and durable project context. That audit trail makes skills reviewable instead of invisible prompt behavior.
Ready to get started?
See how Axiom Studio can transform your AI infrastructure with enterprise-grade governance, security, and cost optimization.
Contact UsContinue Learning
What Are Agent Skills?
The hub guide for SKILL.md packages, progressive disclosure, and governance.
Agent Skill Security
Security controls for third-party and internal skill packages.
Codex Agent Skills
How Codex implements Agent Skills and AGENTS.md guidance.
Code Review Skill
A practical example of a reusable review workflow.