如何创建你的第一个 Agent Skill

什么是 Agent Skill？

Agent Skill（AI 技能）是一个 Markdown 文件（通常是 SKILL.md 或 *.skill.md），用于教 AI 编程助手如何执行特定任务。你可以把它理解为一个有结构的可复用提示词——它告诉 AI 做什么、什么时候激活、怎么执行。

和 MCP 服务器（需要写代码和运行进程）或自定义规则（简单的文本约束）不同，Agent Skill 处于一个最佳平衡点：强大到足以编码复杂工作流，简单到任何人都能创建。

谁在用 Agent Skill？

• Claude Code — 读取 .claude/commands/ 或项目根目录下的 SKILL.md
• OpenAI Codex CLI — 读取 AGENTS.md
• Gemini CLI — 读取 GEMINI.md
• Cursor — 读取 .cursorrules

SKILL.md 格式在所有这些工具中通用，只需少量适配。

前提条件

开始之前，确保你有：

1. AI 编程助手 — Claude Code、Codex CLI 或类似工具
2. 文本编辑器 — VS Code、Cursor 或你喜欢的编辑器
3. 项目目录 — 任意你想使用 Skill 的文件夹

第一步：创建 SKILL.md 文件

在项目根目录（或 Claude Code 的 .claude/commands/ 目录）创建一个新文件：

# 方法 A：项目根目录（通用）
touch SKILL.md

# 方法 B：Claude Code 命令目录
mkdir -p .claude/commands
touch .claude/commands/my-skill.md

文件名很重要：

• SKILL.md — AI 扫描项目时自动发现
• .claude/commands/code-review.md — 在 Claude Code 中变成 /code-review 斜杠命令
• *.skill.md — 被 TokRepo 识别并可发布

第二步：定义元数据

每个好的 Skill 都以清晰的 YAML frontmatter 开头：

---
name: 代码审查 Skill
description: 对修改过的文件进行深度代码审查
triggers:
  - /code-review
  - "审查我的代码"
  - "检查 bug"
---

关键字段说明：

第三步：编写指令

SKILL.md 的正文就是给 AI 的提示词。用清晰的指令格式编写：

## 目标

审查当前分支所有改动的文件，查找 bug、安全问题和代码质量问题。

## 步骤

1. 运行 `git diff --name-only HEAD~1` 找到改动的文件
2. 完整阅读每个改动的文件
3. 对每个文件检查：
   - 逻辑错误和边界情况
   - 安全漏洞（注入、鉴权绕过等）
   - 性能问题（N+1 查询、不必要的循环）
   - 代码风格违规
4. 输出结构化报告，标注严重程度

## 输出格式

对每个发现的问题：
- **文件**: path/to/file.ts
- **行号**: 42
- **严重性**: 🔴 高 | 🟡 中 | 🟢 低
- **问题**: 问题描述
- **修复**: 建议的修复方案

写好指令的技巧

1. 要具体 — "检查所有数据库查询中的 SQL 注入" 比 "查找安全问题" 好得多
2. 用有序列表 — AI 按照有序列表执行比按段落执行更可靠
3. 包含示例 — 展示期望的输出格式
4. 设定边界 — 告诉 AI 什么不该做（例如 "不要修改任何文件，只输出报告"）

第四步：本地测试

在你的 AI 助手中调用 Skill 进行测试：

Claude Code 中：

# 如果放在 .claude/commands/code-review.md
claude /code-review

# 如果放在项目根目录的 SKILL.md
claude "使用代码审查 skill"

Codex CLI 中：

codex "按照 SKILL.md 中的指令审查我的代码"

根据结果迭代优化指令。常见调整：

• 如果输出格式不对，添加更具体的示例
• 如果 AI 做得太多或太少，添加约束条件
• 为边界情况添加错误处理指令

第五步：发布到 TokRepo

Skill 在本地运行良好后，分享给社区：

# 安装 TokRepo CLI
npm install -g tokrepo

# 登录（使用你的 API token）
tokrepo login

# 发布你的 Skill
tokrepo push my-skill.skill.md --public

你的 Skill 现在可以被任何人搜索和安装：

# 其他人可以找到并安装
tokrepo search "code review"
tokrepo install your-skill-name

常见问题

Skill 中可以用图片或图表吗？

可以，但大多数 AI 助手在执行时只处理文本。图片对 TokRepo 上的文档展示有用，但不会被 AI 在执行过程中"看到"。

Skill 应该多长？

最有效的 Skill 通常在 200-500 行之间。太短 AI 缺乏上下文，太长 AI 可能会失去焦点。如果你的 Skill 超过 1000 行，考虑拆分成多个 Skill。

Skill 可以调用其他 Skill 吗？

不能直接调用，但你可以在指令中引用其他 Skill："如果需要运行测试，请按照 .claude/commands/test.md 中的测试 Skill 执行"。AI 会读取并遵循那些指令。

SKILL.md 和 AGENTS.md 有什么区别？

SKILL.md 是单一用途的技能文件。AGENTS.md 是项目级文件，描述整体项目上下文和可用能力。你可以在 AGENTS.md 中引用各种 Skill。

如何更新已发布的 Skill？

# 通过 UUID 更新
tokrepo update <uuid> my-skill.skill.md

# 或使用 sync 自动检测变更
tokrepo sync .

TokRepo 上的相关 Skill

浏览这些热门 Skill 获取灵感：