How to Write Your Own Claude Skill

What a Skill Is

A Skill is a single folder that contains a SKILL.md file. Claude Code scans the folder name and the description field, loading roughly 100 tokens initially and fetching the full content only when the Skill is invoked. By contrast, CLAUDE.md is loaded in full for every conversation, so its token consumption grows with file size.

Skill vs CLAUDE.md

Loading time : CLAUDE.md – full load each conversation; Skill – load name + description on demand.

Token consumption : CLAUDE.md – proportional to file size; Skill – ~100 tokens initially, full content only when triggered.

Suitable content : CLAUDE.md – global rules, project conventions; Skill – task‑specific SOPs, workflows.

Trigger method : CLAUDE.md – automatic; Skill – manual via /command or Claude auto‑match.

Where to Place a Skill

Personal level (available to all projects): ~/.claude/skills/<name>/SKILL.md Project level (effective only in the current project): .claude/skills/<name>/SKILL.md Plugin level (distributed with a plugin): <plugin>/skills/<name>/SKILL.md For most cases the project‑level location is sufficient; committing the .claude/skills/ directory to Git makes the Skills available to the whole team without extra configuration.

Writing a Minimal Skill

A Skill file consists of a YAML front‑matter header followed by a Markdown body.

---
name: hello-world
description: A demo skill that replies in Chinese with a joke.
---
当用户打招呼时，用中文回复，并附上一个冷笑话。

After creating the file, typing / in the Claude dialog shows the Skill list; selecting it or typing /hello-world invokes the Skill. If Claude matches the description automatically, the Skill triggers without manual selection.

Restart Claude Code after adding or modifying a Skill to load the changes.

Front‑matter Field Guide

name

(required): 1–64 characters, lowercase letters, numbers, hyphens; must match the folder name. description (required): up to 1024 characters; serves as the trigger, not a summary. disable-model-invocation (optional): set to true to require manual activation for actions with side effects. allowed-tools (optional): tools Claude may use without confirmation. license, compatibility, metadata (optional): additional metadata.

Best Practices for Writing Skills

1. Description as a Trigger

Write the description to include trigger keywords and the usage scenario, e.g., “Generate Vue 3 components when the user requests a component, page, or Vue file.” Avoid generic summaries.

# Bad
description: This is a tool that helps generate code.
# Good
description: Generate Vue 3 components when the user requests a component, page, or Vue file.

2. Use Imperative Commands with Numbering

Write steps as commands, not suggestions, and number them to enforce order.

1. Read the current file
2. Check for security issues
3. Output the review results

3. Keep SKILL.md Under 500 Lines

If the content grows, split it into auxiliary files and reference them from the main SKILL.md.

my-skill/
├── SKILL.md          # main instructions
├── template.vue      # component template
├── examples/
│   └── sample.vue    # example output
└── references/
    └── REFERENCE.md  # detailed reference

4. Dynamic Injection

Use the !`command` syntax to run a shell command before the Skill loads and embed its output into the prompt. Example for a PR‑review Skill:

---
name: pr-review
description: Review the current PR changes
---
## Current changes
!`git diff --stat`
## Change details
!`git diff`
请审查以上代码变更，关注潜在的 bug 和规范问题。

5. Accept Arguments

Define parameters with $ARGUMENTS (or positional $0, $1) to pass values when invoking the Skill.

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
修复 GitHub issue #$ARGUMENTS：
1. 阅读 issue 描述
2. 实现修复
3. 编写测试
4. 创建 commit

Calling /fix-issue 42 replaces $ARGUMENTS with 42. Multiple arguments can be accessed via $0, $1, etc.

6. Distinguish Automatic vs. Manual Triggers

Allow automatic triggering for pure query or generation tasks. Add disable-model-invocation: true for actions with side effects such as deployment, messaging, or file modification.

Full‑Featured Example: React Component Skill

Directory layout:

react-component/
├── SKILL.md
├── template.tsx   # component template
└── examples/
    └── Button.tsx  # sample output

Content of SKILL.md:

---
name: react-component
description: Generate team‑compliant React components when the user requests a component, UI, or page.
---
按照以下规范生成 React 组件：
1. 使用 TypeScript，所有 props 要写类型
2. 样式一律用 Tailwind CSS，不允许内联样式
3. 函数组件要加 displayName
4. 导出方式用 named export，不用 default export
5. 参考 template.tsx 的结构
输出示例见 examples/Button.tsx。

Now typing “帮我写一个搜索框组件” or manually invoking /react-component yields a component that follows all team standards.

Validating Skills

Use the official skills-ref tool (agentskills/agentskills) to check front‑matter validity.

# Install validation tool (see GitHub: agentskills/agentskills)
skills-ref validate ./react-component

The tool verifies the name format, non‑empty description, and other naming rules.

Team Sharing

Commit the .claude/skills/ directory to a Git repository. New team members clone the repo and immediately see all shared Skills in Claude Code, avoiding the need to embed many rules in a single CLAUDE.md file.

Small Details

Name field rules : only lowercase letters, numbers, single hyphens; cannot start or end with a hyphen or contain consecutive hyphens. Example of a valid name: my-skill.

Restart required : after adding or modifying a Skill, restart Claude Code or run /reload to apply changes.

Debug tip : test whether a Skill is recognized by mentioning its use case in a conversation and observing if Claude loads it automatically.

References

Agent Skills Specification (official spec)

agentskills/agentskills GitHub repository (validation tool)

Juejin article: https://juejin.cn/post/7629641479674478642