Software 2.0

我的第一个AI代理技能

admin -

想象一下：现在是星期二晚上11点。你盯着一个让你感到似曾相识的错误信息。"Connection refused on port 5432"。你见过这个。你知道你见过。你知道有一个变通方法。但在哪里？什么时候？提交消息只是说"fixed db connection." Stack Overflow给了你十二个不同的答案。你的AI助手愉快地建议你已经尝试过的解决方案。

这是AI健忘症在起作用，而且它比你想象的更昂贵。

每个AI编码助手都有相同的令人沮丧的限制：它们忘记一切在会话之间。开始一个新聊天，Claude不知道昨天你花了45分钟发现你的暂存环境使用端口5433，而不是5432。它不知道你选择了PostgreSQL而不是MongoDB，因为你的团队现有专长。它不能回忆那个"connection refused"错误总是意味着VPN断开连接。或者它开始使用一个新的NLP库或图表库当整个项目使用另一个时。然后你不得不再次解释。以及再次。

所有那些辛苦获得的知识？消失了。每一次。

我通过观看一个YouTube视频发现了简单解决方案，视频展示了如何让Claude Code保持项目上下文更新。创作者链接了小markdown文件从他们的CLAUDE.md来跟踪决策、bug和关键事实。一个灯泡时刻击中了我：如果我能创建一个技能来自动管理这个呢？

那个想法变成了project-memory，我为Claude Code写的非常早期的技能之一。尽管非常简单（不到300行），它真正节省了我数小时的工作。这个教程展示了如何构建你自己的项目记忆技能，更重要的是，如何思考创建解决实际问题的技能。

Claude Code不是唯一的玩家。Codex、GitHub Copilot和OpenCode都已经宣布支持Agentic Skills。还有一个agentic skills的市场支持Gemini、Aidr、Qwen Code、Kimi K2 Code、Cursor和更多；14+平台和计数中有一个通用agentic skills安装程序（skilz）。

在整个指南中，我将"Claude"和"编码代理"互换使用，就像说"Xerox this paper"而不是"copy this paper"一样。值得一提的是，我在自己的工作流程中更喜欢Claude Code、OpenCode和Gemini CLI。

1、AI健忘症的真正成本

让我描绘一个你可能认识的画面：

第一个月：发现

错误：CORS policy blocked request from localhost:3000
[2小时调试，尝试代理配置、头部更改、nginx重写]
解决方案：添加package.json中的代理配置

第六个月：似曾相识

错误：CORS policy blocked request from localhost:3000
开发者："这看起来熟悉...我们是怎么修复的？"
[搜索旧提交，检查Stack Overflow再次，问Claude不知道记忆]
[1小时重新发现确切的代理配置解决方案]

听起来熟悉？这是不舒服的真相：AI代码助手使这更糟，不是更好。没有记忆：

  • 每个新聊天会话从零开始
  • 每个bug感觉像你第一次解决它
  • 解决方案被重复"重新发现"（我曾解决相同的CORS问题四次在六个月内）
  • 没有学习随着时间积累，为你或你的AI助手

隐藏成本绝对惊人。 如果你每周花30分钟重新解决你已经解决的问题，那就是每年26小时。在$100/小时，这是$2,600的浪费时间。

但如果你的AI助手能记住呢？

2、什么是Agent Skill？

在深入project-memory之前，让我们理解技能实际上是什么。如果你曾经希望Claude有一个特定的工作流程或领域知识，技能就是答案。

一个agent skill只是一个文件夹包含一个SKILL.md文件和可选的支持资源。SKILL.md文件有两个部分：

  1. YAML frontmatter：告诉Claude何时激活的元数据
  2. Markdown body：当技能激活时Claude遵循的指令

想想技能作为可重用的"专家模式"你可以安装。当你说"set up project memory"时，Claude不只是猜测你是什么意思。它加载特定的、测试的指令，用于确切的任务。

2.1 Agent Skill结构剖析

SKILL.md文件结构显示YAML frontmatter与名称和描述，Markdown body与概述、何时使用、核心能力、示例和成功标准部分

SKILL.md文件结构显示YAML frontmatter与名称和描述，Markdown body与概述、何时使用、核心能力、示例和成功标准部分。

技能通常可以放在两个位置：

