Claude Code Skills 开发指南

> 从 Skill 定义结构到实战案例，涵盖 blog-publish、debug-ila、unit-sim、git-push 等真实用例。

1. Skill 概述

Skill 是 Claude Code 的可复用能力单元 —— 将一组固定的操作流程封装为可触发的命令。当用户输入包含特定关键词或执行 /skill-name 时，Claude Code 自动加载对应指令集并执行。

核心价值

消除重复描述：不再每次对 Claude 解释"帮我做 A → B → C"
保证一致性：每次执行流程完全一致，避免遗漏步骤
降低门槛：团队成员无需了解底层细节，一句话即可触发
可组合：一个 Skill 可以调用另一个 Skill

2. Skill 定义结构

2.1 存储位置


~/.claude/skills/               # 全局 Skills
├── blog-publish.md
├── debug-ila.md
├── unit-sim.md
├── git-push.md
├── git-share.md
├── md2html.md
└── md2pdf.md

<project>/.claude/skills/       # 项目级 Skills（优先级更高）

└── project-specific-skill.md

2.2 文件格式

每个 Skill 是一个 Markdown 文件，包含 YAML frontmatter：


---
name: skill-name
description: 简短描述，显示在 /help 列表中
trigger_words:
  - 触发词1
  - 触发词2
  - /slash-command
arguments:
  - name: arg1
    description: 参数1说明
    required: true
  - name: arg2
    description: 参数2说明
    required: false
    default: "默认值"
---

# Skill 名称

## 执行步骤

1. 第一步操作的具体说明

2. 第二步操作的说明

...

3. 实战案例

3.1 blog-publish — 博客发布

触发词：发布博客、上传博客、发表文章、push blog、/blog-publish

--- name: blog-publish description: 将 Markdown 文章转为 HTML 并发布到 buckfpga.uk trigger_words: - 发布博客 - 上传博客 - 发表文章 - /blog-publish - /publish arguments: - name: file description: Markdown 文件路径 required: true --- # blog-publish 将 Markdown 博客文章转为 HTML 并通过 Cloudflare R2 发布到 buckfpga.uk。 ## 执行流程

1. **读取** Markdown 文件，确认文件存在且格式正确 2. **转换** md → html： - 使用 pandoc 或自定义转换器 - 渲染 Mermaid 图表为 SVG - 渲染 Wavedrom 时序图 3. **生成页面**： - 套用博客模板（header/footer/nav） - 注入 meta 标签（title/description/og:image） - 添加阅读时间、标签、日期 4. **上传**到 Cloudflare R2：

bash
# 设置环境变量
export R2_ACCESS_KEY_ID="..."
export R2_SECRET_ACCESS_KEY="..."

# 上传 HTML
aws s3 cp output.html s3://buckfpga-blog/posts/ \
--endpoint-url https://xxx.r2.cloudflarestorage.com



5. **验证**：curl 检查页面 HTTP 200

6. **输出**：发布后的 URL `https://buckfpga.uk/posts/xxx.html`

## 模板文件

- HTML 模板：`/home/user/tools/blog-template.html`

- CSS 样式：`/home/user/tools/blog-style.css`

## 错误处理

- 如果 pandoc 未安装：提示安装命令 `sudo apt install pandoc`

- 如果 R2 上传失败：检查 AWS CLI 配置和 endpoint URL

- 如果 Mermaid 渲染失败：降级为代码块展示

设计要点：

trigger_words 覆盖中英文多种说法
arguments 通过 file 参数指定博客文件
执行流程分五步，每步有明确的成功标准
错误处理覆盖常见失败场景

3.2 debug-ila — FPGA 调试插桩

触发词：debug_ila、加调试、加 ILA、插桩、抓信号

--- name: debug-ila description: 自动在 RTL 中添加 ILA 调试链路 trigger_words: - debug_ila - 加调试 - 加 ILA - 插桩 - 抓信号 arguments: - name: top_module description: 顶层模块名称 required: true - name: signals description: 要抓取的信号列表（空格分隔） required: true - name: depth description: ILA 采样深度 required: false default: "1024" --- # debug-ila 在指定的顶层模块中自动添加 `soft_ila_top` + `ila_hub_top` 调试链路。 ## 执行流程

1. **定位 RTL**：找到 `top_module` 对应的 .v/.sv 文件 2. **分析端口**：解析模块端口列表，检查 `signals` 是否都存在于模块内部 3. **添加 ILA 例化**： - 例化 `soft_ila_top #(.SAMPLE_DEPTH(depth), .SIGNAL_COUNT(n))` - 例化 `ila_hub_top`（JTAG/UART 接口） - 连接时钟和复位到 ILA 4. **生成 signals.json**：

