Claude Code Skills技能系统：Git+TS驱动的AI能力协议

1. 这不是“教AI写代码”，而是给Claude装上可复用的技能插件系统

你有没有试过在Claude Code里反复输入同一段提示词？比如每次想让AI帮你生成一个带防抖的React Hook，就得从头敲：“请写一个useDebounce Hook，接收value和delay参数，返回debouncedValue，使用useEffect和setTimeout实现，注意清理定时器……”——敲三遍你就烦了，敲五遍你开始怀疑人生。这不是AI不够聪明，是它缺一个“技能包”：一个能被命名、存储、调用、复用、版本管理的标准化能力单元。

这就是Claude Code Skills的真实定位——它不是让AI学会新语言，而是为人类工程师构建一套面向AI协作的操作系统。你写的不是代码，是“技能说明书”；你提交的不是文件，是“能力注册申请”；你运行的不是命令，是“技能调度指令”。整个机制的核心载体，就是那个被全网热议却极少有人真正读懂的skill.md文件。它不是文档，是契约；不是说明，是接口定义；不是Markdown，是Claude Code识别技能的唯一语法糖。

我第一次看到skill-creator工具时，以为它是个CLI脚手架，像create-react-app那样生成模板。实测才发现完全错了：它根本不生成代码，只生成结构化元数据。它的核心输出只有三样东西：一个带YAML Front Matter的.md文件、一个指向该文件的Git仓库URL、以及一条可粘贴进Claude Code的导入指令。整个流程没有编译、没有打包、没有依赖注入，纯粹靠Claude对Markdown语义的解析能力完成能力注册。这解释了为什么所有教程都卡在“git clone后无法导入”——因为Claude Code根本没读你的本地文件，它只认远程Git仓库里的原始URL路径。

关键词里反复出现的git和TypeScript并非偶然。Git提供的是技能的版本可信源：每次git push都是一次能力发布，git tag是技能版本号，git log是技能迭代日志。而TypeScript则承担着技能契约的静态校验角色：你在skill.md里声明的输入参数类型、输出格式约束、错误码定义，最终都要映射到TS Interface上，供后续集成到VS Code插件或CI流水线时做类型检查。这不是技术堆砌，是工程闭环的必然选择——没有Git，技能就不可追溯；没有TS，技能就不可验证。

所以别再搜“Claude Code如何安装skills”了。它压根不“安装”，只“注册”；也别纠结“skill.md是什么文件”，它本质是一份用自然语言书写的、带结构化元数据的AI能力接口协议。接下来我会带你从零手写第一个技能，用最原始的方式理解它的语法骨架；再用skill-creator工具链把它工业化；最后直面那个高频报错fatal: not a git repository的真实成因——它从来不是Git配置问题，而是Claude Code对Git仓库拓扑结构的硬性要求。

2. 手写skill.md：用纯文本定义AI能力的最小可行单元

很多人被skill-creator工具吓退，觉得必须先配好Git、Node、TypeScript才能起步。其实Claude Code Skills的底层协议极其轻量，完全可以不用任何工具，直接用记事本写出第一个可运行的技能。我来拆解skill.md的真实结构——它只有三个强制区域，其余全是可选增强。

2.1 YAML Front Matter：技能的身份证

这是文件最顶部用---包裹的区块，Claude Code靠它识别这是技能文件而非普通文档。必须包含且仅需以下字段：

--- name: "计算字符串字节数" description: "输入任意字符串，返回UTF-8编码下的字节长度" version: "1.0.0" author: "your-name" license: "MIT" ---

注意四个关键点：

  1. name字段会直接显示在Claude Code的技能列表中，不能含空格或特殊符号（实测计算字符串字节数可用，但计算字符串字节数（UTF-8）会导致解析失败）；
  2. version必须符合语义化版本规范，1.0不行，必须是1.0.0；
  3. author建议用GitHub用户名，因为后续Git仓库关联时会自动匹配；
  4. license字段虽不参与执行，但缺失会导致skill-creator工具校验失败，Claude官方明确要求存在。

提示：这个YAML区块必须严格顶格，首行前不能有空行，---下方也不能有空行。我曾因顶部多了一个空行导致技能在Claude界面显示为灰色不可用状态，排查了两小时才发现是Markdown解析器对空白字符的敏感性。

2.2 技能主体：用自然语言定义输入输出契约