将技能存储在你的用户home目录~/.claude/skills/.这些是全局可用的在所有项目中，它们是为通用技能如代码审查、文档。项目特定技能生活在.claude/skills/.这些只是这个项目的本地项目特定工作流程。我说通常是因为你有企业技能、共享技能在mono-repo级别等。以及它也取决于你使用的提供者（~/.codex/skills/ , ~/.config/opencode/skill/ , ~/.gemini/skills/ , .claude/skills/ , .codex/skills/ , .opencode/skills/ 只是命名几个）。

💡 试试这个： 运行ls ~/.claude/skills/看看你已经安装了什么技能。如果目录还不存在，你安装第一个技能时会创建它。

2.2 技能激活如何工作

当你做一个请求时，Claude Code遵循一个用于编写agentic skills的渐进披露模式。它只加载它需要的，当它需要时。这保持交互快速，同时给你按需访问强大能力的权利。

技能激活流程图显示三个阶段：发现（扫描目录，加载元数据），匹配（检查请求是否匹配技能），执行（加载SKILL.md，跟随指令，完成任务）

技能激活流程图显示三个阶段：发现（扫描目录，加载元数据），匹配（检查请求是否匹配技能），执行（加载SKILL.md，跟随指令，完成任务）。

关键见解：Claude扫描技能目录，只读取元数据（名称+描述）直到它找到匹配。只有然后它加载完整指令。这意味着你可以安装数十个技能而不减慢正常交互。

现在你理解了机制，让我们看看project-memory如何将它们付诸实践。

3、项目记忆技能

project-memory技能在docs/project_notes/创建一个结构化知识系统，有四个专门文件。每个在保留和回忆项目知识中服务于不同目的。

3.1 记忆技能文件结构

项目记忆文件结构显示docs/project_notes/文件夹包含bugs.md, decisions.md, key_facts.md, 和issues.md, 加上配置文件CLAUDE.md和AGENTS.md

注意项目记忆文件结构显示docs/project_notes/文件夹包含bugs.md, decisions.md, key_facts.md, 和issues.md, 加上配置文件CLAUDE.md和AGENTS.md它链接到项目笔记文件，这构成了项目记忆。

每个记忆文件服务于捕获项目知识的特定角色。例如，bugs.md作为可搜索的bug数据库，条目如"BUG-018: Pulumi state drift — run pulumi refresh — yes "记录问题及其解决方案，防止当相同问题再次出现时未来时间损失。我用它来跟踪项目中重复出现的问题。decisions.md文件跟踪架构选择通过ADR（架构决策记录），如"ADR-012: Use D3.js for all charts (team expertise), "确保一致性并防止未来技术选择冲突。同时，key_facts.md作为项目基本细节的快速参考，如"Staging API: https://api.staging.example.com:8443,"消除关于端口和URL的猜测。最后，issues.md维护一个按时间顺序的工作日志，条目如"TICKET-456: Implemented user auth — 2024–01–15,"创建连接完成工作到特定票据和日期的审计跟踪。

让我分解技能的每个部分如何工作。

3.2 YAML格式头：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".
---

description字段至关重要。它可能是你的技能最重要的部分。它告诉Claude何时激活。注意描述中嵌入的特定触发短语："set up project memory", "track our decisions", "log a bug fix"。当你说任何这些时，Claude识别匹配并加载完整指令。（完整技能在文章末尾列出。）

💡 试试这个： 当编写你自己的技能描述时，包括3-5个用户可能自然说的特定短语。通过尝试变体测试激活："help me track decisions" vs "set up decision tracking" vs "I want to log our architectural choices"。

3.3 何时使用这个Agent Skill（上下文触发）

## 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)

这一部分强化触发并帮助Claude理解更广泛的上下文哪里记忆有用。短语"didn't we solve this before?"特别强大。它捕捉到记忆会有帮助的精确挫败时刻。

3.4 初始设置指令（技能的"能力"）

## Core Capabilities

### 1. Initial Setup - Create Memory Infrastructure

When invoked for the first time in a project, create the following structure:

docs/
└── project_notes/
    ├── bugs.md         # Bug log with solutions
    ├── decisions.md    # Architectural Decision Records
    ├── key_facts.md    # Project configuration and constants
    └── issues.md       # Work log with ticket references

**Directory naming rationale:** Using `docs/project_notes/` instead of `memory/`
makes it look like standard engineering organization, not AI-specific tooling.