json
{
"top_module": "fcam_top",
"signals": [
{"name": "vsync", "width": 1, "msb": 0, "lsb": 0},
{"name": "fifo_wr_data", "width": 32, "msb": 31, "lsb": 0}
],
"depth": 1024
}



5. **验证**：确认插入后语法正确（检查 `endmodule` 位置）

## 插入位置规则

- `soft_ila_top`：always 块之后，endmodule 之前

- `ila_hub_top`：顶层模块中，soft_ila_top 旁边

- 格式：每行一个端口，对齐清晰

## 文件修改记录

- 修改 `<top_module>.v`：添加 ILA 例化

- 创建 `<top_module>_ila_signals.json`：信号配置

设计要点：

需要两个参数（模块名 + 信号列表）
depth 有默认值 1024，用户可覆盖
输出 signals.json 便于后续工具读取
有明确的格式规范（参考 Verilog 例化风格）

3.3 unit-sim — Verilog 单元仿真

触发词：仿真、unit-sim、单元仿真、跑仿真、simulate


---
name: unit-sim
description: Verilog 单元仿真自动化流程
trigger_words:
  - 仿真
  - unit-sim
  - 单元仿真
  - 跑仿真
  - /sim
arguments:
  - name: module_name
    description: 要仿真的模块名
    required: true
  - name: simulator
    description: 仿真工具 (verilator|icarus|modelsim)
    required: false
    default: "verilator"
---

# unit-sim

自动查找 testbench → 选择仿真器 → 运行 → 打开波形。

## 执行流程

### 第一步：查找 Testbench

搜索规则（按优先级）：



### 第二步：选择仿真工具

bash

Verilator（默认，最快）

verilator --cc --trace .v tb_.v --exe --build ./obj_dir/V

Icarus Verilog

iverilog -o sim.out .v tb_.v vvp sim.out

ModelSim（如果安装了）

vlib work vlog .v tb_.v vsim -c -do "run -all; quit" work.tb_



### 第三步：解析结果

- 检查 `$display("PASS")` / `$display("FAIL")` 输出

- 检查 `$fatal` / `$error` 调用

- 统计 assertion 通过率

### 第四步：打开波形

bash

GTKWave（最常用）

gtkwave dump.vcd &

Verilator 波形

gtkwave obj_dir/trace.vcd &



## 自动检测仿真工具

bash

按可用性自动选择

if command -v verilator &> /dev/null; then SIM=verilator elif command -v iverilog &> /dev/null; then SIM=icarus elif command -v vsim &> /dev/null; then SIM=modelsim else echo "错误: 未找到仿真器。安装 verilator: sudo apt install verilator" exit 1 fi



## 仿真报告

==================== 仿真报告 ==================== 模块: fcam_top Testbench: tb_fcam_top.v 仿真器: Verilator 5.012 状态: 通过耗时: 2.3s 断言: 15/15 通过覆盖率: 92% (语句) 波形: obj_dir/trace.vcd ==================================================

设计要点：

自动检测可用的仿真工具
多级 testbench 搜索策略
统一的输出报告格式

--- name: git-push description: 推送代码到 GitHub trigger_words: - /git-push - 上传代码 - push 代码 arguments: - name: project description: 项目名（如 FPGA_Prj/Project/WebServer 或简写 WebServer） required: true --- # git-push 推送指定项目的代码到 GitHub。 ## 执行流程

1. **定位项目**： - 精确匹配：`/home/user/work/$project` - 模糊匹配：在 `/home/user/work/` 下搜索包含 `$project` 的目录 2. **检查状态**：

bash
cd /home/user/work/$project
git status



3. **自动提交**（如果有未提交更改）：

bash
git add -A
git commit -m "自动提交: $(date '+%Y-%m-%d %H:%M')"



4. **推送**：

bash
git push origin $(git branch --show-current)



5. **输出** commit hash 和 push 结果

## Git 凭据

使用 BuckHuang/HuanghmBuck 的 GitHub 凭据。

Token 存储在 `~/.git-credentials` 或环境变量 `GITHUB_TOKEN` 中。


---
name: git-share
description: 管理 GitHub 私有仓库的协作者
trigger_words:
  - 分享仓库
  - 添加协作者
  - 移除协作者
  - grant access
  - /git-share
arguments:
  - name: project
    description: 项目名
    required: true
  - name: action
    description: add 或 remove
    required: true
  - name: username
    description: GitHub 用户名
    required: true
---

# git-share

## 执行流程

bash

添加协作者

gh api repos/BuckHuang/$REPO/collaborators/$USERNAME -X PUT

