Free Preview
先试读：Claude Code Skill 编写、验证与封存指南
很多 Skill 写不好，不是 Markdown 写错了，而是一开始就没有定义清楚它要解决哪一类任务。
• 它服务哪类任务？例如“检查静态落地页上线质量”，不要写成“处理前端工作”。
这篇能解决什么问题
- 把一句模糊需求改成 AI 能执行、你能验收的任务卡。
- 知道执行前要先检查哪些文件、风险点和验证命令。
- 避免 AI 顺手改无关内容，最后只交付可审、可回退的改动。
付费后能看到哪些内容
- 先定义任务，不要先写文件
- 一个 Skill 文件夹应该长什么样
- 最小版本长这样
- SKILL.md 怎么写才会被正确触发
可以先照着试的一句话
这是我要改的功能：___。请先阅读项目结构，列出会动哪些文件、风险点和验证命令；等我确认范围后，再开始做最小改动。
试读到这里先判断是否对你的任务有用；完整文章会继续展开步骤、案例、模板和避坑细节。
先定义任务，不要先写文件
很多 Skill 写不好，不是 Markdown 写错了，而是一开始就没有定义清楚它要解决哪一类任务。
写 Skill 前，先回答四个问题：
• 它服务哪类任务？例如“检查静态落地页上线质量”，不要写成“处理前端工作”。
• 用户会怎么说？例如“帮我检查这个活动页能不能发上线”，这些句子会影响 description。
• 它需要哪些固定资源？例如检查清单、品牌文案规范、脚本、模板、示例输出。
• 什么算完成？例如输出风险等级、问题列表、修复建议、需要人工确认的点。
我们用一个模拟场景贯穿本文：一个内容团队经常让 Claude Code 审查静态落地页，要求检查移动端布局、CTA 文案、链接、埋点、付费墙可见性和发布风险。
这个任务重复出现、流程固定、验收标准明确，因此适合做成 landing-page-review Skill。
注意，这个 Skill 不应该包含真实客户资料、真实订单、真实密钥，也不应该引用某个真实项目名。所有示例都使用模拟文件和通用路径，比如 ~/projects/demo-site/。
一个 Skill 文件夹应该长什么样
最小可用 Skill 只需要一个 SKILL.md，但真正好用的 Skill 往往会把材料拆出去。
landing-page-review/
├── SKILL.md
├── references/
│ ├── launch-checklist.md
│ └── copy-quality.md
├── scripts/
│ └── check_links.mjs
└── assets/
└── report-template.mdSKILL.md
必须存在。放触发描述、核心流程、资源导航和关键限制。
references/
放详细参考资料。只有需要时再读，避免一次加载过多上下文。
scripts/
放可重复执行的脚本。适合链接检查、格式转换、批量处理等确定性任务。
assets/
放输出模板、样式文件、示例素材等。通常不是给模型逐字阅读的。
agents/
有些环境会用它存 UI 展示信息，例如显示名、简短描述和默认提示。
不要乱加
不要加一堆 README、CHANGELOG、安装说明，把 Skill 变成文档垃圾堆。
最小版本长这样
landing-page-review/
└── SKILL.md如果 Skill 只是一个清晰流程，没有脚本和外部资料，最小版本就够了。不要为了“看起来专业”硬加目录。
SKILL.md 怎么写才会被正确触发
description 是触发关键，正文是执行关键。两者不要混在一起。
SKILL.md 开头必须有 YAML frontmatter。最核心字段是 name 和 description。
---
name: landing-page-review
description: Review static HTML/CSS/JS landing pages before launch. Use when checking responsive layout, CTA clarity, broken links, analytics hooks, paywall visibility, accessibility basics, and publish readiness.
---
# Landing Page Review
Use this workflow when the user asks to review a landing page before publishing.
## Workflow
1. Identify the page files and linked assets.
2. Inspect layout, content, links, scripts, and publishing risks.
3. Run available deterministic checks.
4. Return findings ordered by severity with file references.
5. Separate must-fix issues from optional polish.description 的四个要素
一个好的 description 应该包含：
• 任务动作：review、create、translate、audit、generate、deploy。
• 处理对象：HTML landing page、PPTX deck、CSV workbook、Gmail thread。
• 触发场景：before launch、when localizing design、when triaging inbox。
• 关键能力：responsive layout、tracked changes、charts、privacy review。
| 问题 | 坏写法 | 更好写法 |
|---|---|---|
| 太泛 | Help with websites. |
Review static HTML/CSS landing pages before launch for layout, links, CTA clarity, and analytics hooks. |
| 太像广告 | Make pages amazing and professional. |
Use when the user asks for launch readiness review of a marketing or product landing page. |
| 只写功能不写触发 | Checks links and layout. |
Use when checking a page before publishing or after frontend copy/layout changes. |
Claude Code 是先看元数据判断要不要加载 Skill。正文只有在触发之后才会读到。也就是说，“何时使用这个 Skill”的关键信息要写进 description，不能只写在正文里。
scripts、references、assets 怎么拆
好的 Skill 不会把所有内容堆在 SKILL.md。它会让 Claude Code 按需读取。
什么时候放 scripts
脚本适合处理确定性任务：链接检查、CSV 清洗、图片尺寸扫描、Markdown 转换、PDF 分割、HTML 结构检查。只要你发现 Claude Code 每次都在重写同一段代码，就应该考虑把它沉淀成脚本。
// scripts/check_links.mjs
// 模拟示例：检查 HTML 文件里的站内链接是否指向存在的本地文件
import fs from 'node:fs';
import path from 'node:path';
const htmlPath = process.argv[2];
const root = process.argv[3] || process.cwd();
const html = fs.readFileSync(htmlPath, 'utf8');
const links = [...html.matchAll(/href="([^"]+)"/g)].map(m => m[1]);
for (const link of links) {
if (!link.startsWith('/')) continue;
const target = path.join(root, link.replace(/^\//, ''));
if (!fs.existsSync(target) && !fs.existsSync(target + '/index.html')) {
console.log(`MISSING ${link}`);
}
}什么时候放 references
参考资料适合放详细规范：设计标准、文案风格、数据字段说明、API 约定、验收清单。它们不一定每次都要加载，所以不要全部塞进 SKILL.md。
references/
├── launch-checklist.md # 上线检查清单
├── copy-quality.md # 文案质量标准
└── analytics-rules.md # 埋点检查规则什么时候放 assets
模板、图片、示例文件、输出格式样板可以放进 assets/。例如报告模板：
assets/report-template.md
# 页面上线审查报告
## 必须修复
- ...
## 建议优化
- ...
## 验证结果
- 移动端：
- 链接：
- 付费墙：
- 埋点：SKILL.md 放“路标”，references 放“细节”，scripts 放“确定性动作”，assets 放“输出素材”。
如果一个参考文件很长，就在 SKILL.md 里写清楚什么时候读它，而不是默认全部读。
怎么验证、封存和分享
写完 Skill 只是第一步。能不能长期复用，取决于验证和封存。
先做结构验证
检查目录名、SKILL.md 是否存在、YAML frontmatter 是否正确、name 是否符合命名规则、description 是否能说明触发场景。
再做触发验证
用用户真实会说的话测试，例如“帮我检查这个活动页能不能上线”。观察 Claude Code 是否会使用这个 Skill。
然后做输出验证
看输出是否稳定包含严重程度、文件位置、问题说明、修复建议和需要人工确认的点。
最后做反例验证
问一个不相关任务，比如“帮我写一封邮件”。如果 Skill 也被调用，说明 description 写得太宽。
封存成可分享目录
封存 Skill 时，最稳的是保留完整文件夹结构：
landing-page-review/
├── SKILL.md
├── references/
├── scripts/
└── assets/如果要发给别人，可以压缩这个文件夹：
zip -r landing-page-review.zip landing-page-review接收者解压后，可以放到个人 Skill 目录、项目 .claude/skills/ 目录，或者进一步打包进插件。分享前要做一次隐私检查：不要包含真实客户数据、内部 URL、真实密钥、个人账号、公司未公开资料。
团队协作时推荐放项目目录
如果这个 Skill 是某个项目必需的，例如“本项目上线前审查流程”，应该放在：
.claude/
└── skills/
└── landing-page-review/
└── SKILL.md这样它可以跟项目一起走。团队成员拉取项目后，Claude Code 在这个项目中就能看到同一套 Skill。
涉及部署、付款、权限、删除、外部发送、线上发布的 Skill，不要让 Claude Code 自主完成最后一步。Skill 应该明确要求：执行前列出变更对象、风险、验证方式，并等待用户确认。
- 先定义任务边界：服务哪类任务、用户怎么说、完成标准是什么。
- 再写
SKILL.md：description写触发场景，正文写执行流程。 - 能拆就拆：详细规范放
references/，确定性动作放scripts/，模板素材放assets/。 - 验证要包含正例、反例和输出质量，不只看文件格式是否正确。
- 封存分享前先做隐私检查，确保没有真实客户、密钥、内部项目和个人信息。