Lessons from Building Claude Code: How We Use Skills

URL: https://x.com/trq212/status/2033949937936085378
Source: x
Author: trq212
Local evidence: 文章阅读/2026-07-23-claude-code-skills-lessons/学习笔记.md
Fetch method: local Obsidian note from X article
Added: 2026-07-23

中文摘要

这篇 Claude Code Skills 实践分享把 skills 分成 API 参考、产品验证、数据抓取分析、业务流程、脚手架、代码质量、CI/CD、Runbook 等类型。最值得复用的是验证类 skill：让工程师花时间把 Playwright/tmux、逐步断言、录屏和质量门禁写扎实；description 则应描述“何时触发”，而不是给人看的摘要。

One-liner

Claude Code Skills 的关键不是资料堆叠，而是把验证、Runbook 和触发条件写成可执行上下文。

Obsidian evidence excerpt

---
title: "学习笔记：Claude Code Skills 实践"
date: 2026-07-23
source: https://x.com/trq212/status/2033949937936085378
tags:
  - llm-agent
  - type/summary
  - source/x
---

# 学习笔记：Claude Code Skills 实践

## 一句话判断

Skill 的价值不在「多写一篇 markdown」，而在把组织特有的验证路径、坑点、数据入口和操作护栏，做成代理可发现、可组合、可度量的文件夹能力包。

## 原文主线

- 起点：Skills 已是 Claude Code 最常用扩展点，但「什么值得做、怎么写、何时分享」仍模糊。
- 转折：Anthropic 内部数百活跃 skill 后，归纳 9 类用途 + 写作技巧 + 分发/度量。
- 当前结论：好 skill 干净落在一类；高信号来自 gotchas、脚本、渐进披露与触发描述；规模化靠 marketplace + 使用量度量。
- 未展开但重要：跨 skill 原生依赖、策展标准量化、验证 skill 的 ROI 如何衡量。

## 核心观点

1. **Skill ≠ 单文件说明**：是含 scripts/assets/data/hooks 的文件夹；代理会探索和操作其中内容。
2. **先分类再补齐**：9 类覆盖参考、验证、数据、流程自动化、脚手架、质量、CI/CD、runbook、

Fetched source / metadata

title: "学习笔记：Claude Code Skills 实践" date: 2026-07-23 source: https://x.com/trq212/status/2033949937936085378 tags:

llm-agent
type/summary
source/x

学习笔记：Claude Code Skills 实践

一句话判断

Skill 的价值不在「多写一篇 markdown」，而在把组织特有的验证路径、坑点、数据入口和操作护栏，做成代理可发现、可组合、可度量的文件夹能力包。

原文主线

起点：Skills 已是 Claude Code 最常用扩展点，但「什么值得做、怎么写、何时分享」仍模糊。
转折：Anthropic 内部数百活跃 skill 后，归纳 9 类用途 + 写作技巧 + 分发/度量。
当前结论：好 skill 干净落在一类；高信号来自 gotchas、脚本、渐进披露与触发描述；规模化靠 marketplace + 使用量度量。
未展开但重要：跨 skill 原生依赖、策展标准量化、验证 skill 的 ROI 如何衡量。

核心观点

1. Skill ≠ 单文件说明：是含 scripts/assets/data/hooks 的文件夹；代理会探索和操作其中内容。 2. 先分类再补齐：9 类覆盖参考、验证、数据、流程自动化、脚手架、质量、CI/CD、runbook、基建运维；好 skill 一类做透，跨太多类会糊。 3. 验证类值得重仓：作者明确说可以让工程师花一周把 verification skills 做扎实；配合 Playwright/tmux、逐步断言、甚至录屏。 4. 写 skill 的核心是改默认行为：别写模型已知常识；写 gotchas、组织约定、反默认设计口味（如 frontend-design 避开 Inter/紫渐变）。 5. description 是触发器：给模型扫描用，写「何时该启用」，不是给人看的摘要。 6. 上下文有成本：repo 内 skills 越多越占上下文；规模化转向内部 plugin marketplace 按需装。 7. 从最小可用长出来：多数 skill 始于几行 + 一个 gotcha，靠真实失败持续追加。

论证结构

| 类型 | 内容 | |------|------| | 事实 | Anthropic 内部大量使用 Claude Code skills，活跃数百个；skill 支持 hooks、文件夹结构、${CLAUDE_PLUGIN_DATA}；可用 PreToolUse 记使用量 | | 解释 | 类别用来查缺；渐进披露降低一次塞满上下文；脚本让模型做组合而非重造样板 | | 建议 | 建 gotchas；setup 用 config.json；危险操作做 on-demand hooks；marketplace 先 sandbox 再 PR；发布前策展 | | 预测/开放 | 依赖管理尚未原生；整体仍 early，作者自称 tips grab bag 而非终极指南 |

可复用检查清单

做新 skill 前问：

1. 它主要落在 9 类的哪一类？能否一句话说清触发场景？ 2. 有没有「模型默认会做错」的 gotcha 至少 1 条？ 3. 哪些该放 references/ / scripts/ / assets/，而不是全塞进 SKILL.md？ 4. description 是否像触发条件，而不像目录简介？ 5. 是否需要 config 启动问询？记忆数据是否写在稳定目录？ 6. 有破坏面吗？要不要 /careful 类按需 hook？ 7. 怎么知道它被用了、触发不足还是冗余？

边界

材料来自 trq212 公开 X Article，是 Anthropic 侧实践分享，不是你仓库的现成规范。
9 类是观察聚类，作者自己说不是 definitive list。
文中「花一周做验证 skill」是投入建议，不是普遍 KPI。
Claude Code 特有能力（动态 hooks、AskUserQuestion、${CLAUDE_PLUGIN_DATA}）迁到其他 agent 栈时要对齐能力边界。

读者下一步

打开你们现有 agent skills 目录，按 9 类贴标签：空缺最多的前两类里，各写一个「只有 gotchas + description 触发句」的最小 skill，跑一周看触发日志。