移除协作者

gh api repos/BuckHuang/$REPO/collaborators/$USERNAME -X DELETE

查看当前协作者

gh api repos/BuckHuang/$REPO/collaborators

设计要点：

project 参数支持简写（自动搜索完整路径）
自动处理未提交的更改
错误时给出清晰的提示

3.5 md2html — 文档格式转换

--- name: md2html description: Markdown 转 HTML（支持 Mermaid + Wavedrom） trigger_words: - 转html - 生成网页 - md2html - /md2html arguments: - name: input description: Markdown 文件路径 required: true - name: output description: 输出 HTML 文件路径（可选，默认同名 .html） required: false --- # md2html ## 转换流程

1. **预处理**：提取 Mermaid 代码块 → 渲染为 SVG 2. **预处理**：提取 Wavedrom 代码块 → 渲染为 SVG 3. **Markdown → HTML**：

bash
pandoc input.md -o output.html \
--standalone \
--template=/home/user/tools/pandoc-template.html \
--toc --toc-depth=3 \
--metadata title="文档标题"



4. **嵌入 SVG**：将步骤 1-2 生成的 SVG 内联到 HTML

5. **后处理**：添加语法高亮（highlight.js）、响应式 meta 标签

## Mermaid 渲染

bash mmdc -i mermaid.mmd -o mermaid.svg -t neutral



## Wavedrom 渲染

bash wavedrom-cli -i wavedrom.json -o wavedrom.svg



## 依赖安装

bash sudo apt install pandoc npm install -g @mermaid-js/mermaid-cli npm install -g wavedrom-cli

3.6 md2pdf — Markdown 转 PDF/DOCX


---
name: md2pdf
description: Markdown 转 PDF/DOCX
trigger_words:
  - 转pdf
  - 转docx
  - 生成pdf
  - /md2pdf
arguments:
  - name: input
    description: Markdown 文件路径
    required: true
  - name: format
    description: pdf 或 docx
    required: false
    default: "pdf"
---

# md2pdf

## 转换命令

bash

MD → PDF

pandoc input.md -o output.pdf \ --pdf-engine=xelatex \ -V mainfont="Noto Sans CJK SC" \ -V geometry:margin=2cm \ --toc

MD → DOCX

pandoc input.md -o output.docx \ --reference-doc=/home/user/tools/template.docx



## 中文字体配置

bash

安装中文字体

sudo apt install fonts-noto-cjk

检查可用字体

fc-list :lang=zh | grep -i noto



## 常见问题

- **中文不显示**：确认 xelatex 和 Noto CJK 字体已安装

- **Mermaid 图表丢失**：先用 md2html 渲染，再用 pandoc 转换 HTML → PDF

4. 触发词设计原则

4.1 设计准则

原则	说明	示例
覆盖面	覆盖中英文、常见变体	`push代码`、`上传代码`、`/git-push`
避免歧义	触发词应唯一，减少与其他 Skill 冲突	`加调试` > `加`
自然语言	优先用自然短语，而非技术黑话	`抓信号` > `insert_ila`
短词优先	2-4 个字的中文短语	`跑仿真` > `运行单元仿真测试`

4.2 冲突处理

当多个 Skill 匹配同一输入时：

精确匹配优先：/git-push 优先于 push
项目级优先：项目 .claude/skills/ 优先于全局 ~/.claude/skills/
参数数匹配：参数更多的 Skill 优先
用户确认：无法自动判定时，列出候选让用户选择

4.3 命名规范


<动词>-<对象>    # 推荐格式
blog-publish     # 发布博客
git-push         # 推送代码
unit-sim         # 单元仿真
debug-ila        # ILA 调试

# 避免

publish_blog     # 不推荐：下划线

BlogPublish      # 不推荐：驼峰

pb              # 不推荐：过度缩写

4.4 触发词清单模板


trigger_words:
  - 英文主名          # 精确匹配
  - 中文主名          # 自然语言
  - 中文别名1         # 同义说法
  - 中文别名2         # 口语化表达
  - /slash-command    # Slash 命令形式

5. 参数传递与错误处理

5.1 参数定义


arguments:
  - name: module_name
    description: 模块名称
    required: true
    # 无默认值，必须由用户提供

- name: simulator

    description: 仿真工具选择

    required: false

    default: "verilator"

    # 可选参数，有默认值

- name: files

    description: 文件列表

    required: false

    type: array

    # 接受多个值

5.2 参数类型

类型	示例
`string`	`"fcam_top"`
`number`	`1024`
`boolean`	`true`
`array`	`["file1.v", "file2.v"]`
`path`	`/home/user/work/project/src/`

