手把手教你写第一个 Claude Code 技能（Skill）：一个能帮你省几十个小时的项目记忆系统
- 1. AI 失忆症：每个开发者都懂但没意识到有多贵
- 2. 什么是 Agent Skill（技能）
- 3. 项目记忆技能：核心设计
- 4. SKILL.md 完整结构
- 5. 核心机制：CLAUDE.md 注入
- 6. 真实效果：知识复利
- 7. 思考
- 8. 总结
1. AI 失忆症：每个开发者都懂但没意识到有多贵
晚上 11 点，你盯着屏幕上的报错信息：
Connection refused on port 5432
太眼熟了。你记得上次解决过它。可是怎么解决的？在哪儿？那个 commit message 只写了 “fixed db connection”。Stack Overflow 给了你 12 个不同的答案。你的 AI 助手热心地建议你试那些你已经试过的方法。
这是 AI 失忆症的典型症状，而且它的隐性成本远超你的想象。
每个 AI 编程助手都有同一个致命缺陷：会话之间什么都不记得。新开一个对话，Claude 不知道你昨天花了 45 分钟才发现 staging 环境用的是 5433 端口。它不记得你选 PostgreSQL 而不是 MongoDB 是因为团队更熟悉 PG。它不知道那个 “connection refused” 错误永远是因为 VPN 断了。
所有那些花时间搞明白的知识？清零。每次。完完全全。
如果每周花 30 分钟重新解决已经解决过的问题，一年就是 26 小时。按 $100/小时算，每个开发者每年浪费 $2,600。
我自己的血泪教训：同一个 CORS 问题，6 个月里我解决了 4 次。
2. 什么是 Agent Skill（技能）
在写项目记忆技能之前，先搞清楚技能究竟是什么。
一个 Agent Skill 就是一个文件夹，里面包含一个 SKILL.md 文件和可选的辅助资源。SKILL.md 分两部分：
- YAML frontmatter：元数据，告诉 Claude 什么时候激活这个技能
- Markdown 正文：Claude 激活技能后要遵循的指令
可以把技能理解成可安装的”专家模式”。当你说”设置项目记忆”，Claude 不会瞎猜你的意思——它会加载针对这个任务写好的、测试过的精确指令。
技能存放位置：
- 全局技能：
~/.claude/skills/（所有项目可用） - 项目技能：
.claude/skills/（仅当前项目可用）
不同提供商目录不同：~/.codex/skills/、~/.config/opencode/skill/、~/.gemini/skills/ 等。
技能激活机制
Claude Code 的技能加载遵循渐进式披露原则：只加载需要的，只在需要的时候加载。
- 发现阶段：扫描技能目录，读取元数据（name + description）
- 匹配阶段：判断当前请求是否匹配某个技能
- 执行阶段：加载完整的 SKILL.md，执行指令
这意味着你可以安装几十个技能，但日常交互完全不受影响——Claude 只在需要时才加载完整指令。
3. 项目记忆技能：核心设计
project-memory 技能的核心是在 docs/project_notes/ 下创建一个结构化的知识系统，包含四个专用文件：
docs/
└── project_notes/
├── bugs.md # Bug 及其解决方案
├── decisions.md # 架构决策记录（ADR）
├── key_facts.md # 项目配置和常量
└── issues.md # 工作日志
目录命名策略：用 docs/project_notes/ 而不是 memory/ 或 claude-context/，让它看起来像标准的工程文档，而不是 AI 专属工具。这样其他开发者（不管用不用 AI）都会自然地维护它。
3.1 Bugs.md：Bug 数据库
每条记录包含 Issue、Root Cause、Solution、Prevention 四个字段。Prevention 字段最有价值——它把”修过的 Bug”变成”学到的教训”：
### 2024-10-20 - BUG-018: Pulumi State Drift During Deploy
**Issue**: Deploy failed with cryptic "update failed" error after manual GCP console changes
**Root Cause**: Pulumi state file out of sync with actual infrastructure after teammate made console changes
**Solution**: Run `pulumi refresh --yes`
**Prevention**: Always run `pulumi refresh --yes` before deploy if manual changes may have occurred
3.2 Decisions.md：架构决策记录（ADR）
### 2024-10-15 - ADR-012: Charting Library Selection
**Context**: Need a charting library for the analytics dashboard
**Decision**: Use D3.js for all charts
**Alternatives**: Chart.js (limited customisation), Highcharts (expensive)
**Consequences**: Steeper learning curve but full flexibility
3.3 Key_facts.md：项目配置要点
Staging API: https://api.staging.example.com:8443
Ports: staging-postgres:5433, local-postgres:5432
Preferred ORM: SQLAlchemy 2.0
3.4 Issues.md：工作日志
TICKET-456: Implemented user auth — 2024-10-15
TICKET-457: Added API rate limiting — 2024-10-18
4. SKILL.md 完整结构
Frontmatter（触发条件）
---
name: project-memory
description: Set up and maintain a structured project memory system in docs/project_notes/
that tracks bugs with solutions, architectural decisions, key project facts, and work
history. Use this skill when asked to "set up project memory", "track our decisions",
"log a bug fix", "update project memory", or "initialize memory system".
---
描述字段是技能最重要的部分。它告诉 Claude 什么时候激活。注意其中嵌入的触发短语——当你说”set up project memory”或”log a bug fix”时，Claude 识别匹配并加载完整指令。
When to Use
## When to Use This Skill
Invoke this skill when:
- Starting a new project that will accumulate knowledge over time
- The project already has recurring bugs or decisions that should be documented
- The user asks to "set up project memory" or "track our decisions"
- Encountering a problem that feels familiar ("didn't we solve this before?")
- Before proposing an architectural change (check existing decisions first)
5. 核心机制：CLAUDE.md 注入
这是整个技能最巧妙的机制。技能不仅仅是创建记忆文件，它还修改项目的 CLAUDE.md，让 Claude 默认具备记忆意识：
## Project Memory System
### Memory-Aware Protocols
**Before proposing architectural changes:**
- Check `docs/project_notes/decisions.md` for existing decisions
- Verify the proposed approach doesn't conflict with past choices
**When encountering errors or bugs:**
- Search `docs/project_notes/bugs.md` for similar issues
- Apply known solutions if found
- Document new bugs and solutions when resolved
**When looking up project configuration:**
- Check `docs/project_notes/key_facts.md` for credentials, ports, URLs
- Prefer documented facts over assumptions
一旦这些协议写入 CLAUDE.md，Claude 就会自动在做出决策或建议之前检查记忆文件。你不需要记得说”查一下 bug 日志”——这成了默认行为。
6. 真实效果：知识复利
Bug 修复速度对比
没有记忆系统：遇到一个 Pulumi state drift 错误，45 分钟调试，检查 IAM 权限、回顾最近变更、尝试不同部署策略——最后发现只是 pulumi refresh --yes。
有记忆系统：同样的错误再次出现时，Claude 自动搜索 bugs.md，找到 BUG-018，5 秒内给出解决方案。
架构决策一致性
团队引入了一个新的 NLP 库，没有记录之前的决策。一个月后，另一个开发者又引入了另一个 NLP 库，因为”不知道之前已经决定了用哪个”。
有了 decisions.md，Claude 会在提出架构变更前先查记录。发现冲突，提醒开发者——避免了技术栈碎片化。
7. 思考
这个技能最打动我的不是它有多复杂——相反，它就 300 行，思路极其简单。
它的核心洞察是：AI 的记忆不应该藏在 embedding 向量里，而应该藏在人类可读的 Markdown 文件里。这样你和 AI 都能读、都能改、都能理解。不是”黑盒记住了什么”，而是”白纸黑字写明了什么”。
这个思路和 Karpathy 的 LLM Wiki 如出一辙——把知识编译成可审计的文档，而不是交给模型藏在参数里。
另外，”让记忆文件看起来像标准工程文档”这个设计决策也值得学习。很多 AI 工具的问题是它们太”AI”了，开发者不信任、不维护。但一旦把东西放在 docs/project_notes/ 里，它就变成了”正经的工程文档”——任何人都可以更新，不管他是不是用 AI。
8. 总结
project-memory 技能用不到 300 行代码，把一个最痛的开发者问题——AI 会话间失忆——变成了一个可管理的工程问题。它的核心机制不是技术上的创新，而是流程上的：创建一个结构化的记忆系统，通过 CLAUDE.md 协议让 AI 自动使用它。
对于任何一个正在用 Claude Code、Codex 或 OpenCode 做项目的团队来说，这是最值得花 10 分钟安装的技能之一。