[AI Readability Summary] Claude Skill is an on-demand prompt engineering wrapper that turns repetitive development workflows into reusable capabilities with a single
SKILL.mdfile. It helps reduce repeated style instructions, duplicate process prompts, and wasted context in AI coding. Keywords: Claude Code, Skill, Prompt Engineering.
The technical specification snapshot outlines the essentials.
| Parameter | Description |
|---|---|
| Language | Markdown, YAML, Shell |
| Protocol/Specification | Agent Skills Specification |
| Applicable Environments | Claude Code, local projects, plugin ecosystems |
| Core Dependencies | SKILL.md, frontmatter, command injection, parameter passing |
| Repository Popularity | Original source did not provide a star count |
Claude Skill is a lightweight capability wrapper for repetitive tasks.
In Claude Code workflows, developers often repeat the same instructions about coding style, directory conventions, bug-fix procedures, and review standards. If you keep injecting that information in natural language during every session, you waste time and continuously consume valuable context window space.
The core value of a Skill is that it packages high-frequency workflows into a recognizable, triggerable, and reusable directory unit. Unlike CLAUDE.md, which loads in every conversation, a Skill loads only when the scenario matches. That makes it more token-efficient and better suited to modular maintenance.
The boundary between Skill and CLAUDE.md should remain clear.
CLAUDE.md works best for global development constraints, such as shared coding standards, commit conventions, and the team’s default language. A Skill behaves more like an on-demand task plugin, making it ideal for specific actions such as component generation, PR review, issue fixing, and release workflows.
---
name: hello-world
description: When the user says hello, reply in Chinese and include a dad joke.
---
Respond to the user input as requested.This minimal example shows the basic Skill skeleton: the YAML header defines the trigger metadata, and the body defines the execution instructions.
The Skill directory structure determines its scope.
A Skill can live at the personal, project, or plugin level, and its location directly determines where it takes effect. For team collaboration, the project-level .claude/skills/ directory is usually the most practical choice because the capability can ship with the repository.
| Storage Location | Path | Scope |
|---|---|---|
| Personal | `~/.claude/skills/ | |
| /SKILL.md` | All projects for the current user | |
| Project | `.claude/skills/ | |
| /SKILL.md` | Current repository | |
| Plugin | ` | |
| /skills//SKILL.md` | Environments where the plugin is enabled |
mkdir -p .claude/skills/my-skill
cd .claude/skills/my-skill
touch SKILL.md # Create the main Skill fileThis command sequence initializes a project-level Skill directory so you can start writing and testing immediately.
The Skill menu can be triggered directly through slash commands.
Once the directory and file structure are correct, entering / in the Claude chat box will usually show a list of manually invocable Skills. If nothing appears, the most common causes are an incorrect directory, invalid frontmatter syntax, or a client that has not been restarted.
AI Visual Insight: This interface shows Claude’s auto-discovered Skills in the command input box, which indicates that the client has indexed the local Skill successfully. You can explicitly invoke it with
/skill-name, making this view useful for verifying that the directory structure and frontmatter are working.
AI Visual Insight: This screenshot shows the result after a Skill is triggered, confirming that the
description field in frontmatter and the body instructions were parsed correctly and converted into a structured user-facing response.
Frontmatter fields directly affect Skill triggering and safety boundaries.
The most important field is description. It is not a summary. It is a trigger condition. The AI uses both name and description to decide whether the current task matches, so the description must include scenario terms, action terms, and a target object.
| Field | Purpose |
|---|---|
name |
Skill name and slash-command name |
description |
Matching basis for auto-triggering |
disable-model-invocation |
When set to true, the Skill can only be invoked manually |
allowed-tools |
Tools that can be used directly after activation |
context |
Supports execution in an isolated context |
---
name: vue-component
description: Generate a Vue 3 component. Use this when the user asks to create a component, page, or Vue file.
disable-model-invocation: false
allowed-tools:
- read
- write
---
1. Analyze the user requirement.
2. Generate the component according to the project conventions.
3. Add the necessary comments and exports.This example shows that trigger phrases should reflect real tasks rather than generic feature descriptions.
A strong description is fundamentally a retrieval entry point.
If you write, “This is a tool that helps generate code,” the model can barely determine when to activate it. If you instead write, “Generate a Vue 3 component. Use this when the user asks to create a page, form, or modal,” the hit rate improves significantly.
High-quality Skills should use step-by-step imperative instructions.
Use imperative sentences and numbered steps in the body whenever possible. This reduces execution ambiguity and guides the model to complete tasks in order instead of improvising freely.
1. Read the issue description.
2. Locate the relevant files.
3. Implement the fix.
4. Write tests.
5. Output a change summary.This kind of numbered instruction set significantly reduces missed steps and works especially well for test completion, code review, and pre-release checks.
Large Skills should split templates, examples, and scripts into separate files.
If SKILL.md keeps growing, move templates, examples, and validation scripts into other files in the same directory and reference them with relative paths. This keeps the main file manageable and makes version maintenance easier.
my-skill/
├── SKILL.md
├── template.vue
├── examples/
│ └── sample.vue
└── scripts/
└── validate.shThis directory tree shows a recommended way to split a Skill for complex generation tasks and team-shared templates.
## References
- See the component template in [template.vue](template.vue)
- See the output example in [examples/sample.vue](examples/sample.vue)This reference pattern decouples static assets from the main instruction file and reduces redundancy.
Dynamic injection and parameter passing are the key enhancements for Skill automation.
Using the !`command` syntax, a Skill can execute shell commands before loading and inject the results into the context. This is especially useful for PR review, Git change analysis, and environment state collection.
---
name: pr-review
description: Review the code changes in the current PR
---
## Current Changes
!`git diff --stat` # Inject change statistics
## Change Details
!`git diff` # Inject the full diff
Review the code changes above, focusing on potential bugs and style or standards issues.The core purpose of this configuration is to feed runtime context directly into the model instead of forcing the model to guess what changed.
Parameterized invocation lets one Skill serve many task instances.
$ARGUMENTS captures the input passed after the slash command. This is ideal for issue fixing, branch inspection, and ticket handling scenarios that require an ID or keyword.
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Fix GitHub issue #$ARGUMENTS:
1. Read the issue description # Understand the problem
2. Implement the fix # Modify the code
3. Write tests # Prevent regression
4. Create the commit # Output the commit resultThis Skill supports reusing the same workflow through a command such as /fix-issue 42.
Manual triggering is a necessary engineering constraint for high-risk operations.
Actions such as deployment, messaging, database modification, and remote resource creation all produce side effects and should not be invoked automatically by the model. For that reason, set disable-model-invocation: true for these Skills and return the final decision to the developer.
In practice, you should prioritize the most repetitive and stable workflows first.
If you are just getting started with Skills, do not over-engineer them. Start by packaging high-frequency tasks such as component generation, issue fixing, and pre-PR checks. These produce immediate value and are the easiest to standardize across a team.
FAQ structured answers address the most common implementation questions.
Q1: How should Skill and CLAUDE.md divide responsibilities?
A: Put long-term global rules in CLAUDE.md, and put on-demand task workflows in Skills. The former defines shared standards, while the latter executes specific tasks.
Q2: Why is my Skill not being auto-triggered?
A: The usual reason is that the description is too abstract and lacks clear scenario terms. Other common causes include an incorrect directory hierarchy, invalid YAML syntax, or a client that has not been restarted.
Q3: What kinds of tasks are suitable for Skills?
A: Skills work best for repetitive, high-frequency, rules-based workflows such as code generation, PR review, issue fixing, change summarization, template output, and validation script execution.
Core Summary: This article systematically explains Claude Skill concepts, directory conventions, trigger mechanisms, and efficient authoring techniques. It helps developers package repetitive coding workflows into reusable capabilities, reduce context consumption, standardize coding style, and improve AI collaboration efficiency.