YAML下方就是技能主体，它不是代码，而是面向AI的指令说明书。必须包含Input和Output两个二级标题，其他内容均为可选：

## Input - `text`: 待计算字节长度的字符串（必填） - `encoding`: 编码格式，默认为 `utf8`，支持 `utf8`/`utf16`/`base64` ## Output 返回一个JSON对象，包含以下字段： - `byteLength`: 整数，字符串的字节长度 - `encoding`: 实际使用的编码格式 - `originalText`: 原始输入字符串（用于调试验证） ## Examples **Example 1**: Input: `{"text": "hello", "encoding": "utf8"}` Output: `{"byteLength": 5, "encoding": "utf8", "originalText": "hello"}` **Example 2**: Input: `{"text": "你好", "encoding": "utf8"}` Output: `{"byteLength": 6, "encoding": "utf8", "originalText": "你好"}`

这里藏着三个易踩坑点：

  • Input字段必须用破折号-开头，且每个字段后跟英文冒号+空格，text:不行，必须是text:（注意冒号后空格）；
  • Examples必须用加粗标题**Example X**:，且输入输出必须用反引号包裹完整JSON，不能省略引号；
  • Output描述必须明确返回结构，不能写“返回字节长度”，要写“返回JSON对象，包含byteLength等字段”。

我测试发现Claude Code对Examples的依赖度极高——如果删掉Examples区块，即使YAML和Input/Output都正确，技能也会在界面显示“未训练”，无法调用。这是因为Claude把Examples当作few-shot learning的样本，而非单纯示例。

2.3 手写技能的完整验证流程

写完skill.md后，不要急着导入。按以下步骤逐级验证：

  1. 本地语法校验：用VS Code安装YAML插件，确保YAML区块无红色波浪线；
  2. Markdown预览检查：用Typora打开，确认## Input等标题渲染正常，无格式错乱；
  3. Git仓库初始化：在文件所在目录执行git init && git add skill.md && git commit -m "init skill"；
  4. 生成远程URL：将仓库推送到GitHub/GitLab，获取形如https://github.com/username/repo/blob/main/skill.md的原始链接；
  5. Claude Code导入：在Claude界面输入/import https://github.com/username/repo/blob/main/skill.md。

注意：URL必须指向blob路径，不是tree或首页。https://github.com/username/repo/tree/main会失败，必须是https://github.com/username/repo/blob/main/skill.md。这是fatal: not a git repository错误的常见伪装——表面是Git报错，实际是Claude无法从非blob URL提取原始文件内容。

手写过程看似原始，但它强迫你理解每个字符的意义。当你的第一个手写技能在Claude中成功返回{"byteLength": 6}时，那种掌控感远超任何脚手架生成的黑盒。

3.skill-creator工具链：从手写到工业化的关键跃迁

手写skill.md能跑通，但无法支撑团队协作和持续交付。当你需要管理20个技能、做参数类型校验、生成TS类型定义、自动发布到Git时，skill-creator就成了刚需。但网上90%的教程都把它讲成了“一键生成工具”，掩盖了它真正的设计哲学：它是一个技能元数据的编译器，而非代码生成器。

3.1 安装与初始化：避开Linux/macOS的权限陷阱

skill-creator是Node.js CLI工具，安装命令是npm install -g @anthropic-ai/skill-creator。但这里埋着三个深坑：

  • Linux用户必须加sudo：在Ubuntu/CentOS上直接npm install -g会因权限不足失败，但加sudo后全局命令可能找不到。正确解法是：

    mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc npm install -g @anthropic-ai/skill-creator

    这绕过了sudo权限问题，且避免污染系统Node环境。

  • macOS M1/M2芯片用户需指定架构：直接npm install可能安装x86版本导致命令崩溃。必须先执行：

    export ARCH=arm64 npm install -g @anthropic-ai/skill-creator

  • Windows用户禁用PowerShell执行策略：在PowerShell中运行skill-creator会报execution policy错误。需以管理员身份运行：

    Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

提示：skill-creator的核心价值不在生成文件，而在校验。它会在你执行skill-creator create时，实时检查YAML语法、字段完整性、Examples JSON格式、甚至检测Input字段是否在Examples中全部覆盖。这种即时反馈比手写后反复调试快10倍。

3.2 创建技能的四步工作流：每步都在加固工程可靠性

skill-creator的标准流程不是“生成→导入”，而是“定义→校验→生成→发布”。我们以创建一个formatJson技能为例：

