> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# 我的第一个AI代理技能
- URL: https://www.hubwiz.com/blog/my-first-agent-skills/
- Published: 2026-01-21T15:28:33.000Z
- Updated: 2026-01-21T15:28:33.000Z
- Description: project-memory是我为Claude Code写的非常早期的技能之一。尽管非常简单（不到300行），它真正节省了我数小时的工作。
- Author: admin
- Tags: TOOL, CLAUDE CODE, #Import 2026-10-14 14:41

想象一下：现在是星期二晚上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](https://developers.openai.com/codex/skills?ref=hubwiz.com)、[GitHub Copilot](https://github.blog/changelog/2025-12-18-github-copilot-now-supports-agent-skills/?ref=hubwiz.com)和[OpenCode](https://opencode.ai/docs/skills/?ref=hubwiz.com)都已经宣布支持[Agentic Skills](https://agentskills.io/home?ref=hubwiz.com)。还有一个[agentic skills的市场](https://skillzwave.ai/?ref=hubwiz.com)支持Gemini、Aidr、Qwen Code、Kimi K2 Code、Cursor和更多；14+平台和计数中有一个[通用agentic skills安装程序（skilz）](https://skillzwave.ai/docs/?ref=hubwiz.com)。

在整个指南中，我将"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结构剖析

![](https://www.hubwiz.com/blog/content/images/2026/01/image-651.png)

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

[SKILL.md](http://skill.md/?ref=hubwiz.com)文件结构显示YAML frontmatter与名称和描述，Markdown body与概述、何时使用、核心能力、示例和成功标准部分。

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

![](https://www.hubwiz.com/blog/content/images/2026/01/image-652.png)

将技能存储在你的用户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的**渐进披露**模式](https://skillzwave.ai/ai-agent-guides/mastering-claude-skills-the-complete-guide-to-building-effective-agent-skills/?ref=hubwiz.com)。它只加载它需要的，当它需要时。这保持交互快速，同时给你按需访问强大能力的权利。

![](https://www.hubwiz.com/blog/content/images/2026/01/image-653.png)

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

技能激活流程图显示三个阶段：发现（扫描目录，加载元数据），匹配（检查请求是否匹配技能），执行（加载[SKILL.md](http://skill.md/?ref=hubwiz.com)，跟随指令，完成任务）。

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

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

## 3、项目记忆技能

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

### 3.1 记忆技能文件结构

![](https://www.hubwiz.com/blog/content/images/2026/01/image-654.png)

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

注意项目记忆文件结构显示docs/project\_notes/文件夹包含[bugs.md](http://bugs.md/?ref=hubwiz.com), [decisions.md](http://decisions.md/?ref=hubwiz.com), key\_facts.md, 和[issues.md](http://issues.md/?ref=hubwiz.com), 加上配置文件[CLAUDE.md](http://claude.md/?ref=hubwiz.com)和[AGENTS.md](http://agents.md/?ref=hubwiz.com)它链接到项目笔记文件，这构成了项目记忆。

![](https://www.hubwiz.com/blog/content/images/2026/01/image-655.png)

每个记忆文件服务于捕获项目知识的特定角色。例如，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](https://api.staging.example.com:8443/?ref=hubwiz.com),"消除关于端口和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可以可靠地解析结构化格式，即使几个月后：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-656.png)

上面是[bugs.md](http://bugs.md/?ref=hubwiz.com)条目格式（Issue, Root Cause, Solution, Prevention）和[decisions.md](http://decisions.md/?ref=hubwiz.com) 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解决

![](https://www.hubwiz.com/blog/content/images/2026/01/image-657.png)

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

上面显示没有记忆的bug解决（45分钟调试从头开始）与有记忆（5分钟查找已知解决方案在[bugs.md](http://bugs.md/?ref=hubwiz.com)）的比较图。我曾浪费数小时追逐我以前见过的东西，所以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 复利效应

![](https://www.hubwiz.com/blog/content/images/2026/01/image-658.png)

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

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

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

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

## 5、跨平台：Agent Skill标准

这里有强大的东西：project-memory不仅仅是为Claude Code。它遵循**Agent Skill标准**（[agentskills.io](http://agentskills.io/?ref=hubwiz.com)），意味着相同技能在14+ AI编码助手中工作。还有技能中指令保持[AGENTS.md](https://agents.md/?ref=hubwiz.com)最新。

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

![](https://www.hubwiz.com/blog/content/images/2026/01/image-659.png)

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

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

### 5.1 跨平台安装

![](https://www.hubwiz.com/blog/content/images/2026/01/image-660.png)

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

Agent技能已成为跨平台所以有一些通用的技能安装器。上面显示在GitHub和[SkillzWave](https://skillzwave.ai/?ref=hubwiz.com) agent市场找到技能作为来源，[开源skilz CLI作为agent技能安装器](https://skillzwave.ai/docs/?ref=hubwiz.com)，分发到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可以第二天从那个知识受益。

你可以安装它任何地方。

![](https://www.hubwiz.com/blog/content/images/2026/01/image-661.png)

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

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

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

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

### 6.1 危险区

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

![](https://www.hubwiz.com/blog/content/images/2026/01/image-662.png)

永远不要在key\_facts.md中存储：

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

### 6.2 安全区

**在 key\_facts.md** **中可以安全存储：**

![](https://www.hubwiz.com/blog/content/images/2026/01/image-663.png)

安全存储（摘要）：

- **主机名和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 秘密存到哪里

![](https://www.hubwiz.com/blog/content/images/2026/01/image-664.png)

秘密属于哪里（摘要）：

- **.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](https://pub.spillwave.com/build-your-first-claude-code-skill-a-simple-project-memory-system-that-saves-hours-1d13f21aff9e?source=home%5Ffor%5Fyou---------38-98--------------------13a018b5%5F96fa%5F4fab%5Fbcd6%5Fab05e7e11761-------15-------)

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