如何创建你的第一个 Agent Skill

一句话：创建一个 Agent Skill 只要 5 分钟——建一个 SKILL.md，写 YAML frontmatter（name、description、triggers），用 Markdown 写清任务步骤和输出格式，保存到项目根目录或 .claude/commands/。

Skill 是什么

Agent Skill 是一个 Markdown 文件（通常是 SKILL.md），教 AI 编程助手执行特定任务。可以理解成有结构的可复用提示词：告诉 AI 做什么、什么时候激活、怎么执行。

和 MCP（要写代码、跑进程）或简单规则（纯文本约束）相比，Skill 处在最佳平衡点：强大到能编码复杂工作流，简单到任何人都能写。

哪些工具在用：

第一步：创建文件

# 方法 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 识别，可发布

第二步：定义元数据（frontmatter）

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

第三步：写指令（正文）

正文就是给 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 什么不该做（如「不要修改文件，只输出报告」）

第四步：本地测试

# Claude Code
claude /code-review        # 放在 .claude/commands/ 的情况
claude "使用代码审查 skill"  # 放在项目根 SKILL.md 的情况

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

根据结果迭代：输出格式不对 → 加更具体的示例；做得太多/太少 → 加约束；边界情况出错 → 加错误处理指令。

第五步：发布到 TokRepo（可选）

npm install -g tokrepo
tokrepo login
tokrepo push my-skill.skill.md --public

发布后任何人都能搜索安装：tokrepo search "code review" → tokrepo install your-skill-name。

常见问题

Skill 应该多长？
200–500 行最有效。太短缺上下文，太长 AI 失焦。超过 1000 行就拆成多个 Skill。

Skill 能调用其他 Skill 吗？
不能直接调用，但可以在指令里引用：「如需跑测试，按 .claude/commands/test.md 中的测试 Skill 执行」。

Skill 和 AGENTS.md 的区别？
SKILL.md 是单一用途的技能文件；AGENTS.md 是项目级文件，描述整体项目上下文，可以在其中引用各个 Skill。

如何更新已发布的 Skill？

tokrepo update <uuid> my-skill.skill.md
# 或在 Skill 目录下重跑 push（幂等，无变化会跳过）
tokrepo push .