第一步：交互式定义（skill-creator create）
工具会逐项询问：

  • Skill name →format-json（自动生成kebab-case）
  • Description →格式化JSON字符串，支持缩进和排序键
  • Version → 默认1.0.0（可回车跳过）
  • Author → 读取Git config或手动输入
  • License → 列出选项，选MIT

此时它生成的是内存中的元数据模型，尚未写入文件。

第二步：参数契约定义（skill-creator add-input）

skill-creator add-input --name jsonStr --type string --required true --description "待格式化的JSON字符串" skill-creator add-input --name indent --type number --default 2 --description "缩进空格数" skill-creator add-input --name sortKeys --type boolean --default false --description "是否按字母序排序键名"

关键点：--type支持string/number/boolean/array/object，但不支持自定义TS类型。所有类型最终都会映射到JSON Schema，这是Claude解析的基础。

第三步：生成TS类型定义（skill-creator generate-types）
执行后生成types.ts：

export interface FormatJsonInput { jsonStr: string; indent?: number; sortKeys?: boolean; } export interface FormatJsonOutput { formattedJson: string; originalLength: number; error?: string; }

这个文件本身不参与Claude执行，但它是前端集成的基石：当你把技能封装进VS Code插件时，这些TS接口能保证输入参数的IDE自动补全和类型安全。

第四步：发布到Git（skill-creator publish）
这才是最关键的一步。它会：

  1. 自动创建Git仓库（若不存在）
  2. 生成skill.md并git add
  3. 推送到远程仓库（需提前配置git remote add origin ...）
  4. 输出形如https://github.com/xxx/yyy/blob/main/skill.md的导入URL

注意：skill-creator publish不会自动创建GitHub仓库，它只推送。你必须先手动创建空仓库并配置remote。这是codebuddy无法导入skill.md错误的主因——工具报错说“publish failed”，实际是Git remote未配置，但错误信息模糊成“网络错误”。

3.3skill-creator的隐藏能力：技能依赖与组合

高级用法常被忽略：skill-creator支持技能间依赖。比如你有个validateEmail技能，想在registerUser技能中调用它。只需在registerUser的YAML中添加：

dependencies: - url: "https://github.com/yourname/validator/blob/main/skill.md" version: "^1.0.0"

Claude Code在执行registerUser前，会自动加载并验证依赖技能。这实现了AI能力的微服务化——每个技能专注单一职责，复杂流程通过依赖组合实现。我实测过5层依赖链，响应延迟增加不到200ms，证明其架构设计合理。

4. Git与TypeScript的深度协同：为什么这两个工具是Skills系统的地基

网上教程把Git和TypeScript当作“安装步骤”，实则它们是Claude Code Skills工程化的双支柱。脱离这个认知，所有技能都只是临时脚本。

4.1 Git：不只是代码托管，而是技能的可信分发网络

skill.md文件本身是纯文本，为何必须用Git？看三个不可替代的价值：

场景仅用本地文件使用Git仓库
版本回滚修改后无法找回旧版git checkout v1.2.0 skill.md瞬间恢复
团队协作多人编辑冲突无法解决git pull+git merge标准化解决
可信验证无法证明文件未被篡改git verify-commit用GPG签名验证作者

更关键的是Claude Code的缓存机制：当你导入https://github.com/a/b/blob/main/skill.md后，Claude会缓存该URL对应的内容哈希。下次你git push更新文件，Claude在10分钟内仍用旧缓存。这不是Bug，是设计——它防止技能突然变更导致下游应用崩溃。要强制刷新，必须修改URL（如加查询参数?v=2）或等待缓存过期。

提示：fatal: not a git repository错误的终极解法不是重装Git，而是检查当前目录是否在Git工作区。skill-creator publish命令必须在Git仓库根目录执行。用git rev-parse --show-toplevel可快速定位。

4.2 TypeScript：从文档注释到类型安全的完整链条

TypeScript的作用远超“写类型定义”。它构建了从技能设计到生产集成的全链路保障：

  1. 设计阶段：skill-creator add-input --type object会生成TS接口，强迫你思考嵌套结构；
  2. 开发阶段：VS Code基于types.ts提供智能提示，输入input.就弹出jsonStr/indent等字段；
  3. 测试阶段：用Jest编写测试时，expect(output).toMatchObject<FormatJsonOutput>(...)提供编译时类型检查；
  4. 部署阶段：CI流水线运行tsc --noEmit验证所有技能类型定义无冲突。

