How to Build a Custom Claude Skill Quickly

What a Skill Is

A Skill is a single SKILL.md file placed in its own folder. Claude Code scans only the name and description fields (≈100 tokens) at startup and loads the full file on demand. By contrast, CLAUDE.md is loaded in full for every conversation, so large files consume a lot of context.

Where Skills Can Be Stored

Personal level (available to all projects): ~/.claude/skills/ Project level (effective only for the current project): .claude/skills/ Plugin level (distributed with a plugin): /skills/ In most cases the project level is sufficient; committing the .claude/skills/ folder to Git shares the Skill with the whole team without extra configuration.

Creating the Simplest Skill

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

---
name: hello-world
description: 一个示例 skill，用于演示基本结构
---
当用户打招呼时，用中文回复，并附上一个冷笑话。

After saving the file, typing / in the Claude dialog shows the Skill list. Selecting it or typing /hello-world invokes the Skill. Claude can also auto‑trigger the Skill when the conversation matches the description.

Front‑Matter Field Guide

name

(required): 1–64 characters, lowercase letters, numbers, hyphens; must match the folder name. description (required): up to 1024 characters; the key field that tells Claude when to load the Skill. disable-model-invocation (optional): if true, the Skill can only be called manually. allowed-tools (optional): tools the Skill may use without confirmation. license (optional): license type. compatibility (optional): environment requirements, e.g. Requires python3.10+. metadata (optional): custom key‑value pairs for extra information.

Best Practices for Writing Skills

Make description a trigger, not a summary. Include actionable keywords and the exact scenario, e.g. “生成 Vue 3 组件。当用户要求创建组件、页面或 Vue 文件时使用”。

Use imperative commands with numbering. Example:

1. 读取当前文件
2. 检查安全问题
3. 输出审查结果

Keep SKILL.md under 500 lines. Split large logic into auxiliary files and reference them from the main file.

Dynamic injection. Use !`command` to run a shell command before the Skill loads and embed its output, e.g. !`git diff --stat` for a PR‑review Skill.

Accept parameters. Use $ARGUMENTS (or $0, $1) to receive arguments when invoking the Skill.

Control who can trigger the Skill. Set disable-model-invocation: true for actions with side effects such as deployments.

Full‑Scale Example: React Component Generator

Folder layout:

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

Key parts of SKILL.md:

---
name: react-component
description: 生成符合团队规范的 React 组件。当用户要求创建组件、写 UI 或新建页面时使用。
---
按照以下规范生成 React 组件：
1. 使用 TypeScript，所有 props 要写类型
2. 样式一律用 Tailwind CSS，不允许内联样式
3. 函数组件要加 displayName
4. 导出方式用 named export，不用 default export
5. 参考 template.tsx 的结构
输出示例见 examples/Button.tsx

After adding this Skill, saying “帮我写一个搜索框组件” or running /react-component yields a fully compliant component without repeating the specifications each time.

Validation and Sharing

Use the official skills-ref tool (agentskills/agentskills) to validate front‑matter:

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

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

Small Details

The name field must be lowercase, alphanumeric, with at most one hyphen between characters (e.g., my-skill is valid; my--skill or -my-skill are not).

After adding or modifying a Skill, restart Claude Code or run /reload for changes to take effect.

To debug, mention a scenario related to the Skill in conversation and see if Claude auto‑loads it.

References

Agent Skills Specification (official spec)

agentskills/agentskills GitHub – Skill validation tool

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