skill-builder

用途

Skill Builder 用于创建生产就绪的 Claude Code Skills，提供规范的 YAML frontmatter、渐进式披露架构以及完整的文件与文件夹结构。它引导用户构建可被 Claude 在所有界面（Claude.ai、Claude Code、SDK、API）自主发现和使用的技能。

前置条件

Claude Code 2.0+ 或支持 Skills 的 Claude.ai
对 Markdown 和 YAML 有基本了解
文本编辑器或 IDE

主要能力

YAML Frontmatter 规范

每个 SKILL.md 必须以 YAML frontmatter 开头，且仅包含两个必填字段：

name：字符串，最长 64 字符，人类友好的显示名称，建议使用标题大小写。
description：字符串，最长 1024 字符，必须同时说明技能做什么（功能）以及 Claude 何时应调用它（触发条件）。

只有 name 和 description 会被 Claude 使用，其他字段会被忽略。

目录结构

技能必须直接位于 ~/.claude/skills/[skill-name]/ 或 .claude/skills/[skill-name]/ 下，不支持嵌套子目录或命名空间。

最小结构：

~/.claude/skills/
└── my-skill/
    └── SKILL.md

完整结构可包含可选的 README.md、scripts/、resources/（templates、examples、schemas）和 docs/ 目录。

技能位置分两类：

个人技能：~/.claude/skills/，对所有项目可用，不提交到 git。
项目技能：<project-root>/.claude/skills/，仅当前项目可用，应提交到 git。

渐进式披露架构

Claude Code 使用三级渐进式披露系统，可扩展到 100+ 技能而不产生上下文负担：

第 1 级：元数据（名称 + 描述），启动时始终加载，每个技能约 200 字符。
第 2 级：SKILL.md 正文，技能被触发时加载，通常约 1-10KB。
第 3 级及以上：引用文件，按需加载，大小可变。

SKILL.md 内容结构

推荐四级结构：

概述（始终先读）：2-3 句简要描述、前置条件、功能列表。
快速开始：基本用法和常见场景。
详细说明：分步指南、高级选项。
参考：故障排除、完整 API 参考、示例、相关技能、资源。

内容最佳实践

描述中前置关键词，包含明确的“何时使用”子句，具体说明技术栈。
保持第 1 级简短，第 2 级覆盖常见路径，第 3 级提供细节，第 4 级处理边缘情况。
保持 SKILL.md 精简（约 2-5KB），将冗长内容移至单独文件并引用。

脚本与资源

scripts/：可执行脚本，如 setup.sh、validate.js、generate.py、deploy.sh，从 SKILL.md 引用。
resources/：模板、示例、schema 等静态文件，可被脚本引用或复制。

文件引用与导航

支持 Markdown 链接、相对文件路径和内联文件内容引用，Claude 可自动导航到引用文件。

使用方式

快速创建第一个技能：

# 1. 创建技能目录（必须在顶层，不能放在子目录中！）
mkdir -p ~/.claude/skills/my-first-skill

# 2. 创建 SKILL.md
cat > ~/.claude/skills/my-first-skill/SKILL.md << 'EOF'
---
name: "My First Skill"
description: "Brief description of what this skill does and when Claude should use it. Maximum 1024 characters."
---

# My First Skill

## What This Skill Does
[Your instructions here]

## Quick Start
[Basic usage]
EOF

# 3. 验证技能被检测到
# 重启 Claude Code 或刷新 Claude.ai

验证清单

发布技能前需检查：

YAML frontmatter：以 --- 开头和结尾，包含 name（≤64 字符）和 description（≤1024 字符），描述包含“做什么”和“何时用”，无语法错误。
文件结构：SKILL.md 存在于技能目录中，目录直接位于 ~/.claude/skills/[skill-name]/ 或 .claude/skills/[skill-name]/，无嵌套子目录。
内容质量：各级内容清晰，示例具体可运行，故障排除覆盖常见问题。
渐进式披露：核心指令在 SKILL.md 中，高级内容在 docs/ 中，大资源在 resources/ 中。
测试：技能出现在 Claude 技能列表中，描述能在相关查询时触发，脚本可成功执行，示例按文档工作。

适用场景

需要为 Claude Code 或 Claude.ai 创建可自主发现和使用的技能。
希望遵循规范的 YAML frontmatter 和渐进式披露架构。
需要组织完整的技能目录结构，包括脚本、模板、示例和文档。
团队共享项目特定技能或构建个人生产力工具。

限制

技能必须直接位于顶层技能目录下，不支持嵌套子目录或命名空间。
YAML frontmatter 仅 name 和 description 被使用，其他字段被忽略。
name 最长 64 字符，description 最长 1024 字符。
需要 Claude Code 2.0+ 或支持 Skills 的 Claude.ai。
关于收费、价格、平台等具体信息暂未提供。