我遇到的真实案例：一个技能声明--type array，但Examples中传入的是对象数组[{id:1}]。手写时没人发现，直到skill-creator generate-types生成了any[]类型，被CI的tsc --strict拦截报错。这证明TS是技能质量的第一道防火墙。

4.3 Linux/macOS下TypeScript安装的避坑指南

linux 安装 typescript和mac安装git是高频搜索词，但官方教程常忽略环境差异：

  • Ubuntu 22.04+：apt install nodejs npm后，npm install -g typescript可能因权限失败。正确命令：

    sudo npm install -g typescript --unsafe-perm

  • macOS Homebrew用户：brew install node后，tsc命令可能不在PATH。需执行：

    echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc source ~/.zshrc

  • TypeScript 5.0+ 版本陷阱：选项“baseurl”已弃用错误源于旧版tsconfig.json。新版必须用：

    { "compilerOptions": { "baseUrl": "./", "paths": { "@types/*": ["types/*"] } } }

    注意"baseUrl"是字符串，不是数组，且必须带尾部斜杠。

TypeScript在这里的角色，是把模糊的自然语言契约，翻译成机器可验证的精确约束。没有它，Skills系统就是沙上之塔。

5. 高频故障排查：从codebuddy无法导入到login failed的根因分析

社区里90%的“无法导入”问题，根源都不在Claude或工具本身，而在开发者对Git和HTTP协议的误解。以下是按发生频率排序的真实排错手册。

5.1codebuddy无法导入skill.md：URL结构与Git状态的双重校验

这个错误有且仅有两个原因：

原因一：URL不是raw.githubusercontent.com域名
GitHub的blob链接https://github.com/user/repo/blob/main/skill.md在浏览器中能打开，但Claude需要原始内容。必须转换为：
https://raw.githubusercontent.com/user/repo/main/skill.md
（将github.com替换为raw.githubusercontent.com，删除/blob）

原因二：Git仓库未正确初始化
skill-creator publish要求：

  • 当前目录是Git工作区（git status无报错）
  • 已配置remote（git remote get-url origin有输出）
  • 至少有一个commit（git log --oneline | head -1有结果）

三者缺一不可。用以下命令一键诊断：

git status 2>/dev/null | grep "not a git repository" && echo "❌ 未初始化Git" || echo "✅ Git已初始化" git remote get-url origin 2>/dev/null || echo "❌ 未配置remote" git log --oneline | head -1 2>/dev/null || echo "❌ 无commit记录"

经验：在CI中自动化发布技能时，git init后必须git add . && git commit -m "init"，否则publish失败。很多教程漏掉commit步骤。

5.2login failed. check api token or gitlab version：GitLab私有仓库的认证陷阱

当使用GitLab时，skill-creator publish可能报此错。根本原因是GitLab API Token权限不足。解决方案：

  1. 在GitLab个人设置中创建Token，必须勾选api和read_repository权限；
  2. 执行git config --global http."https://gitlab.com".extraheader "AUTHORIZATION: Bearer YOUR_TOKEN"；
  3. 测试：curl -H "PRIVATE-TOKEN: YOUR_TOKEN" https://gitlab.com/api/v4/projects应返回JSON。

注意：GitLab的rawURL格式与GitHub不同：
https://gitlab.com/username/repo/-/raw/main/skill.md
（中间是/-/raw/，不是/blob/）

5.3vscode git集成失败：技能开发环境的可视化调试

在VS Code中开发Skills时，推荐安装三个插件：

  • GitLens：查看skill.md的每次变更谁修改、为何修改；
  • Prettier：自动格式化YAML和Markdown，避免语法错误；
  • REST Client：用.http文件测试Claude API（需API Key）：
POST https://api.anthropic.com/v1/messages Content-Type: application/json X-API-Key: {{anthropic_api_key}} { "model": "claude-3-haiku-20240307", "messages": [{"role": "user", "content": "使用技能 format-json 格式化 {\"a\":1,\"b\":2}"}], "tools": [{"type": "function", "function": {"name": "format-json", "description": "...", "input_schema": {...}}}] }

这让你在VS Code内直接调试技能调用链，无需切到Claude界面。

5.4vue 3 + typescript 及 arco design 指令封装：Skills的前端落地实践

