从零构建 Claude Skill：以 Hugo 博客发布为例

di4urp@gmail.com (taevas) — Thu, 12 Mar 2026 12:00:00 +0800

背景

Claude Code 支持 Skill 系统，允许用户创建可复用的能力模块。本文以实际创建的 hugo skill 为例，详解 Skill 的构建过程。

什么是 Skill

Skill 是 Claude Code 的扩展机制，本质是一个包含指令和资源的目录：

skill-name/
├── SKILL.md # 核心：YAML frontmatter + Markdown 指令
├── scripts/ # 可执行脚本
├── references/ # 参考文档
└── assets/ # 输出资源

创建步骤

第一步：定义使用场景

明确 skill 要解决的问题。以 hugo skill 为例：

场景	用户输入	预期行为
检查环境	`/hugo`	检测 Hugo 安装和站点
创建文章	`/hugo 写一篇 Go 教程`	生成内容并发布
指定路径	`/hugo --path ~/myblog`	使用指定站点

第二步：规划资源需求

分析需要哪些辅助资源：

hugo/
├── scripts/
│ └── detect_hugo_site.py # 检测 Hugo 站点
├── references/
│ └── front-matter.md # Front matter 格式参考
└── SKILL.md

脚本的作用：检测站点需要遍历目录、检查配置文件，逻辑复杂，用 Python 脚本更可靠。

参考文档的作用：Front matter 有多种格式（TOML/YAML），放入 reference 按需加载。

第三步：编写 SKILL.md

Frontmatter 设计

---
name: hugo
description: "Publish content to Hugo blog. Use when user invokes /hugo command..."
---

description 是触发机制的关键：

必须包含 skill 功能
必须包含触发条件
会被 Claude 持续加载在上下文中

工作流设计

## Workflow

1. **Check Hugo installation**
2. **Determine Hugo site path**
3. **Determine content**
4. **Determine front matter format**
5. **Create the post**

每一步都有明确的指令，包括命令示例和预期输出。

第四步：实现脚本

# scripts/detect_hugo_site.py
def is_hugo_site(directory: str) -> dict:
 # 检查 config.toml / hugo.toml / config.yaml
 config_names = ["config", "hugo"]
 config_extensions = [".toml", ".yaml", ".yml", ".json"]

 # 返回检测结果
 return {
 "is_hugo_site": bool,
 "config_file": str,
 "content_dir": str,
 "existing_posts": list
 }

第五步：验证和迭代

# 测试脚本
python3 scripts/detect_hugo_site.py /path/to/hugo/site

# 实际调用
/hugo 写一篇测试文章

设计原则

1. 渐进式披露

Skill 采用三层加载机制：

层级	内容	加载时机
Metadata	name + description	始终
SKILL.md body	工作流指令	触发后
references/	详细文档	按需

2. 简洁至上

SKILL.md 应控制在 500 行以内，详细内容放入 references。

3. 自由度匹配

自由度	适用场景	hugo skill 示例
高	多种有效方案	文章内容由 LLM 生成
中	有首选模式	Front matter 格式检测
低	必须精确执行	站点检测脚本

最终结构

hugo/
├── SKILL.md # 2.8KB，核心指令
├── scripts/
│ └── detect_hugo_site.py # 92 行，站点检测
├── references/
│ └── front-matter.md # Front matter 格式参考
└── LICENSE.txt

总结

构建 Skill 的核心是明确场景 → 规划资源 → 精简指令。好的 skill 应该：

在 description 中清晰描述触发条件
用脚本处理确定性任务
用 references 存放详细文档
保持 SKILL.md 精简

自动化 on Tao