这个设计决策比它看起来重要：使记忆看起来像正常文档。如果你在ai-memory/或claude-context/创建文件，开发者会将其视为AI工具，不会维护它。在docs/project_notes/，它看起来像标准工程文档任何人都可以更新，无论他们是否使用AI帮助。

3.5 记忆条目格式（结构化知识）

技能为每种条目类型定义一致格式。一致性很重要，因为Claude可以可靠地解析结构化格式，即使几个月后：

上面是bugs.md条目格式（Issue, Root Cause, Solution, Prevention）和decisions.md ADR格式（Context, Decision, Alternatives, Consequences）的并排比较。

bug条目中的Prevention字段特别有价值。它将bug从"我们修复的问题"转变为"我们学到的教训"。六个月后，Claude可以在你之前警告你击中相同问题。

3.6 CLAUDE.md的记忆协议（魔法）

这里真正的力量出现。技能配置CLAUDE.md使Claude默认记忆感知：

### 2. Configure CLAUDE.md - Memory-Aware Behavior

Add or update the following section in the project's `CLAUDE.md` file:

## 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将自动检查记忆文件在做出决定或建议之前。你不必记住说"check the bug log."它成为默认行为。

4、现实世界影响：知识复利

让我分享具体例子，展示记忆技能如何改变日常开发工作流程。

4.1 记忆感知bug解决

没有记忆的bug解决比较图（45分钟调试从头开始）与有记忆（5分钟在bugs.md中查找已知解决方案）

上面显示没有记忆的bug解决（45分钟调试从头开始）与有记忆（5分钟查找已知解决方案在bugs.md）的比较图。我曾浪费数小时追逐我以前见过的东西，所以45分钟是低估潜在节省。我不仅仅是时间。它是绝对的挫败感你可以避免！

4.2 示例1：Bug解决速度（真实数字）

场景：

10月20日，我在部署期间遇到Pulumi state drift错误。错误信息神秘："error: update failed"。在调试IAM权限、审查最近更改并尝试不同部署策略的45分钟后，我发现了解决方案：pulumi refresh --yes同步状态文件。

我将其记录为BUG-018：

### 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` before deploy to sync state

**Prevention**: Add `pulumi refresh --yes` to CI/CD pipeline before deploys; 
document that manual console changes require refresh

两天后，10月22日，相同错误出现。这次：

  1. 我告诉Claude错误
  2. Claude检查bugs.md并找到BUG-018
  3. Claude建议pulumi refresh --yes
  4. 问题在5分钟内解决

结果： 45分钟减少到5分钟。解决时间减少89%。

4.3 示例2：架构一致性（防止Bundle膨胀）

没有记忆：

User: "Add a bar chart to the dashboard"
Claude: "I'll add Chart.js for the bar chart. Let me install it..."
Result: Bundle size +85KB, duplicate charting dependencies, inconsistent styling

有记忆：

User: "Add a bar chart to the dashboard"
Claude: Checking decisions.md...
Found: ADR-012 - Use D3.js for all charts (team has D3 expertise, already in bundle)
Claude: "I see we've decided to use D3.js for charts. I'll create the bar chart using D3 to match your existing charts."
Result: Uses existing D3.js, consistent styling, no bundle increase

4.5 复利效应

知识复利时间线显示从第一次遇到（2小时调试）到文档到第二次遇到（5分钟）到第三次（2分钟）到预防建议的进展

事实是知识捕获以复利支付回报。上面图显示从第一次遇到（2小时调试）到文档到第二次遇到（5分钟）到第三次（2分钟）到预防建议的时间线

注意进展：第四次遇到时，Claude不仅仅修复bug。它防止它。"我注意到你即将做一个以前引起state drift问题的事情。我应该先运行pulumi refresh吗？"

你的项目随着时间变得更容易维护，不是更难。那是记录知识的复利效应。

5、跨平台：Agent Skill标准

这里有强大的东西：project-memory不仅仅是为Claude Code。它遵循Agent Skill标准（agentskills.io），意味着相同技能在14+ AI编码助手中工作。还有技能中指令保持AGENTS.md最新。

为什么这重要？团队经常使用不同的AI工具。一个开发者可能更喜欢Claude Code，另一个使用Cursor，第三个喜欢GitHub Copilot。标准化技能，每个人共享相同项目记忆。

Agent Skill标准图显示一个技能如何跨Claude Code、Codex、Gemini、Cursor等工作