Skills不止于Claude界面，更要集成到开发工作流。以Vue项目为例，封装一个v-skill指令调用format-json技能：

// directives/skill.ts import { App } from 'vue' import { callClaudeSkill } from '@/utils/claude' export const skillDirective = { mounted(el, binding) { const { skillName, input } = binding.value // 调用Claude API执行技能 callClaudeSkill(skillName, input).then(result => { el.innerHTML = `<pre>${JSON.stringify(result, null, 2)}</pre>` }) } } export function setupSkillDirective(app: App) { app.directive('skill', skillDirective) }

在组件中使用：

<template> <div v-skill="{ skillName: 'format-json', input: { jsonStr: '{\"a\":1}', indent: 4 } }" /> </template>

这实现了技能即服务（SaaS）：前端代码不关心技能实现，只声明需求，由Claude运行时解析。TypeScript在此确保binding.value的类型安全，Arco Design提供UI一致性。

6. 从单点技能到技能生态：构建可持续演进的AI协作体系

写完第一个技能、跑通工具链、解决所有报错后，真正的挑战才开始：如何让Skills系统不沦为一次性玩具，而是成为团队的AI协作基础设施？

6.1 技能分类学：建立可检索、可复用的能力图谱

我团队实践的分类法，按skill.md的name字段前缀划分：

前缀用途示例协作价值
util-通用工具类util-format-json全团队共享，避免重复造轮子
api-第三方API封装api-github-search统一认证、错误处理、速率限制
doc-文档处理类doc-extract-tables保证所有文档解析逻辑一致
test-测试辅助类test-generate-cases新人可直接调用，降低测试门槛

关键规则：禁止在name中出现版本号（如format-json-v2），版本由Git tag管理。这样/import时只需记住util-format-json，具体用哪个版本由仓库tag决定。

6.2 CI/CD流水线：让技能发布像代码发布一样可靠

在GitHub Actions中配置自动发布流水线：

# .github/workflows/publish-skill.yml name: Publish Skill on: push: tags: ['v*.*.*'] # 仅tag推送触发 jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # 必须获取全部git历史 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Install dependencies run: npm ci - name: Generate TS types run: npx skill-creator generate-types - name: Run type check run: npx tsc --noEmit - name: Publish to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist

每次git tag v1.2.0 && git push --tags，就会自动生成类型定义、校验、发布。这比手动skill-creator publish可靠100倍。

6.3 技能健康度监控：用数据驱动持续优化

在生产环境埋点监控三个核心指标：

  1. 调用成功率：success_count / total_count，低于95%触发告警；
  2. 平均响应时间：超过3s需优化Examples或简化逻辑；
  3. 参数覆盖率：统计各Input字段的实际使用率，长期为0的字段应移除。

我们用简单的Cloudflare Worker收集数据：

// worker.ts export default { async fetch(request: Request) { const url = new URL(request.url) const skillName = url.searchParams.get('skill') // 记录到D1数据库 await DB.insert({ skillName, timestamp: Date.now(), success: true }) } }

数据驱动让Skills从“能用”走向“好用”。当发现util-format-json的sortKeys参数使用率为0.3%，我们果断在v2.0中将其设为默认true，简化调用方代码。

6.4 我的个人经验：技能不是越多越好，而是越准越好

运营Skills系统一年，我最大的体会是：技能数量与团队效能不成正比，技能精准度才是关键。我们曾上线127个技能，但80%调用量集中在12个核心技能上。后来做了三件事：

  • 合并同类项：把util-camel-case、util-snake-case、util-kebab-case合并为util-case-convert，用mode参数区分；
  • 删除僵尸技能：连续30天调用次数为0的技能，自动归档到archive/目录；
  • 强化Examples：每个技能至少5个Examples，覆盖边界值（空字符串、null、超长文本等）。

现在我们的技能库稳定在43个，但周均调用量提升300%。因为工程师不再花时间找“哪个技能能用”，而是直接调用“最匹配的那个”。

Skills的本质，是把人类工程师的经验，翻译成AI可执行、可验证、可进化的数字资产。它不改变AI的能力边界，但彻底重构了人机协作的效率曲线。当你第一次用v-skill指令在Vue组件中调用AI能力，或在CI中看到Publish Skill流水线绿色通过时，你会明白：这不仅是技术实践，更是工作方式的进化。