5.3 错误处理模式


## 错误处理

### 文件未找到

- 检查路径拼写

- 搜索相似文件名

- 列出当前目录文件供选择

### 工具未安装

- 检测工具是否存在（`command -v xxx`）

- 给出安装命令

- 询问是否自动安装（需要 sudo 权限）

### 参数缺失

- 列出缺失的必选参数

- 提供交互式输入（对话中询问）

### 执行失败

- 保留中间产物便于排查

- 输出完整错误日志

- 提供回滚/清理方案

5.4 交互式参数收集

当必选参数缺失时，Skill 可以引导用户逐步提供：


用户: /sim
Claude: 请问要对哪个模块进行仿真？
用户: fcam_top
Claude: 检测到以下 Testbench：
        1. tb_fcam_top.v (同目录)
        2. fcam_top_tb_full.v (../tb/)
        请选择（默认 1）：
用户: 1
Claude: 使用 Verilator 仿真...
        仿真通过！波形在 obj_dir/trace.vcd

6. 将重复任务抽象为 Skill

6.1 识别可 Skill 化的任务

判断标准：

重复频率：每周执行 >= 2 次
步骤固定：每次流程高度一致
多人使用：团队其他成员也需要
容易出错：手动操作有遗漏风险

6.2 抽象流程


观察重复任务 → 分解步骤 → 识别变量 → 编写 Skill → 测试迭代

示例：将"编译 APK"抽象为 Skill


观察：每次编译 APK 都要执行
1. cd /home/user/work/Android/FCam
2. export JAVA_HOME=/home/user/tools/jdk-17
3. ./gradlew clean assembleDebug
4. cp app/build/outputs/apk/debug/app-debug.apk /tmp/fcam_$(date +%Y%m%d_%H%M%S).apk

分解 → 识别变量：

- 项目路径（变量）

- JDK 版本（变量，默认 17）

- 输出命名（变量，默认时间戳 + 项目名）

编写 Skill：

trigger_words: [编译apk, build apk, /build-apk]

arguments:

  - name: project_dir   → 项目路径

  - name: jdk_version   → JDK 版本（默认 17）

  - name: output_name   → 输出文件名（默认自动生成）

6.3 渐进式增强


V1: 最小可用版
    - 只支持默认参数
    - 只覆盖最常见路径

V2: 参数化

    - 添加可选参数

    - 支持自定义配置

V3: 智能化

    - 自动检测项目结构

    - 多级 fallback

    - 错误自愈

7. Skill 调试与测试

7.1 查看已注册的 Skill


# 列出所有 Skill
claude skill list

# 查看特定 Skill 详情

claude skill show blog-publish

7.2 测试 Skill


# 模拟触发
echo "发布博客 /home/user/work/blog/new-post.md" | claude --skill-mode

# 或者在对话中使用 /skill-name 并观察输出

7.3 调试要点

检查 frontmatter YAML 格式是否正确（缩进、引号）
确认 trigger_words 没有与其他 Skill 冲突
验证参数名拼写与执行步骤中的引用一致
测试边界情况：空参数、特殊字符、路径不存在

7.4 日志

Skill 执行日志位置：



~/.claude/logs/skills.log

8. 参考

Claude Code Skills 官方文档
Skill 示例仓库：~/.claude/skills/ 目录下的 .md 文件

Claude Code Skills 开发指南

1. Skill 概述

核心价值

2. Skill 定义结构

2.1 存储位置

2.2 文件格式

3. 实战案例

3.1 blog-publish — 博客发布

3.2 debug-ila — FPGA 调试插桩

3.3 unit-sim — Verilog 单元仿真

Verilator（默认，最快）

Icarus Verilog

ModelSim（如果安装了）

GTKWave（最常用）

Verilator 波形

按可用性自动选择

3.4 git-push / git-share — Git 操作

添加协作者

移除协作者

查看当前协作者

3.5 md2html — 文档格式转换

3.6 md2pdf — Markdown 转 PDF/DOCX

MD → PDF

MD → DOCX

安装中文字体

检查可用字体

4. 触发词设计原则

4.1 设计准则

4.2 冲突处理

4.3 命名规范

4.4 触发词清单模板

5. 参数传递与错误处理

5.1 参数定义

5.2 参数类型

5.3 错误处理模式

5.4 交互式参数收集

6. 将重复任务抽象为 Skill

6.1 识别可 Skill 化的任务

6.2 抽象流程

6.3 渐进式增强

7. Skill 调试与测试

7.1 查看已注册的 Skill

7.2 测试 Skill

7.3 调试要点

7.4 日志

8. 参考