上面显示Agent Skill标准如何使一个技能跨Claude Code、Codex、Gemini、Cursor等工作。

5.1 跨平台安装

跨平台技能安装图显示GitHub和SkillzWave市场作为来源，skilz CLI作为安装器，分发到Claude Code、Codex、Gemini、Cursor、Copilot等更多AI代理

Agent技能已成为跨平台所以有一些通用的技能安装器。上面显示在GitHub和SkillzWave agent市场找到技能作为来源，开源skilz CLI作为agent技能安装器，分发到Claude Code、Codex、Gemini、Cursor、Github Copilot等更多AI代理。

使用skilz CLI安装Agent Skill：

# Install skilz
pip install skilz

# Install for Claude Code (global)
skilz install -g https://github.com/SpillwaveSolutions/project-memory

# Install for a specific project only
skilz install -g https://github.com/SpillwaveSolutions/project-memory --project

# Install for other agents
skilz install -g https://github.com/SpillwaveSolutions/project-memory \
                --agent codex
skilz install -g https://github.com/SpillwaveSolutions/project-memory \
               --agent gemini
skilz install -g https://github.com/SpillwaveSolutions/project-memory \
               --agent cursor
skilz install -g https://github.com/SpillwaveSolutions/project-memory \
               --agent opencode

相同知识，可从你使用的任何AI编码工具访问。当你在Claude Code中记录bug修复时，你的队友使用Cursor或Gemini或Codex可以第二天从那个知识受益。

你可以安装它任何地方。

在skillz市场查看project-memory，带有各种编码代理平台的安装指令

6、安全：你必须永远不要存储的东西

这一节至关重要。在使用项目记忆之前仔细阅读。

key_facts.md文件设计用于方便查找项目配置。然而，便利创造风险如果你不小心。永远不要在你的记忆文件中存储秘密。它们是版本控制的markdown，任何有repo访问的人可以读取。技能指定这个警告。

6.1 危险区

永远不要在 key_facts.md（或任何记忆文件）中存储这些：

永远不要在key_facts.md中存储：

  • 认证凭据： 密码、API密钥、访问令牌，或任何形式的认证秘密
  • 服务账户密钥： GCP/AWS JSON密钥文件、私有密钥，或服务账户凭据
  • OAuth秘密： 客户端秘密、刷新令牌，或OAuth配置秘密
  • 数据库凭据： 包含密码或任何数据库认证详情的连接字符串
  • 基础设施秘密： SSH私有密钥、VPN凭据，或网络访问凭据

6.2 安全区

在 key_facts.md 中可以安全存储：

安全存储（摘要）：

  • 主机名和URL： 公共域名如api.staging.example.com或[https://api.example.com/v1](https://api.example.com/v1)
  • 端口号： 标准端口如PostgreSQL: 5432或Redis: 6379
  • 项目标识符： GCP项目ID、AWS账户ID，或类似非敏感标识符
  • 服务账户电子邮件地址： 身份信息如service-account@project.iam.gserviceaccount.com
  • 环境名称： 环境标签如staging、production或dev
  • 公共端点： 任何公开可访问的URL或API端点
  • 配置值： 非敏感设置如超时值、重试计数，或功能标志

6.3 秘密存到哪里

秘密属于哪里（摘要）：

  • .env文件（gitignored）： 最适合本地开发秘密如DATABASE_PASSWORD=secret123
  • 云秘密管理器： 生产系统应该使用GCP Secret Manager、AWS Secrets Manager，或Azure Key Vault
  • CI/CD变量： 自动化管道应该使用GitHub Actions秘密、GitLab CI/CD变量，或类似
  • 密码管理器： 通过1Password、LastPass、Bitwarden，或类似工具的团队共享凭据
  • 环境变量： 部署时注入的运行时秘密，永远不提交到版本控制
  • Kubernetes秘密： 对于使用Kubernetes Secret对象的容器化应用
  • 硬件安全模块（HSM）： 对于企业环境中高度敏感的加密密钥

💡 试试这个： 现在，搜索你现有的key_facts.md（如果你有的话）模式如password、secret、key或token。如果你找到任何秘密，立即移动它们并轮换受损凭据。

原文链接：Build Your First Claude Code Skill: A Simple Project Memory System That Saves Hours

汇智网翻译整理，转载请标明出处