Agent Skills (OpenCode)

This project uses skills installed under .opencode/skills/ (or a compatible path).

Core Rules

• If a task matches a skill, invoke it with the skill tool before acting.
• Skills are located in .opencode/skills/<skill-name>/SKILL.md.
• Follow the skill workflow strictly; do not partially apply it.
• Never skip required steps such as spec, plan, or test when a skill demands them.

Intent → Skill Mapping

Map the user's intent to the matching skill automatically:

• Feature / new functionality → spec-driven-development, then incremental-implementation and test-driven-development
• Planning / breakdown → planning-and-task-breakdown
• Bug / failure / unexpected behavior → debugging-and-error-recovery
• Code review → code-review-and-quality
• Refactoring / simplification → code-simplification
• API or interface design → api-and-interface-design
• UI work → frontend-ui-engineering

Execution Model

For every request:

1. Determine if any skill applies (even a small chance).
2. Load the skill with skill({ name: "<skill-name>" }).
3. Follow the skill workflow exactly.
4. Only proceed to implementation once required steps are complete.

把它保存为你项目根目录的 `AGENTS.md`，OpenCode 会自动加载。

这个模板与仓库根 [AGENTS.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/AGENTS.md?utm_source=gitcode_repo_files#L11-L68) 的 OpenCode 集成章节几乎一一对应：Core Rules 对应其 "Core Rules"，Intent → Skill Mapping 对应其意图映射表（Feature 走 `spec-driven-development` → `incremental-implementation` + `test-driven-development`，Bug 走 `debugging-and-error-recovery`，评审走 `code-review-and-quality` 等）。值得补充的是，根 `AGENTS.md` 还包含一节模板未展开的 **Anti-Rationalization（反合理化）**：以下想法是错误的、必须忽略——"这个任务太小用不着技能"、"我可以快速直接实现"、"我先收集一下上下文"。如果你的 OpenCode 会话频繁绕过技能，可以把这一节也加进你的项目级 `AGENTS.md`。

> **注意：** agent-skills 仓库根目录的 `AGENTS.md` 是为该仓库的贡献者准备的，不应复制到其他项目，参见 [CONTRIBUTING.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/CONTRIBUTING.md?utm_source=gitcode_repo_files) 中关于仓库级文件的说明。

## 四、工作原理：发现、调用与生命周期映射

### 1. 技能发现

OpenCode 按以下顺序扫描路径（项目级优先，然后是全局）：

- `.opencode/skills/<name>/SKILL.md`
- `~/.config/opencode/skills/<name>/SKILL.md`
- `.claude/skills/<name>/SKILL.md`
- `~/.claude/skills/<name>/SKILL.md`
- `.agents/skills/<name>/SKILL.md`
- `~/.agents/skills/<name>/SKILL.md`

每个技能必须包含带合法 `name` 和 `description` frontmatter 的 `SKILL.md`。

### 2. 自动技能调用

当你的项目 `AGENTS.md` 指示 agent 使用技能时，agent 会对每一个请求做评估并映射到合适的技能。典型映射：

- "build a feature"（做个功能）→ `incremental-implementation` + `test-driven-development`
- "design a system"（设计系统）→ `spec-driven-development`
- "fix a bug"（修 bug）→ `debugging-and-error-recovery`
- "review this code"（评审这段代码）→ `code-review-and-quality`

这些被调用技能都是真实存在于仓库中的完整工作流，例如 [skills/debugging-and-error-recovery/SKILL.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/skills/debugging-and-error-recovery/SKILL.md?utm_source=gitcode_repo_files)、[skills/code-review-and-quality/SKILL.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/skills/code-review-and-quality/SKILL.md?utm_source=gitcode_repo_files)，内部包含步骤、检查点、验证要求和反合理化表格——这正是 OpenCode 侧只需要"薄薄的" AGENTS.md 的原因：编排规则在项目里，工作流细节在技能里。

### 3. 生命周期映射（隐式命令）

OpenCode 不要求 slash 命令，但如果你偏好显式命令，见下一节。在 agent 驱动模式下，开发生命周期被隐式映射为：

- DEFINE → `spec-driven-development`
- PLAN → `planning-and-task-breakdown`
- BUILD → `incremental-implementation` + `test-driven-development`
- VERIFY → `debugging-and-error-recovery`
- REVIEW → `code-review-and-quality`
- SHIP → `shipping-and-launch`

这与 [README.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/README.md?utm_source=gitcode_repo_files) 中 DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP 的六段生命周期完全一致，意味着你在 Claude Code 等工具里用 `/spec`、`/plan` 等命令完成的事，在 OpenCode 里由意图映射隐式完成。

### 4. 可选：复制 slash 命令文件

如果你偏好显式命令，把这个仓库的命令文件复制到你自己的项目中，并调整其内容以调用你安装的技能：

```bash
mkdir -p .opencode/commands
cp /path/to/agent-skills/.opencode/commands/*.md .opencode/commands/

注意： 当前仓库 main 分支的 .opencode/ 目录下并没有 commands/*.md 文件（实际只有 skills/ 镜像），因此这条命令目前无文件可复制。可以自行创建命令文件，或关注提议添加这些文件的 PR #200；一旦它们存在，上面的复制模式即可生效。

一个典型的命令文件长这样：

---
description: Break work into small verifiable tasks
---

Invoke the planning-and-task-breakdown skill. Read the spec and create tasks with acceptance criteria.

把它保存为 .opencode/commands/plan.md，即可在 OpenCode 中获得 /plan 命令。

五、使用示例

示例 1：功能开发

用户输入：

Add authentication to this app

Agent 行为：

• 识别这是功能类工作
• 调用 spec-driven-development
• 先产出 spec 再写代码
• 随后转入规划与实现技能（planning-and-task-breakdown、incremental-implementation、test-driven-development）

示例 2：修 Bug

用户输入：

This endpoint is returning 500 errors

Agent 行为：

• 调用 debugging-and-error-recovery
• 按"复现 → 定位 → 修复 → 加防护"的流程推进

示例 3：代码评审

用户输入：

Review this PR