Reorganize workspace and archive skill artifacts
This commit is contained in:
+825
@@ -0,0 +1,825 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>mattpocock/skills 深度解析:AI Agent 工作流的工程化革命</title>
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
|
||||
<style>
|
||||
/* ===== Reset & Base ===== */
|
||||
*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
|
||||
html { scroll-behavior: smooth; }
|
||||
body {
|
||||
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans SC", Roboto, "Helvetica Neue", sans-serif;
|
||||
background: #f8fafc;
|
||||
color: #1e293b;
|
||||
line-height: 1.75;
|
||||
font-size: 16px;
|
||||
}
|
||||
|
||||
/* ===== Layout ===== */
|
||||
.wrapper { max-width: 860px; margin: 0 auto; padding: 0 24px; }
|
||||
|
||||
/* ===== Header ===== */
|
||||
.article-header {
|
||||
background: linear-gradient(135deg, #0f172a 0%, #1e3a5f 100%);
|
||||
color: #f1f5f9;
|
||||
padding: 64px 0 48px;
|
||||
margin-bottom: 48px;
|
||||
}
|
||||
.article-header h1 {
|
||||
font-size: 2rem;
|
||||
font-weight: 700;
|
||||
line-height: 1.3;
|
||||
margin-bottom: 16px;
|
||||
letter-spacing: -0.02em;
|
||||
}
|
||||
.article-header .meta {
|
||||
display: flex;
|
||||
gap: 16px;
|
||||
flex-wrap: wrap;
|
||||
font-size: 0.875rem;
|
||||
color: #94a3b8;
|
||||
}
|
||||
.article-header .tags {
|
||||
display: flex;
|
||||
gap: 8px;
|
||||
flex-wrap: wrap;
|
||||
margin-top: 12px;
|
||||
}
|
||||
.article-header .tag {
|
||||
background: rgba(255,255,255,0.1);
|
||||
border: 1px solid rgba(255,255,255,0.2);
|
||||
padding: 2px 10px;
|
||||
border-radius: 12px;
|
||||
font-size: 0.75rem;
|
||||
color: #cbd5e1;
|
||||
}
|
||||
|
||||
/* ===== Modules ===== */
|
||||
.module { margin-bottom: 48px; }
|
||||
.module-title {
|
||||
font-size: 1.35rem;
|
||||
font-weight: 700;
|
||||
color: #0f172a;
|
||||
padding-bottom: 8px;
|
||||
border-bottom: 3px solid #3b82f6;
|
||||
margin-bottom: 24px;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
/* ===== TL;DR ===== */
|
||||
.tldr-box {
|
||||
background: linear-gradient(135deg, #eff6ff, #dbeafe);
|
||||
border-left: 4px solid #3b82f6;
|
||||
border-radius: 8px;
|
||||
padding: 24px;
|
||||
margin-bottom: 32px;
|
||||
}
|
||||
.tldr-box .core { font-size: 1.1rem; font-weight: 600; margin-bottom: 12px; }
|
||||
.tldr-box .hook {
|
||||
background: #fff;
|
||||
border: 1px dashed #93c5fd;
|
||||
border-radius: 6px;
|
||||
padding: 12px 16px;
|
||||
margin-bottom: 12px;
|
||||
font-size: 0.95rem;
|
||||
}
|
||||
.tldr-box .anchor {
|
||||
font-style: italic;
|
||||
color: #475569;
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
|
||||
/* ===== Mnemonic Card ===== */
|
||||
.mnemonic-card {
|
||||
background: #fffbeb;
|
||||
border: 2px dashed #f59e0b;
|
||||
border-radius: 8px;
|
||||
padding: 20px 24px;
|
||||
margin: 24px 0;
|
||||
font-family: "Courier New", monospace;
|
||||
font-size: 0.95rem;
|
||||
line-height: 1.8;
|
||||
white-space: pre-wrap;
|
||||
}
|
||||
.mnemonic-card::before {
|
||||
content: "🧠 巧记卡片";
|
||||
display: block;
|
||||
font-family: -apple-system, sans-serif;
|
||||
font-weight: 700;
|
||||
color: #b45309;
|
||||
margin-bottom: 8px;
|
||||
font-size: 0.85rem;
|
||||
}
|
||||
|
||||
/* ===== Story ===== */
|
||||
.story-box {
|
||||
background: #f1f5f9;
|
||||
border-radius: 8px;
|
||||
padding: 20px 24px;
|
||||
margin: 24px 0;
|
||||
border-left: 3px solid #64748b;
|
||||
}
|
||||
.story-box .story-label {
|
||||
font-size: 0.8rem;
|
||||
font-weight: 700;
|
||||
color: #64748b;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.05em;
|
||||
margin-bottom: 8px;
|
||||
}
|
||||
|
||||
/* ===== ASCII Art ===== */
|
||||
.ascii-box {
|
||||
background: #0f172a;
|
||||
color: #a5f3fc;
|
||||
border-radius: 8px;
|
||||
padding: 20px 24px;
|
||||
margin: 24px 0;
|
||||
font-family: "Courier New", monospace;
|
||||
font-size: 0.85rem;
|
||||
line-height: 1.6;
|
||||
overflow-x: auto;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
/* ===== Mermaid ===== */
|
||||
.mermaid-box {
|
||||
background: #fff;
|
||||
border: 1px solid #e2e8f0;
|
||||
border-radius: 8px;
|
||||
padding: 24px;
|
||||
margin: 24px 0;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
/* ===== Tables ===== */
|
||||
.table-wrap { overflow-x: auto; margin: 24px 0; }
|
||||
table {
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
th {
|
||||
background: #f1f5f9;
|
||||
text-align: left;
|
||||
padding: 10px 14px;
|
||||
border-bottom: 2px solid #cbd5e1;
|
||||
font-weight: 600;
|
||||
}
|
||||
td {
|
||||
padding: 10px 14px;
|
||||
border-bottom: 1px solid #e2e8f0;
|
||||
}
|
||||
tr:hover td { background: #f8fafc; }
|
||||
|
||||
/* ===== Fission Section ===== */
|
||||
.fission-section {
|
||||
background: #fef2f2;
|
||||
border-left: 4px solid #dc2626;
|
||||
border-radius: 8px;
|
||||
padding: 24px;
|
||||
margin: 32px 0;
|
||||
}
|
||||
.fission-section .fission-title {
|
||||
font-size: 1.05rem;
|
||||
font-weight: 700;
|
||||
color: #991b1b;
|
||||
margin-bottom: 16px;
|
||||
}
|
||||
.fission-section .fission-label {
|
||||
display: inline-block;
|
||||
background: #dc2626;
|
||||
color: #fff;
|
||||
font-size: 0.7rem;
|
||||
font-weight: 700;
|
||||
padding: 2px 8px;
|
||||
border-radius: 4px;
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
.fission-section .search-internal {
|
||||
display: inline-block;
|
||||
background: #f1f5f9;
|
||||
border: 1px solid #cbd5e1;
|
||||
font-size: 0.75rem;
|
||||
padding: 2px 8px;
|
||||
border-radius: 4px;
|
||||
color: #475569;
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
|
||||
/* ===== FAQ ===== */
|
||||
.faq-box { margin: 24px 0; }
|
||||
details {
|
||||
border: 1px solid #e2e8f0;
|
||||
border-radius: 6px;
|
||||
margin-bottom: 8px;
|
||||
overflow: hidden;
|
||||
transition: border-color 0.2s;
|
||||
}
|
||||
details:hover { border-color: #94a3b8; }
|
||||
details[open] { border-color: #3b82f6; }
|
||||
summary {
|
||||
padding: 14px 18px;
|
||||
cursor: pointer;
|
||||
font-weight: 500;
|
||||
background: #f8fafc;
|
||||
user-select: none;
|
||||
}
|
||||
details[open] summary { border-bottom: 1px solid #e2e8f0; background: #eff6ff; }
|
||||
details .faq-body { padding: 16px 18px; font-size: 0.95rem; line-height: 1.7; }
|
||||
|
||||
/* ===== Self Test ===== */
|
||||
.quiz-box { margin: 24px 0; }
|
||||
.quiz-item {
|
||||
background: #f8fafc;
|
||||
border: 1px solid #e2e8f0;
|
||||
border-radius: 6px;
|
||||
padding: 14px 18px;
|
||||
margin-bottom: 10px;
|
||||
font-size: 0.95rem;
|
||||
counter-increment: quiz;
|
||||
}
|
||||
.quiz-item::before {
|
||||
content: counter(quiz) ". ";
|
||||
font-weight: 700;
|
||||
color: #3b82f6;
|
||||
}
|
||||
.quiz-box { counter-reset: quiz; }
|
||||
|
||||
/* ===== Code Blocks ===== */
|
||||
pre {
|
||||
background: #0f172a;
|
||||
color: #e2e8f0;
|
||||
border-radius: 8px;
|
||||
padding: 18px 20px;
|
||||
overflow-x: auto;
|
||||
font-size: 0.85rem;
|
||||
line-height: 1.6;
|
||||
margin: 20px 0;
|
||||
}
|
||||
code {
|
||||
font-family: "JetBrains Mono", "Fira Code", "Consolas", monospace;
|
||||
}
|
||||
p code, li code {
|
||||
background: #f1f5f9;
|
||||
padding: 2px 6px;
|
||||
border-radius: 4px;
|
||||
font-size: 0.85em;
|
||||
color: #b91c1c;
|
||||
}
|
||||
|
||||
/* ===== Paragraphs & Lists ===== */
|
||||
p { margin-bottom: 16px; }
|
||||
ul, ol { margin-bottom: 16px; padding-left: 24px; }
|
||||
li { margin-bottom: 6px; }
|
||||
|
||||
/* ===== Headings within content ===== */
|
||||
h2 { font-size: 1.25rem; margin: 28px 0 12px; color: #0f172a; }
|
||||
h3 { font-size: 1.1rem; margin: 24px 0 10px; color: #1e293b; }
|
||||
h4 { font-size: 1rem; margin: 20px 0 8px; color: #334155; }
|
||||
|
||||
/* ===== Blockquote ===== */
|
||||
blockquote {
|
||||
border-left: 3px solid #3b82f6;
|
||||
padding: 12px 18px;
|
||||
margin: 20px 0;
|
||||
background: #f8fafc;
|
||||
border-radius: 0 6px 6px 0;
|
||||
color: #475569;
|
||||
}
|
||||
|
||||
/* ===== ROI Box ===== */
|
||||
.roi-grid {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr 1fr;
|
||||
gap: 16px;
|
||||
margin: 24px 0;
|
||||
}
|
||||
.roi-card {
|
||||
background: #f0fdf4;
|
||||
border: 1px solid #bbf7d0;
|
||||
border-radius: 8px;
|
||||
padding: 16px;
|
||||
}
|
||||
.roi-card .roi-label { font-size: 0.75rem; font-weight: 700; color: #16a34a; text-transform: uppercase; margin-bottom: 4px; }
|
||||
.roi-card .roi-value { font-weight: 600; font-size: 1rem; }
|
||||
|
||||
/* ===== Anti-pattern Table ===== */
|
||||
.anti-pattern td:first-child { color: #dc2626; }
|
||||
.anti-pattern td:last-child { color: #16a34a; }
|
||||
|
||||
/* ===== Footer ===== */
|
||||
.article-footer {
|
||||
text-align: center;
|
||||
padding: 32px 0;
|
||||
margin-top: 48px;
|
||||
border-top: 1px solid #e2e8f0;
|
||||
color: #94a3b8;
|
||||
font-size: 0.85rem;
|
||||
}
|
||||
|
||||
/* ===== Search ===== */
|
||||
#search-input {
|
||||
width: 100%;
|
||||
padding: 12px 16px;
|
||||
border: 2px solid #e2e8f0;
|
||||
border-radius: 8px;
|
||||
font-size: 0.95rem;
|
||||
margin-bottom: 32px;
|
||||
outline: none;
|
||||
transition: border-color 0.2s;
|
||||
font-family: inherit;
|
||||
}
|
||||
#search-input:focus { border-color: #3b82f6; }
|
||||
.hidden { display: none !important; }
|
||||
|
||||
/* ===== Responsive ===== */
|
||||
@media (max-width: 640px) {
|
||||
.article-header h1 { font-size: 1.5rem; }
|
||||
.roi-grid { grid-template-columns: 1fr; }
|
||||
.wrapper { padding: 0 16px; }
|
||||
}
|
||||
|
||||
/* ===== Print ===== */
|
||||
@media print {
|
||||
.article-header { background: #fff !important; color: #000 !important; padding: 24px 0; }
|
||||
.article-header h1 { color: #000; }
|
||||
#search-input { display: none; }
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<header class="article-header">
|
||||
<div class="wrapper">
|
||||
<h1>mattpocock/skills 深度解析:AI Agent 工作流的工程化革命</h1>
|
||||
<div class="meta">
|
||||
<span>叫我小杨同学的小码酱</span>
|
||||
<span>2026-05-18</span>
|
||||
</div>
|
||||
<div class="tags">
|
||||
<span class="tag">Claude Code</span>
|
||||
<span class="tag">Agent Skills</span>
|
||||
<span class="tag">AI Engineering</span>
|
||||
<span class="tag">Workflow</span>
|
||||
<span class="tag">Matt Pocock</span>
|
||||
<span class="tag">SKILL.md</span>
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<div class="wrapper" id="content-area">
|
||||
|
||||
<input type="text" id="search-input" placeholder="搜索知识点..." autocomplete="off">
|
||||
|
||||
<!-- ===== Module 0: TL;DR ===== -->
|
||||
<section class="module">
|
||||
<h2 class="module-title">📌 核心摘要</h2>
|
||||
<div class="tldr-box">
|
||||
<p class="core">Matt Pocock 将自己在 Claude Code 中打磨了数月的 AI 协作工作流,打包成可复用、可组合的 SKILL.md 技能包,开启了"AI 技能包管理"的工程化时代。</p>
|
||||
<div class="hook"><strong>认知挂钩</strong>:就像 jQuery 插件让前端开发从"每次都从头写 JS"进化到"装个插件就行",mattpocock/skills 让 AI 编程从"每次都从头调教 AI"进化到"装个 Skill 就行"——它定义了 AI Agent 指令的封装标准。</div>
|
||||
<div class="anchor"><strong>真理锚点</strong>:"Skills for Real Engineers. Straight from my .claude directory." —— Matt Pocock</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- ===== Module 1: Concept Ice-breaking ===== -->
|
||||
<section class="module">
|
||||
<h2 class="module-title">🧊 概念破冰</h2>
|
||||
|
||||
<div class="mnemonic-card">AI 编程三板斧:
|
||||
一装技能包,行为有 template(模板化)
|
||||
二写 SKILL.md,流程有 blueprint(蓝图化)
|
||||
三用 npx skills,分发有 package(工程化)</div>
|
||||
|
||||
<div class="story-box">
|
||||
<div class="story-label">📖 故事引入</div>
|
||||
<p>想象一下:你新招了一个能力超强的实习生 Claude。每次让他写代码,你都得花 20 分钟交代一遍:"先写测试、再实现、再重构。不要直接改代码,先问我。Git push 之前必须确认。"</p>
|
||||
<p>一个月后你崩溃了——<strong>每次对话都要重新教一遍</strong>。</p>
|
||||
<p>Matt Pocock 也遇到过这个问题。他的解决方案不是"记住我说的话",而是<strong>把这些指令打包成一个个可复用的"技能包"</strong>,像乐高积木一样按需装载。于是在 2026 年 2 月 3 日,他把自己的 <code>.claude/skills/</code> 目录开源了——mattpocock/skills 诞生。</p>
|
||||
<p><strong>结果</strong>:不到 3 个月,这个仓库飙到 58k+ Stars,成为 AI 编程领域的现象级项目。</p>
|
||||
</div>
|
||||
|
||||
<div class="ascii-box">传统 AI 编程: Skill 化之后:
|
||||
┌──────────────────┐ ┌──────────────────┐
|
||||
│ "Claude,先写测试"│ │ /tdd 一键加载 │
|
||||
│ "Claude,别推代码"│ → │ /grill-me 审需求 │
|
||||
│ "Claude,问清楚" │ │ /diagnose 修bug │
|
||||
│ 每次都重说一遍 │ │ 标准化即插即用 │
|
||||
└──────────────────┘ └──────────────────┘</div>
|
||||
</section>
|
||||
|
||||
<!-- ===== Module 2: Deep Analysis ===== -->
|
||||
<section class="module">
|
||||
<h2 class="module-title">🔬 深度解析</h2>
|
||||
|
||||
<h3>三个核心设计问题</h3>
|
||||
<p>mattpocock/skills 之所以能引爆社区,是因为它精准地回答了三个问题:</p>
|
||||
<ul>
|
||||
<li><strong>Q1</strong>:如何让 AI 记住大量指令而不撑爆上下文?→ <strong>三层渐进加载</strong></li>
|
||||
<li><strong>Q2</strong>:如何让技能包可被发现、可组合?→ <strong>SKILL.md 标准化 + npx skills 包管理器</strong></li>
|
||||
<li><strong>Q3</strong>:如何让技能真正可复用而不是一次性提示词?→ <strong>依赖注入模式:setup-matt-pocock-skills</strong></li>
|
||||
</ul>
|
||||
|
||||
<h3>架构核心:三层渐进加载 (3-Layer Loading)</h3>
|
||||
<p>这是整个系统的基石。Claude Code 的上下文窗口就像一间小公寓——你不能把所有东西都堆进去。</p>
|
||||
|
||||
<div class="mermaid-box">
|
||||
<div class="mermaid">
|
||||
flowchart TD
|
||||
A["Session Init"] --> B["Layer 1"]
|
||||
subgraph B["Layer 1: Discovery"]
|
||||
B1["扫描 .claude/skills/*/SKILL.md"]
|
||||
B2["仅加载 name + description(~100 tokens)"]
|
||||
end
|
||||
B --> C{"用户触发匹配?"}
|
||||
C -- "否" --> D["停留在 L1,0 额外开销"]
|
||||
C -- "是(如输入 /tdd)" --> E["Layer 2"]
|
||||
subgraph E["Layer 2: Activation"]
|
||||
E1["加载完整 SKILL.md 正文"]
|
||||
E2["注入系统提示词"]
|
||||
E3["~5000 tokens"]
|
||||
end
|
||||
E --> F{"指令中引用外部资源?"}
|
||||
F -- "否" --> G["技能执行"]
|
||||
F -- "是(如 references/ 目录)" --> H["Layer 3"]
|
||||
subgraph H["Layer 3: Penetration"]
|
||||
H1["按需读取 references/*.md"]
|
||||
H2["按需执行 scripts/*.py"]
|
||||
H3["可变 tokens"]
|
||||
end
|
||||
H --> G
|
||||
G --> I["输出结果"]
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p><strong>设计妙处</strong>:借鉴了操作系统虚拟内存的"按需分页"思想——只加载当前需要的部分。20 个技能如果全量加载需 100k tokens,分层后仅 ~2k tokens(20 × 100)。</p>
|
||||
|
||||
<h3>SKILL.md 格式规范</h3>
|
||||
<pre><code>---
|
||||
name: tdd
|
||||
description: "Red-Green-Refactor TDD 循环"
|
||||
version: "1.0.0"
|
||||
user-invocable: true
|
||||
allowed-tools: [Read, Write, Bash, Grep]
|
||||
tags: [testing, tdd, development]
|
||||
---
|
||||
|
||||
# TDD 技能
|
||||
|
||||
## Role Definition
|
||||
你是 TDD 驱动开发专家...
|
||||
|
||||
## Workflow
|
||||
1. **Red** — 先写一个会失败的测试
|
||||
2. **Green** — 写最少代码让测试通过
|
||||
3. **Refactor** — 优化代码,保持绿色</code></pre>
|
||||
|
||||
<div class="table-wrap">
|
||||
<table>
|
||||
<tr><th>字段</th><th>约束</th><th>用途</th></tr>
|
||||
<tr><td><code>name</code></td><td>kebab-case,≤64字符</td><td>唯一标识(也是 slash command 名)</td></tr>
|
||||
<tr><td><code>description</code></td><td>≤1024字符</td><td>L1 加载项,技能发现用</td></tr>
|
||||
<tr><td><code>version</code></td><td>semver</td><td>版本管理</td></tr>
|
||||
<tr><td><code>user-invocable</code></td><td>boolean</td><td>是否可通过 <code>/name</code> 调用</td></tr>
|
||||
<tr><td><code>allowed-tools</code></td><td>数组</td><td>运行时授予的工具权限</td></tr>
|
||||
<tr><td><code>tags</code></td><td>数组</td><td>搜索分类</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<h3>目录结构</h3>
|
||||
<pre><code>.claude/skills/<skill-name>/
|
||||
├── SKILL.md # 必需 —— 技能核心
|
||||
├── REFERENCE.md # 可选 —— API 文档
|
||||
├── EXAMPLES.md # 可选 —— few-shot 示例
|
||||
├── TROUBLESHOOTING.md # 可选 —— 常见问题
|
||||
├── scripts/ # 可选 —— 可执行脚本
|
||||
├── references/ # 可选 —— 长文档
|
||||
├── templates/ # 可选 —— 输出模板
|
||||
└── resources/ # 可选 —— 数据文件</code></pre>
|
||||
|
||||
<h3>22 个技能全景</h3>
|
||||
<p>仓库包含约 22 个 SKILL.md 文件,覆盖 4 个大类:</p>
|
||||
|
||||
<h4>工程类 (Engineering)</h4>
|
||||
<div class="table-wrap">
|
||||
<table>
|
||||
<tr><th>技能</th><th>功能</th><th>设计亮点</th></tr>
|
||||
<tr><td><strong>grill-me</strong></td><td>编码前的需求追问</td><td>18+ 问题穷举盲点</td></tr>
|
||||
<tr><td><strong>grill-with-docs</strong></td><td>需求追问+文档生成</td><td>在 grill 基础上产出文档</td></tr>
|
||||
<tr><td><strong>tdd</strong></td><td>红绿重构 TDD 循环</td><td>强制不可跳过 Red 阶段</td></tr>
|
||||
<tr><td><strong>diagnose</strong></td><td>Bug 科学排查循环</td><td>假说-验证 debug 方法论</td></tr>
|
||||
<tr><td><strong>triage</strong></td><td>GitHub Issue 分类</td><td>状态机驱动的标签管理</td></tr>
|
||||
<tr><td><strong>to-prd</strong></td><td>对话→PRD 生成</td><td>模糊需求结构化</td></tr>
|
||||
<tr><td><strong>to-issues</strong></td><td>PRD→GitHub Issues</td><td>垂直切片拆解</td></tr>
|
||||
<tr><td><strong>improve-codebase-architecture</strong></td><td>架构改进建议</td><td>渐进式改进</td></tr>
|
||||
<tr><td><strong>zoom-out</strong></td><td>代码库高空视角</td><td>整体架构概览</td></tr>
|
||||
<tr><td><strong>prototype</strong></td><td>快速原型</td><td>标记为"可丢弃"</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<h4>效率类 (Productivity)</h4>
|
||||
<div class="table-wrap">
|
||||
<table>
|
||||
<tr><th>技能</th><th>功能</th><th>设计亮点</th></tr>
|
||||
<tr><td><strong>caveman</strong></td><td>压缩沟通模式</td><td>减少 ~75% token 消耗</td></tr>
|
||||
<tr><td><strong>handoff</strong></td><td>Agent 间交接文档</td><td>结构化的上下文移交</td></tr>
|
||||
<tr><td><strong>write-a-skill</strong></td><td>元技能——写新技能</td><td>自举设计,系统可自我扩展</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<h4>工具类 (Tooling & Setup)</h4>
|
||||
<div class="table-wrap">
|
||||
<table>
|
||||
<tr><th>技能</th><th>功能</th></tr>
|
||||
<tr><td><strong>setup-matt-pocock-skills</strong></td><td>一键初始化全局配置</td></tr>
|
||||
<tr><td><strong>git-guardrails-claude-code</strong></td><td>拦截危险 git 命令</td></tr>
|
||||
<tr><td><strong>setup-pre-commit</strong></td><td>Husky + lint-staged 配置</td></tr>
|
||||
<tr><td><strong>scaffold-exercises</strong></td><td>练习目录脚手架生成</td></tr>
|
||||
<tr><td><strong>migrate-to-shoehorn</strong></td><td>测试断言迁移工具</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<h3>核心设计模式</h3>
|
||||
|
||||
<h4>模式 A:依赖注入 (Dependency Injection)</h4>
|
||||
<p><code>setup-matt-pocock-skills</code> 在首次运行时自动检测项目环境:git remote → 检测 issue tracker;已有标签 → 合并而非替换;项目类型 → 选择合适的模板。结果写入 <code>docs/agents/</code> 目录下的项目配置文件。</p>
|
||||
<p><strong>类比</strong>:就像 Spring 的 IoC 容器——技能是"通用逻辑",项目配置是"注入的依赖"。</p>
|
||||
|
||||
<h4>模式 B:Grill Me 的对抗式需求澄清</h4>
|
||||
<p>让 AI 扮演一个"烦人的同事",不断对你的设计方案提出质疑。不写一行代码,只提问:</p>
|
||||
<blockquote>"你考虑过边界情况吗?这个接口的调用方是谁?错误处理策略是什么?如果用户输入为空怎么办?这个方案的性能瓶颈在哪里?..."</blockquote>
|
||||
<p><strong>为什么有效</strong>:人类在表达时容易陷入"知识的诅咒"——以为别人知道的和自己一样多。Grill Me 通过强制外化思维过程,暴露盲区。</p>
|
||||
|
||||
<h4>模式 C:垂直切片 (Vertical Slicing)</h4>
|
||||
<p><code>to-issues</code> 将 PRD 拆解为用户故事的粒度,而非技术层粒度。</p>
|
||||
<p><strong>错误方式(水平分层)</strong>:</p>
|
||||
<ul>
|
||||
<li>Issue 1: 写数据库模型</li>
|
||||
<li>Issue 2: 写 API 接口</li>
|
||||
<li>Issue 3: 写前端页面</li>
|
||||
</ul>
|
||||
<p><strong>正确方式(垂直切片)</strong>:</p>
|
||||
<ul>
|
||||
<li>Issue 1: 用户可以注册(数据库 + API + 前端)</li>
|
||||
<li>Issue 2: 用户可以登录(数据库 + API + 前端)</li>
|
||||
<li>Issue 3: 用户可以查看个人资料</li>
|
||||
</ul>
|
||||
|
||||
<h4>模式 D:Git Guardrails</h4>
|
||||
<p>安全代理,拦截操作:<code>git push</code>、<code>git reset --hard</code>、<code>git clean -fd</code>。哲学:AI 执行速度快但"犯错更快",Guardrails 是"慢下来,确保正确"的机制。</p>
|
||||
</section>
|
||||
|
||||
<!-- ===== Module 3: Deep Fission ===== -->
|
||||
<section class="module">
|
||||
<h2 class="module-title">💥 深度裂变</h2>
|
||||
|
||||
<div class="fission-section">
|
||||
<div class="fission-label">颠覆认知</div>
|
||||
<div class="fission-title">这不是"Prompt 合集",而是"软件工程范式转移"</div>
|
||||
|
||||
<p>大多数人对这个仓库的第一反应是:"哦,一堆 Claude 提示词模板。"</p>
|
||||
<p><strong>大错特错。</strong></p>
|
||||
<p>只要仔细分析,你会发现这个仓库实际上在做三件比"提示词"深刻得多的事情:</p>
|
||||
|
||||
<h4>裂变点 1:从 REPL 到 File System</h4>
|
||||
<p>传统的 AI 交互是 <strong>REPL(Read-Eval-Print Loop)</strong> 模式——你问一句,AI 答一句,所有状态在对话中流转。而 SKILL.md 的本质是将认知状态<strong>持久化到文件系统</strong>:</p>
|
||||
<pre><code>REPL 模式: 人类大脑 ←→ AI 上下文
|
||||
Skill 模式: 人类大脑 ←→ [文件系统] ←→ AI 上下文
|
||||
↑__ 可检查、可版本控制、可复用 __↑</code></pre>
|
||||
<p>当 <code>to-prd</code> 将对话内容生成为 PRD 文件时,它不再是对话中的一段文字——它是一个可审查、可修改、可版本控制的<strong>制品</strong>。这是 AI 交互从"瞬时对话"到"工程工件"的质变。</p>
|
||||
|
||||
<h4>裂变点 2:元技能——系统的自举进化</h4>
|
||||
<p><code>write-a-skill</code> 是整座大厦的基石。它是一个<strong>写技能的技能</strong>。这意味着这套系统不需要外部维护者——AI 自己就能扩展自己的能力边界。如果你遇到一个需要新技能的场景,你不需要等 Matt Pocock 发 PR。你只需要运行 <code>/write-a-skill</code>,AI 就会引导你创建新的 SKILL.md,然后它立刻就能用。</p>
|
||||
<p>这实际上是 Agent 领域的<strong>自举(Bootstrapping)</strong>——与编译器中"用 C 写 C 编译器"异曲同工。</p>
|
||||
|
||||
<div class="search-internal">🔍 搜索内化:根据 vercel-labs/skills 官方仓库及多篇技术博客验证,write-a-skill 的设计意图确实是自举(self-bootstrapping)。</div>
|
||||
|
||||
<h4>裂变点 3:The Skill Economy 已现雏形</h4>
|
||||
<p>2026 年 4-5 月,mattpocock/skills 引爆后,社区迅速跟进了多个衍生项目:</p>
|
||||
<div class="table-wrap">
|
||||
<table>
|
||||
<tr><th>项目</th><th>定位</th></tr>
|
||||
<tr><td><strong>vercel-labs/skills</strong></td><td><code>npx skills</code> CLI 工具,成为 Skill 的"npm"</td></tr>
|
||||
<tr><td><strong>ComposioHQ/awesome-codex-skills</strong></td><td>Codex 生态的技能集合</td></tr>
|
||||
<tr><td><strong>vinvcn/mattpocock-skills-zh-CN</strong></td><td>简体中文本地化版</td></tr>
|
||||
<tr><td><strong>vskill</strong></td><td>安全扫描增强版包管理器</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
<p>最耐人寻味的是,有人已经开始在 <strong>npm 上发布 SKILL.md 包</strong>,将"认知指令"作为可分发的产品。这是一个全新的软件品类——<strong>认知包(Cognitive Packages)</strong>。</p>
|
||||
<div class="search-internal">🔍 搜索内化:vercel-labs/skills 的 find-skills 技能安装量已超过 150 万次,多个行业来源(implicator.ai、CSDN、知乎等)交叉验证。</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- ===== Module 4: Actionable Guide ===== -->
|
||||
<section class="module">
|
||||
<h2 class="module-title">🎯 实战指南</h2>
|
||||
|
||||
<h3>快速安装(1 分钟)</h3>
|
||||
<pre><code># 安装全部技能
|
||||
npx skills@latest add mattpocock/skills
|
||||
|
||||
# 安装单个技能(推荐新手这样)
|
||||
npx skills@latest add mattpocock/skills --skill grill-me
|
||||
npx skills@latest add mattpocock/skills --skill tdd
|
||||
npx skills@latest add mattpocock/skills --skill git-guardrails-claude-code</code></pre>
|
||||
|
||||
<h3>初始化配置</h3>
|
||||
<pre><code># 在 Claude Code 中运行
|
||||
/setup-matt-pocock-skills</code></pre>
|
||||
|
||||
<h3>推荐起步三件套</h3>
|
||||
<p>社区公认的"最小可用组合":</p>
|
||||
<ol>
|
||||
<li><strong>git-guardrails-claude-code</strong> → 安全锁(零成本,100% 必要)</li>
|
||||
<li><strong>grill-me</strong> → 需求追问(防止冲代码)</li>
|
||||
<li><strong>tdd</strong> → TDD 循环(保证质量)</li>
|
||||
</ol>
|
||||
|
||||
<h3>如何自己写 Skill</h3>
|
||||
<pre><code>---
|
||||
name: my-custom-review
|
||||
description: "自定义代码审查技能"
|
||||
version: "1.0.0"
|
||||
user-invocable: true
|
||||
allowed-tools: [Read, Grep, Bash]
|
||||
---
|
||||
|
||||
# 我的代码审查技能
|
||||
|
||||
## Role
|
||||
你是一个专门审查 [XX 类型] 代码的专家。
|
||||
|
||||
## Checklist
|
||||
1. 检查 [关注点 A]
|
||||
2. 检查 [关注点 B]
|
||||
3. 检查 [关注点 C]
|
||||
|
||||
## Output Format
|
||||
以 Markdown 表格输出审查结果。</code></pre>
|
||||
|
||||
<h3>避坑指南</h3>
|
||||
<div class="table-wrap">
|
||||
<table class="anti-pattern">
|
||||
<tr><th>🔴 反模式</th><th>✅ 正确做法</th></tr>
|
||||
<tr><td>一个 SKILL.md 里塞满所有逻辑</td><td>保持 SKILL.md 精简,细节放 references/</td></tr>
|
||||
<tr><td>技能之间重复定义相同规则</td><td>通过配置分离(docs/agents/)共享</td></tr>
|
||||
<tr><td>忘记设置 allowed-tools</td><td>明确声明技能需要哪些工具权限</td></tr>
|
||||
<tr><td>描述太长(超 1024 字符)</td><td>描述越短,L1 发现越精准</td></tr>
|
||||
<tr><td>一次性写 10 个技能全装上</td><td>从 3 个核心技能开始,按需增加</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<h3>ROI 分析</h3>
|
||||
<div class="roi-grid">
|
||||
<div class="roi-card">
|
||||
<div class="roi-label">安装</div>
|
||||
<div class="roi-value">1 分钟 → 每个会话节省 5-10 分钟"调教"时间</div>
|
||||
</div>
|
||||
<div class="roi-card">
|
||||
<div class="roi-label">学习</div>
|
||||
<div class="roi-value">30 分钟熟悉 → Bug 排查效率提升 2-3 倍</div>
|
||||
</div>
|
||||
<div class="roi-card">
|
||||
<div class="roi-label">自定义</div>
|
||||
<div class="roi-value">1-2 小时写一个技能 → 团队标准统一</div>
|
||||
</div>
|
||||
<div class="roi-card">
|
||||
<div class="roi-label">维护</div>
|
||||
<div class="roi-value">npx skills update → 技能自动升级</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- ===== Module 5: Consolidation ===== -->
|
||||
<section class="module">
|
||||
<h2 class="module-title">📝 温故知新</h2>
|
||||
|
||||
<h3>常见陷阱 (FAQ)</h3>
|
||||
<div class="faq-box">
|
||||
|
||||
<details>
|
||||
<summary>安装后技能不生效怎么办?</summary>
|
||||
<div class="faq-body">检查是否在正确的目录下运行了 Claude Code。技能分为全局(<code>~/.claude/skills/</code>)和项目级(<code>./.claude/skills/</code>),确保安装位置正确。运行 <code>npx skills list</code> 查看已安装的技能。</div>
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>SKILL.md 与其他 Markdown 文件的区别?</summary>
|
||||
<div class="faq-body">SKILL.md 需要 YAML 前置元数据(frontmatter),且必须有 <code>name</code> 和 <code>description</code> 字段。普通 .md 文件不会被 Claude Code 识别为技能。</div>
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>不同技能的指令冲突了怎么办?</summary>
|
||||
<div class="faq-body">Claude Code 会按技能激活顺序合并指令。如果冲突,后激活的技能不会覆盖先激活的。建议在各自 SKILL.md 中使用明确的范围限定词来避免冲突。</div>
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>可以在 Cursor / Copilot 中使用吗?</summary>
|
||||
<div class="faq-body"><code>npx skills</code> CLI 支持 55+ 个 Agent 平台,包括 Cursor、GitHub Copilot、Windsurf 等。但不同平台对 SKILL.md 的解析程度不同,建议在目标平台上测试。</div>
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>一个技能可以有多个文件吗?</summary>
|
||||
<div class="faq-body">可以。SKILL.md 是入口点,可以通过 <code>scripts/</code> 目录引入脚本,通过 <code>references/</code> 引用长文档。但 L2 激活只会加载 SKILL.md 本体。</div>
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>如何更新已安装的技能?</summary>
|
||||
<div class="faq-body">运行 <code>npx skills@latest update</code>。注意:有已知 bug(vercel-labs/skills#371),某些环境下 <code>npx skills update</code> 会静默失败,建议使用 <code>npx skills@latest add <repo> --skill <name> -g -y</code> 重新安装。</div>
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>技能会消耗大量 token 吗?</summary>
|
||||
<div class="faq-body">不会。L1 阶段每个技能仅消耗约 100 tokens。L2 激活后才消耗约 5000 tokens。只有 L3 会按需扩展。对比复杂任务消耗 20k+ tokens,技能的开销可忽略不计。</div>
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>这个仓库和其他 Skill 集合相比好在哪里?</summary>
|
||||
<div class="faq-body">mattpocock/skills 的核心不是"数量多",而是"设计精良"。每个技能都遵循三层架构、渐进披露、垂直切片等设计原则,而不是简单地堆砌提示词。Matt 本人是 TypeScript 社区的核心人物,他的技能经过实际工程场景的打磨。</div>
|
||||
</details>
|
||||
|
||||
</div>
|
||||
|
||||
<h3>自测题</h3>
|
||||
<div class="quiz-box">
|
||||
<div class="quiz-item">SKILL.md 的三层加载机制是哪三层?各层分别加载什么?</div>
|
||||
<div class="quiz-item">YAML 前置元数据中,哪个字段控制技能是否可通过 <code>/name</code> 调用?</div>
|
||||
<div class="quiz-item">垂直切片(Vertical Slicing)与水平分层拆解 Issue 的区别是什么?为什么垂直切片更好?</div>
|
||||
<div class="quiz-item"><code>setup-matt-pocock-skills</code> 体现了什么设计模式?它解决了什么核心问题?</div>
|
||||
<div class="quiz-item">为什么 <code>write-a-skill</code> 是一个"元技能"?它有什么深远意义?</div>
|
||||
<div class="quiz-item">Git Guardrails 技能解决了什么核心问题?它拦截哪些操作?</div>
|
||||
<div class="quiz-item">Grill Me 技能的本质是什么?它为什么不写代码只提问?</div>
|
||||
<div class="quiz-item">如果要在团队中推广 SKILL.md 体系,你会先推荐哪 3 个核心技能?为什么?</div>
|
||||
</div>
|
||||
|
||||
<h3>参考资源</h3>
|
||||
<ul>
|
||||
<li>GitHub 仓库:<a href="https://github.com/mattpocock/skills">mattpocock/skills</a></li>
|
||||
<li>Vercel Labs Skills CLI:<a href="https://github.com/vercel-labs/skills">vercel-labs/skills</a></li>
|
||||
<li>中文翻译版:<a href="https://github.com/vinvcn/mattpocock-skills-zh-CN">vinvcn/mattpocock-skills-zh-CN</a></li>
|
||||
<li>在 Claude Code 中运行 <code>/find-skills</code> 搜索更多技能</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
</div>
|
||||
|
||||
<footer class="article-footer">
|
||||
<div class="wrapper">
|
||||
<p>© 2026 叫我小杨同学的小码酱 | 知识吸收器 v3.0 | 真理锚定已通过</p>
|
||||
</div>
|
||||
</footer>
|
||||
|
||||
<script>
|
||||
// Mermaid init
|
||||
mermaid.initialize({
|
||||
startOnLoad: true,
|
||||
theme: 'base',
|
||||
themeVariables: {
|
||||
primaryColor: '#3b82f6',
|
||||
primaryBorderColor: '#1d4ed8',
|
||||
primaryTextColor: '#1e293b',
|
||||
lineColor: '#64748b',
|
||||
secondaryColor: '#f1f5f9',
|
||||
tertiaryColor: '#eff6ff',
|
||||
fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans SC", sans-serif',
|
||||
fontSize: '14px'
|
||||
},
|
||||
flowchart: {
|
||||
useMaxWidth: true,
|
||||
htmlLabels: true,
|
||||
curve: 'basis'
|
||||
}
|
||||
});
|
||||
|
||||
// Search filter logic
|
||||
window.onload = function() {
|
||||
const input = document.getElementById('search-input');
|
||||
if(!input) return;
|
||||
input.addEventListener('input', (e) => {
|
||||
const term = e.target.value.toLowerCase().trim();
|
||||
const contentArea = document.getElementById('content-area');
|
||||
const blocks = contentArea.querySelectorAll('p, li, blockquote, .fission-section, .mnemonic-card, details, .mermaid-box, .ascii-box, .story-box, .tldr-box, .table-wrap, pre, .quiz-item, .roi-card, .faq-box details');
|
||||
|
||||
if(term.length === 0) {
|
||||
blocks.forEach(el => el.classList.remove('hidden'));
|
||||
document.querySelectorAll('h1, h2, h3, h4').forEach(el => el.classList.remove('hidden'));
|
||||
return;
|
||||
}
|
||||
|
||||
blocks.forEach(el => el.classList.add('hidden'));
|
||||
document.querySelectorAll('h1, h2, h3, h4').forEach(el => el.classList.add('hidden'));
|
||||
|
||||
blocks.forEach(el => {
|
||||
if(el.innerText.toLowerCase().includes(term)) {
|
||||
el.classList.remove('hidden');
|
||||
}
|
||||
});
|
||||
});
|
||||
};
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
+440
@@ -0,0 +1,440 @@
|
||||
---
|
||||
title: "mattpocock/skills 深度解析:AI Agent 工作流的工程化革命"
|
||||
author: "叫我小杨同学的小码酱"
|
||||
tags: [Claude Code, Agent Skills, AI Engineering, Workflow, Matt Pocock, SKILL.md]
|
||||
created: 2026-05-18
|
||||
---
|
||||
|
||||
# mattpocock/skills 深度解析:AI Agent 工作流的工程化革命
|
||||
|
||||
---
|
||||
|
||||
## 模块 0:核心摘要 (TL;DR)
|
||||
|
||||
> **一句话核心**:Matt Pocock 将自己在 Claude Code 中打磨了数月的 AI 协作工作流,打包成可复用、可组合的 SKILL.md 技能包,开启了"AI 技能包管理"的工程化时代。
|
||||
|
||||
**认知挂钩**:就像 jQuery 插件让前端开发从"每次都从头写 JS"进化到"装个插件就行",mattpocock/skills 让 AI 编程从"每次都从头调教 AI"进化到"装个 Skill 就行"——它定义了 AI Agent 指令的封装标准。
|
||||
|
||||
**真理锚点**:*"Skills for Real Engineers. Straight from my .claude directory."* —— Matt Pocock
|
||||
|
||||
---
|
||||
|
||||
## 模块 1:概念破冰 (Concept Ice-breaking)
|
||||
|
||||
### 巧记卡片
|
||||
|
||||
```
|
||||
AI 编程三板斧:
|
||||
一装技能包,行为有 template(模板化)
|
||||
二写 SKILL.md,流程有 blueprint(蓝图化)
|
||||
三用 npx skills,分发有 package(工程化)
|
||||
```
|
||||
|
||||
### 故事引入
|
||||
|
||||
想象一下:你新招了一个能力超强的实习生 Claude。每次让他写代码,你都得花 20 分钟交代一遍:"先写测试、再实现、再重构。不要直接改代码,先问我。Git push 之前必须确认。"
|
||||
|
||||
一个月后你崩溃了——**每次对话都要重新教一遍**。
|
||||
|
||||
Matt Pocock 也遇到过这个问题。他的解决方案不是"记住我说的话",而是**把这些指令打包成一个个可复用的"技能包"**,像乐高积木一样按需装载。于是在2026年2月3日,他把自己的 `.claude/skills/` 目录开源了——mattpocock/skills 诞生。
|
||||
|
||||
**结果**:不到 3 个月,这个仓库飙到 58k+ Stars,成为 AI 编程领域的现象级项目。
|
||||
|
||||
### 可视化
|
||||
|
||||
```
|
||||
传统 AI 编程: Skill 化之后:
|
||||
┌──────────────────┐ ┌──────────────────┐
|
||||
│ "Claude,先写测试"│ │ /tdd 一键加载 │
|
||||
│ "Claude,别推代码"│ → │ /grill-me 审需求 │
|
||||
│ "Claude,问清楚" │ │ /diagnose 修bug │
|
||||
│ 每次都重说一遍 │ │ 标准化即插即用 │
|
||||
└──────────────────┘ └──────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模块 2:深度解析 (Deep Analysis)
|
||||
|
||||
### 2.1 三个核心设计问题
|
||||
|
||||
Matt Pocock 的 skills 仓库之所以能引爆社区,是因为它精准地回答了三个问题:
|
||||
|
||||
**Q1: 如何让 AI 记住大量指令而不撑爆上下文?**
|
||||
→ **三层渐进加载 (Progressive 3-Layer Loading)**
|
||||
|
||||
**Q2: 如何让技能包可被发现、可组合?**
|
||||
→ **SKILL.md 标准化 + npx skills 包管理器**
|
||||
|
||||
**Q3: 如何让技能真正可复用而不是一次性提示词?**
|
||||
→ **依赖注入模式:setup-matt-pocock-skills**
|
||||
|
||||
### 2.2 架构核心:三层渐进加载 (3-Layer Loading)
|
||||
|
||||
这是整个系统的基石。Claude Code 的上下文窗口就像一间小公寓——你不能把所有东西都堆进去。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["Session Init"] --> B["Layer 1"]
|
||||
subgraph B["Layer 1: Discovery"]
|
||||
B1["扫描 .claude/skills/*/SKILL.md"]
|
||||
B2["仅加载 name + description(~100 tokens)"]
|
||||
end
|
||||
B --> C{"用户触发匹配?"}
|
||||
C -- "否" --> D["停留在 L1,0 额外开销"]
|
||||
C -- "是(如输入 /tdd)" --> E["Layer 2"]
|
||||
subgraph E["Layer 2: Activation"]
|
||||
E1["加载完整 SKILL.md 正文"]
|
||||
E2["注入系统提示词"]
|
||||
E3["~5000 tokens"]
|
||||
end
|
||||
E --> F{"指令中引用外部资源?"}
|
||||
F -- "否" --> G["技能执行"]
|
||||
F -- "是(如 references/ 目录)" --> H["Layer 3"]
|
||||
subgraph H["Layer 3: Penetration"]
|
||||
H1["按需读取 references/*.md"]
|
||||
H2["按需执行 scripts/*.py"]
|
||||
H3["可变 tokens"]
|
||||
end
|
||||
H --> G
|
||||
G --> I["输出结果"]
|
||||
```
|
||||
|
||||
**设计妙处**:这个机制借鉴了操作系统虚拟内存的"按需分页"思想——只加载当前需要的部分,极大节省了上下文空间。如果你有 20 个技能,每个占 5000 tokens,一次性加载就是 100k tokens。但有了分层设计,实际消耗仅 2k tokens 左右(20 × 100 = 2000)。
|
||||
|
||||
### 2.3 SKILL.md 格式规范
|
||||
|
||||
每个技能的核心是一个 Markdown 文件,带 YAML 前置元数据:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: tdd
|
||||
description: "Red-Green-Refactor TDD 循环"
|
||||
version: "1.0.0"
|
||||
user-invocable: true
|
||||
allowed-tools: [Read, Write, Bash, Grep]
|
||||
tags: [testing, tdd, development]
|
||||
---
|
||||
|
||||
# TDD 技能
|
||||
|
||||
## Role Definition
|
||||
你是 TDD 驱动开发专家...
|
||||
|
||||
## Workflow
|
||||
1. **Red** — 先写一个会失败的测试
|
||||
2. **Green** — 写最少代码让测试通过
|
||||
3. **Refactor** — 优化代码,保持绿色
|
||||
|
||||
## Constraints
|
||||
- 严禁跳过 Red 阶段
|
||||
- 每次重构后运行全部测试
|
||||
```
|
||||
|
||||
**YAML 字段详解**:
|
||||
|
||||
| 字段 | 约束 | 用途 |
|
||||
|------|------|------|
|
||||
| `name` | kebab-case,≤64字符 | 唯一标识(也是 slash command 名) |
|
||||
| `description` | ≤1024字符 | L1 加载项,技能发现用 |
|
||||
| `version` | semver | 版本管理 |
|
||||
| `user-invocable` | boolean | 是否可通过 `/name` 调用 |
|
||||
| `allowed-tools` | 数组 | 技能运行时授予的工具权限 |
|
||||
| `tags` | 数组 | 用于搜索分类 |
|
||||
|
||||
### 2.4 目录结构
|
||||
|
||||
```
|
||||
.claude/skills/<skill-name>/
|
||||
├── SKILL.md # 必需 —— 技能的核心
|
||||
├── REFERENCE.md # 可选 —— API 文档、规则
|
||||
├── EXAMPLES.md # 可选 —— few-shot 示例
|
||||
├── TROUBLESHOOTING.md # 可选 —— 常见问题
|
||||
├── scripts/ # 可选 —— 可执行脚本
|
||||
│ ├── process.py
|
||||
│ └── utils.js
|
||||
├── references/ # 可选 —— 长文档
|
||||
│ └── style-guide.md
|
||||
├── templates/ # 可选 —— 输出模板
|
||||
│ └── report-template.txt
|
||||
└── resources/ # 可选 —— 数据文件
|
||||
└── template.xlsx
|
||||
```
|
||||
|
||||
**渐进披露的精髓**:`SKILL.md` 保持足够短(<5000 tokens),只写核心流程。所有长文档放在 `references/`,仅在需要时由 `SKILL.md` 中的指令触发加载。这样既保证了功能的完整性,又维持了上下文的轻量。
|
||||
|
||||
### 2.5 22 个技能全景
|
||||
|
||||
Matt Pocock 的仓库包含约 22 个 SKILL.md 文件,覆盖 4 个大类:
|
||||
|
||||
#### 工程类 (Engineering)
|
||||
| 技能 | 功能 | 设计亮点 |
|
||||
|------|------|---------|
|
||||
| **grill-me** | 编码前的需求追问 | 18+ 问题穷举盲点,不写代码只提问 |
|
||||
| **grill-with-docs** | 需求追问+文档生成 | 在 grill 基础上产出文档产物 |
|
||||
| **tdd** | 红绿重构 TDD 循环 | 强制不可跳过 Red 阶段 |
|
||||
| **diagnose** | Bug 科学排查循环 | 基于假说-验证的 debug 方法论 |
|
||||
| **triage** | GitHub Issue 分类 | 状态机驱动的标签化管理 |
|
||||
| **to-prd** | 对话→PRD 生成 | 将模糊需求转化为结构化的 PRD |
|
||||
| **to-issues** | PRD→GitHub Issues | 垂直切片拆解,而非分层拆解 |
|
||||
| **improve-codebase-architecture** | 架构改进建议 | 识别技术债并提出渐进式改进 |
|
||||
| **zoom-out** | 代码库高空视角 | 整体架构概览,不漏细节 |
|
||||
| **prototype** | 快速原型 | 明确标记为"可丢弃" |
|
||||
|
||||
#### 效率类 (Productivity)
|
||||
| 技能 | 功能 | 设计亮点 |
|
||||
|------|------|---------|
|
||||
| **caveman** | 压缩沟通模式 | 减少约 75% token 消耗的极简回复 |
|
||||
| **handoff** | Agent 间交接文档 | 结构化的上下文移交格式 |
|
||||
| **write-a-skill** | 元技能——写新技能 | 自举设计,系统可自我扩展 |
|
||||
|
||||
#### 工具类 (Tooling & Setup)
|
||||
| 技能 | 功能 |
|
||||
|------|------|
|
||||
| **setup-matt-pocock-skills** | 一键初始化全局配置 |
|
||||
| **git-guardrails-claude-code** | 拦截危险 git 命令 |
|
||||
| **setup-pre-commit** | Husky + lint-staged 配置 |
|
||||
| **scaffold-exercises** | 练习目录脚手架生成 |
|
||||
| **migrate-to-shoehorn** | 测试断言迁移工具 |
|
||||
|
||||
### 2.6 核心设计模式
|
||||
|
||||
#### 模式 A: 依赖注入 (Dependency Injection)
|
||||
`setup-matt-pocock-skills` 在首次运行时,自动检测项目环境:
|
||||
- git remote → 检测 issue tracker
|
||||
- 已有标签 → 合并,而非替换
|
||||
- 项目类型 → 选择合适的模板
|
||||
|
||||
结果写入 `docs/agents/` 目录下的项目配置文件。
|
||||
|
||||
**类比**:就像 Spring 的 IoC 容器——技能是"通用逻辑",项目配置是"注入的依赖"。
|
||||
|
||||
#### 模式 B: Grill Me 的对抗式需求澄清
|
||||
这是一个反直觉的设计——**让 AI 扮演一个"烦人的同事"**,不断对你的设计方案提出质疑。它不写一行代码,只提问:
|
||||
|
||||
> "你考虑过边界情况吗?这个接口的调用方是谁?错误处理策略是什么?如果用户输入为空怎么办?这个方案的性能瓶颈在哪里?..."
|
||||
|
||||
**为什么有效**:人类在表达时容易陷入"知识的诅咒"——以为别人知道的和自己一样多。Grill Me 通过强制外化思维过程,暴露了那些"你以为想清楚了但其实没有"的盲区。
|
||||
|
||||
#### 模式 C: 垂直切片 (Vertical Slicing)
|
||||
`to-issues` 将 PRD 拆解为用户故事的粒度,而非技术层粒度。
|
||||
|
||||
**错误方式**(水平分层):
|
||||
- Issue 1: 写数据库模型
|
||||
- Issue 2: 写 API 接口
|
||||
- Issue 3: 写前端页面
|
||||
|
||||
**正确方式**(垂直切片):
|
||||
- Issue 1: 用户可以注册(数据库 + API + 前端)
|
||||
- Issue 2: 用户可以登录(数据库 + API + 前端)
|
||||
- Issue 3: 用户可以查看个人资料
|
||||
|
||||
**原因**:每个垂直切片都是**可独立交付**的——开发完一个就真正能用,而不是"所有模型都写完了但啥也看不到"。
|
||||
|
||||
#### 模式 D: Git Guardrails
|
||||
这个技能本质上是一个**安全代理**,它拦截以下操作:
|
||||
- `git push` → 要求先拉取最新代码
|
||||
- `git reset --hard` → 要求显示将被丢弃的变更
|
||||
- `git clean -fd` → 需要明确确认
|
||||
|
||||
**哲学**:AI 执行速度很快,但快意味着"犯错更快"。Guardrails 是"慢下来,确保正确"的机制。
|
||||
|
||||
---
|
||||
|
||||
## 模块 3:深度裂变 (Deep Fission)
|
||||
|
||||
### 🔍 颠覆认知:这不是"Prompt 合集",而是"软件工程范式转移"
|
||||
|
||||
大多数人对这个仓库的第一反应是:"哦,一堆 Claude 提示词模板。"
|
||||
|
||||
**大错特错。**
|
||||
|
||||
只要仔细分析,你会发现这个仓库实际上在做三件比"提示词"深刻得多的事情:
|
||||
|
||||
#### 裂变点 1: 从 REPL 到 File System
|
||||
|
||||
传统的 AI 交互是 **REPL(Read-Eval-Print Loop)** 模式——你问一句,AI 答一句,所有状态在对话中流转。而 SKILL.md 的本质是将认知状态**持久化到文件系统**:
|
||||
|
||||
```
|
||||
REPL 模式: 人类大脑 ←→ AI 上下文
|
||||
Skill 模式: 人类大脑 ←→ [文件系统] ←→ AI 上下文
|
||||
↑__ 可检查、可版本控制、可复用 __↑
|
||||
```
|
||||
|
||||
当 `to-prd` 将对话内容生成为 PRD 文件时,它不再是对话中的一段文字——它是一个可审查、可修改、可版本控制的**制品**。这是 AI 交互从"瞬时对话"到"工程工件"的质变。
|
||||
|
||||
#### 裂变点 2: 元技能——系统的自举进化
|
||||
|
||||
`write-a-skill` 是整座大厦的基石。它是一个**写技能的技能**。这意味着:
|
||||
|
||||
> 这套系统不需要外部维护者——AI 自己就能扩展自己的能力边界。
|
||||
|
||||
如果你遇到一个需要新技能的场景,你不需要等 Matt Pocock 发 PR。你只需要运行 `/write-a-skill`,AI 就会引导你创建新的 SKILL.md,然后它立刻就能用。这实际上是 Agent 领域的**自举(Bootstrapping)**——与编译器中"用 C 写 C 编译器"异曲同工。
|
||||
|
||||
#### 裂变点 3: The Skill Economy 已现雏形
|
||||
|
||||
2026 年 4-5 月,mattpocock/skills 引爆后,社区迅速跟进了多个衍生项目:
|
||||
|
||||
| 项目 | 定位 |
|
||||
|------|------|
|
||||
| **vercel-labs/skills** | `npx skills` CLI 工具,成为 Skill 的"npm" |
|
||||
| **ComposioHQ/awesome-codex-skills** | Codex 生态的技能集合 |
|
||||
| **vinvcn/mattpocock-skills-zh-CN** | 简体中文本地化版 |
|
||||
| **vskill** | 安全扫描增强版包管理器 |
|
||||
|
||||
最耐人寻味的是,有人已经开始在 **npm 上发布 SKILL.md 包**,将"认知指令"作为一种可分发的产品。这是一个全新的软件品类——**认知包 (Cognitive Packages)**。
|
||||
|
||||
🔍 **搜索内化**:根据多个来源验证,vercel-labs/skills 的 `find-skills` 技能安装量已超过 150 万次,头部技能的安装量达到了数十万级别。这已经不仅仅是"开发者玩具"的规模。
|
||||
|
||||
---
|
||||
|
||||
## 模块 4:实战指南 (Actionable Guide)
|
||||
|
||||
### 4.1 如何开始
|
||||
|
||||
#### 快速安装(1 分钟)
|
||||
|
||||
```bash
|
||||
# 安装全部技能
|
||||
npx skills@latest add mattpocock/skills
|
||||
|
||||
# 安装单个技能(推荐新手这样)
|
||||
npx skills@latest add mattpocock/skills --skill grill-me
|
||||
npx skills@latest add mattpocock/skills --skill tdd
|
||||
npx skills@latest add mattpocock/skills --skill git-guardrails-claude-code
|
||||
```
|
||||
|
||||
#### 初始化配置
|
||||
|
||||
```bash
|
||||
# 在 Claude Code 中运行
|
||||
/setup-matt-pocock-skills
|
||||
```
|
||||
|
||||
该命令会自动:
|
||||
1. 检测你的 git remote
|
||||
2. 设置 issue tracker 配置
|
||||
3. 初始化 `docs/agents/` 目录
|
||||
|
||||
### 4.2 推荐起步三件套
|
||||
|
||||
社区公认的"最小可用组合":
|
||||
|
||||
```
|
||||
1. git-guardrails-claude-code → 安全锁(零成本,100% 必要)
|
||||
2. grill-me → 需求追问(防止冲代码)
|
||||
3. tdd → TDD 循环(保证质量)
|
||||
```
|
||||
|
||||
### 4.3 如何自己写 Skill
|
||||
|
||||
参考 `/write-a-skill` 的引导流程:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-custom-review
|
||||
description: "自定义代码审查技能"
|
||||
version: "1.0.0"
|
||||
user-invocable: true
|
||||
allowed-tools: [Read, Grep, Bash]
|
||||
---
|
||||
|
||||
# 我的代码审查技能
|
||||
|
||||
## Role
|
||||
你是一个专门审查 [XX 类型] 代码的专家。
|
||||
|
||||
## Checklist
|
||||
1. 检查 [关注点 A]
|
||||
2. 检查 [关注点 B]
|
||||
3. 检查 [关注点 C]
|
||||
|
||||
## Output Format
|
||||
以 Markdown 表格输出审查结果。
|
||||
```
|
||||
|
||||
### 4.4 避坑指南
|
||||
|
||||
| 🔴 反模式 | ✅ 正确做法 |
|
||||
|-----------|-----------|
|
||||
| 一个 SKILL.md 里塞满所有逻辑 | 保持 SKILL.md 精简,细节放 references/ |
|
||||
| 技能之间重复定义相同规则 | 通过配置分离(`docs/agents/`)共享 |
|
||||
| 忘记设置 `allowed-tools` | 明确声明技能需要哪些工具权限 |
|
||||
| 描述太长(超 1024 字符) | 描述越短,L1 发现越精准 |
|
||||
| 一次性写 10 个技能全装上 | 从 3 个核心技能开始,按需增加 |
|
||||
|
||||
### 4.5 ROI 分析
|
||||
|
||||
| 投入 | 产出 |
|
||||
|------|------|
|
||||
| 安装:1 分钟 | 每个会话节省 5-10 分钟"调教"时间 |
|
||||
| 学习:30 分钟熟悉各技能 | Bug 排查效率提升 2-3 倍 |
|
||||
| 自定义:1-2 小时写一个技能 | 团队标准统一,新人上手更快 |
|
||||
|
||||
---
|
||||
|
||||
## 模块 5:温故知新 (Consolidation)
|
||||
|
||||
### 常见陷阱 (FAQ)
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: 安装后技能不生效怎么办?</strong></summary>
|
||||
检查是否在正确的目录下运行了 Claude Code。技能分为全局(`~/.claude/skills/`)和项目级(`./.claude/skills/`),确保安装位置正确。运行 `npx skills list` 查看已安装的技能。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: SKILL.md 与其他 Markdown 文件的区别?</strong></summary>
|
||||
SKILL.md 需要 YAML 前置元数据(frontmatter),且必须有 `name` 和 `description` 字段。普通 .md 文件不会被 Claude Code 识别为技能。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: 不同技能的指令冲突了怎么办?</strong></summary>
|
||||
Claude Code 会按技能激活顺序合并指令。如果冲突,后激活的技能不会覆盖先激活的。建议在各自 SKILL.md 中使用明确的范围限定词(比如"/diagnose 场景下")来避免冲突。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: 可以在 Cursor / Copilot 中使用吗?</strong></summary>
|
||||
`npx skills` CLI 支持 55+ 个 Agent 平台,包括 Cursor、GitHub Copilot、Windsurf 等。但不同平台对 SKILL.md 的解析程度不同,建议在目标平台上测试。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: 一个技能可以有多个文件吗?</strong></summary>
|
||||
可以。SKILL.md 是入口点,可以通过 `scripts/` 目录引入脚本,通过 `references/` 引用长文档。但 L2 激活只会加载 SKILL.md 本体。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: 如何更新已安装的技能?</strong></summary>
|
||||
运行 `npx skills@latest update`。注意:目前有一个已知 bug(vercel-labs/skills#371),某些环境下 `npx skills update` 会静默失败,建议使用 `npx skills@latest add <repo> --skill <name> -g -y` 重新安装。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: 技能会消耗大量 token 吗?</strong></summary>
|
||||
不会。L1 阶段每个技能仅消耗约 100 tokens。L2 激活后才消耗约 5000 tokens。只有 L3 会按需扩展。对比一个复杂的任务可能消耗 20k+ tokens,技能的开销可以忽略不计。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: 这个仓库和其他 Skill 集合相比好在哪里?</strong></summary>
|
||||
mattpocock/skills 的核心不是"数量多",而是"设计精良"。每个技能都遵循三层架构、渐进披露、垂直切片等设计原则,而不是简单地堆砌提示词。Matt 本人是 TypeScript 社区的核心人物,他的技能经过实际工程场景的打磨。
|
||||
</details>
|
||||
|
||||
### 自测题
|
||||
|
||||
1. **SKILL.md 的三层加载机制是哪三层?各层分别加载什么?**
|
||||
2. **YAML 前置元数据中,哪个字段控制技能是否可通过 `/name` 调用?**
|
||||
3. **垂直切片(Vertical Slicing)与水平分层拆解 Issue 的区别是什么?为什么垂直切片更好?**
|
||||
4. **`setup-matt-pocock-skills` 体现了什么设计模式?它解决了什么核心问题?**
|
||||
5. **为什么 `write-a-skill` 是一个"元技能"?它有什么深远意义?**
|
||||
6. **Git Guardrails 技能解决了什么核心问题?它拦截哪些操作?**
|
||||
7. **Grill Me 技能的本质是什么?它为什么不写代码只提问?**
|
||||
8. **如果要在团队中推广 SKILL.md 体系,你会先推荐哪 3 个核心技能?为什么?**
|
||||
|
||||
### 参考资源
|
||||
|
||||
- GitHub 仓库:https://github.com/mattpocock/skills
|
||||
- Vercel Labs Skills CLI:https://github.com/vercel-labs/skills
|
||||
- 中文翻译版:https://github.com/vinvcn/mattpocock-skills-zh-CN
|
||||
- 搜索安装:在 Claude Code 中运行 `/find-skills`
|
||||
|
||||
---
|
||||
|
||||
*© 2026 叫我小杨同学的小码酱 | 知识吸收器 v3.0 | 真理锚定已通过*
|
||||
Reference in New Issue
Block a user