addyosmani-agent-skills-zh: Instructions file for Codex

AGENTS.md

本文件为 AI coding agents（Claude Code、Cursor、Copilot、Antigravity 等）在本仓库中处理代码时提供指导。

适用范围： 本文件为在 addyosmani/agent-skills 仓库本身上工作的 agents 提供配置。它不应被复制到其他项目或全局 agent 配置中；可复用的资产是 skills/ 里的 skills，而不是这个文件。

仓库概览

面向资深软件工程师的 Claude.ai 和 Claude Code skills 集合。Skills 是打包后的 instructions 和 scripts，用于扩展 Claude 以及你的 coding agents 的能力。

OpenCode 集成

OpenCode 使用由 skill tool 和本仓库 /skills 目录驱动的 skill-driven execution model。

核心规则

• 如果任务匹配某个 skill，你 MUST 调用它
• Skills 位于 skills/<skill-name>/SKILL.md
• 如果有适用 skill，绝不要直接实现
• 始终严格遵循 skill instructions（不要只部分应用）

意图 → Skill 映射

Agent 应自动将用户意图映射到 skills：

• Feature / new functionality → spec-driven-development，然后 incremental-implementation、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

生命周期映射（隐式命令）

OpenCode 不支持 /spec 或 /plan 这样的 slash commands。

因此，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

执行模型

对每个请求：

1. 判断是否有任何 skill 适用（即使只有 1% 可能）
2. 使用 skill tool 调用合适的 skill
3. 严格遵循 skill workflow
4. 仅在完成必需步骤（spec、plan 等）后再进入实现

反合理化

以下想法是错误的，必须忽略：

• "This is too small for a skill"
• "I can just quickly implement this"
• "I’ll gather context first"

正确行为：

• 始终先检查并使用 skills

这能确保 OpenCode 的行为类似具备完整 workflow enforcement 的 Claude Code。

编排：Personas、Skills 和 Commands

本仓库有三个可组合层。它们职责不同，不应混淆：

• Skills (skills/<name>/SKILL.md) — 带步骤和退出标准的工作流。即 how。意图匹配时必须经过。
• Personas (agents/<role>.md) — 带视角和输出格式的角色。即 who。
• Slash commands (.claude/commands/*.md) — 面向用户的入口点。即 when。编排层。