Add best-practice

Author: yeasy

AGENTS.md

@@ -52,6 +52,7 @@ If normal startup or maintenance cannot complete, degrade explicitly instead of
 6. **Complex work loops**: for high-risk or cross-artifact tasks, investigate, plan, execute the smallest necessary change, then evaluate correctness, risk, validation, maintainability, and user impact. Iterate until deliverable.
 7. **Evidence-based completion**: choose validation that fits the artifact: tests/builds for code, render/export/link checks for docs and slides, visual QA for design, source checks for research, schema/recalculation checks for data.
 8. **Precise analysis**: cite exact file paths and line numbers, pages, frames, sheets, or asset names when proposing plans, trade-offs, or review findings.
+9. **Relevant best practices**: apply domain-specific best practices when they directly improve correctness, safety, maintainability, accessibility, or user outcomes. Explain material trade-offs and keep the change scoped to the task.
 
 ## Working Modes
 
@@ -67,6 +68,7 @@ Work normally. As the project evolves, accumulate durable context:
 - Review findings -> `.agents/memory/review-findings.md`
 - Open items -> `.agents/memory/open-items.md`
 - Reusable workflows -> `.agents/workflows/`
+- Runtime-supported skills -> `.agents/skills/` when useful
 
 ### Existing Projects
 
@@ -109,6 +111,8 @@ Use progressive understanding. Do not map the whole project unless the task requ
 │   └── ...
 ├── workflows/
 │   └── ...
+├── skills/
+│   └── ...        # Optional; only for agent runtimes that support repo-scoped skills
 ├── archive/
 │   └── ...
 └── changelog.md
@@ -122,9 +126,10 @@ Use progressive understanding. Do not map the whole project unless the task requ
 | Create / update `memory/` | Free | Record durable project facts, decisions, pitfalls, findings, and open items. |
 | Create / update `rules/` | Free | Extract stable conventions from artifacts and config. |
 | Create / update `workflows/` | Free | Codify recurring multi-step operations. |
+| Create / update `skills/` | Free | Optional; create focused, runtime-supported skills for repeatable workflows with clear triggers, inputs, outputs, and validation. Skills must not override this file, source priority, or confirmation rules. |
 | Modify `AGENTS.md` | Restricted | Do not modify this file for project adaptation. Edit it only when the user's task is specifically to change AGENTS.md itself. |
 | Merge / rewrite / delete `memory/` | Free | Keep notes accurate; leave a changelog trace. |
-| Delete `rules/` or `workflows/` | Requires confirmation | These affect future agent behavior. |
+| Delete `rules/`, `workflows/`, or `skills/` | Requires confirmation | These affect future agent behavior. |
 
 ### When to Record
 
@@ -138,6 +143,7 @@ Use compact entries with `date`, `artifact`, `note`, `evidence`, `status`, and `
 - Review findings and suggested fixes -> `memory/review-findings.md`
 - Unresolved questions or deferred work -> `memory/open-items.md`
 - Complex operations executed -> `workflows/`
+- Repeatable workflows with clear triggers, inputs, outputs, and validation -> `workflows/`; if the project and agent runtime support repo-scoped skills, create or update a focused skill under `skills/` when useful.
 
 ### Maintenance Cadence
 

AGENTS.zh-CN.md

@@ -54,6 +54,7 @@
 6. **复杂任务闭环**：高风险或跨产物任务先调研，再计划，执行最小必要变更，最后从正确性、风险、验证、可维护性、用户影响复核。发现问题就继续迭代。
 7. **基于证据完成**：按产物类型选择验证方式：代码跑测试/构建，文档和幻灯片做渲染/导出/链接检查，设计做视觉 QA，研究做来源核验，数据做 schema/重算检查。
 8. **精确分析**：提出计划、权衡或评审结论时，引用精确文件路径和行号、页码、画板、工作表或素材名。
+9. **相关最佳实践**：当领域最佳实践能直接提升正确性、安全性、可维护性、可访问性或用户结果时采用；说明重要取舍，并保持变更范围受控。
 
 ## 工作模式
 
@@ -69,6 +70,7 @@
 - 审阅发现 -> `.agents/memory/review-findings.md`
 - 未决事项 -> `.agents/memory/open-items.md`
 - 可复用流程 -> `.agents/workflows/`
+- 运行时支持的 skills -> `.agents/skills/`（确有帮助时）
 
 ### 已有项目
 
@@ -111,6 +113,8 @@
 │   └── ...
 ├── workflows/
 │   └── ...
+├── skills/
+│   └── ...        # 可选；仅供支持 repo-scoped skills 的 Agent 运行时使用
 ├── archive/
 │   └── ...
 └── changelog.md
@@ -124,9 +128,10 @@
 | 创建/更新 `memory/` | 自由 | 记录持久项目事实、决策、坑点、发现和未决事项。 |
 | 创建/更新 `rules/` | 自由 | 从产物和配置中提取稳定约定。 |
 | 创建/更新 `workflows/` | 自由 | 固化重复的多步操作。 |
+| 创建/更新 `skills/` | 自由 | 可选；为具备清晰触发条件、输入、输出和验证的重复流程创建聚焦的、运行时支持的 skill。skills 不得覆盖本文件、来源优先级或确认规则。 |
 | 修改 `AGENTS.md` | 受限 | 不为项目适配修改本文件。只有用户任务明确要求修改 AGENTS.md 本身时才编辑。 |
 | 合并/重写/删除 `memory/` | 自由 | 保持笔记准确，并在 changelog 留痕。 |
-| 删除 `rules/` 或 `workflows/` | 需确认 | 这些文件会影响后续 Agent 行为。 |
+| 删除 `rules/`、`workflows/` 或 `skills/` | 需确认 | 这些文件会影响后续 Agent 行为。 |
 
 ### 何时记录
 
@@ -140,6 +145,7 @@
 - 审阅发现和修改建议 -> `memory/review-findings.md`
 - 未决问题或延期工作 -> `memory/open-items.md`
 - 执行过的复杂操作 -> `workflows/`
+- 具备清晰触发条件、输入、输出和验证方式的重复流程 -> `workflows/`；如果项目和 Agent 运行时支持 repo-scoped skills，确有帮助时可在 `skills/` 下创建或更新聚焦的 skill。
 
 ### 维护节奏
 

README.md

@@ -1,11 +1,11 @@
 <h1 align="center">AgentGo</h1>
 
 <p align="center">
-  <strong>Drop in one AGENTS.md. Go agent-ready.</strong>
+  <strong>One AGENTS.md makes any project agent-ready.</strong>
 </p>
 
 <p align="center">
-  <sub>Best practices baked in — works in every project.</sub>
+  <sub>Best practices baked in. No custom setup required.</sub>
 </p>
 
 <p align="center">English | <a href="./README.zh-CN.md">简体中文</a></p>
@@ -133,7 +133,7 @@ flowchart LR
     style D fill:#B45309,color:#fff
 ```
 
-New findings are filed by type: source document inventory → `memory/source-index.md`, project conventions → `rules/`, decisions → `memory/decisions.md`, gotchas → `memory/gotchas.md`, reusable patterns → `memory/patterns.md`, review findings → `memory/review-findings.md`, and unresolved work → `memory/open-items.md`. After each meaningful task, the agent records durable results and appends `.agents/changelog.md`. The maintenance cadence is enforced by `AGENTS.md` itself — **easy to write in, hard to stay** — so notes never pile up into noise.
+New findings are filed by type: source document inventory → `memory/source-index.md`, project conventions → `rules/`, decisions → `memory/decisions.md`, gotchas → `memory/gotchas.md`, reusable patterns → `memory/patterns.md`, reusable workflows → `workflows/`, runtime-supported skills → `skills/` when useful, review findings → `memory/review-findings.md`, and unresolved work → `memory/open-items.md`. After each meaningful task, the agent records durable results and appends `.agents/changelog.md`. The maintenance cadence is enforced by `AGENTS.md` itself — **easy to write in, hard to stay** — so notes never pile up into noise.
 
 Recommended memory entry shape: `date`, `artifact`, `note`, `evidence`, `status`, and `next action`. The project does not need git; when no git repository exists, `.agents/changelog.md` still acts as the local audit trail.
 
@@ -170,6 +170,7 @@ your-project/
 │   ├── memory/            # Project overview, decisions, findings, open items
 │   ├── rules/             # Project conventions extracted from artifacts/config
 │   ├── workflows/         # Standard operating procedures for recurring flows
+│   ├── skills/            # Optional repo-scoped skills for supporting runtimes
 │   ├── archive/           # Obsolete agent-only configs, only after confirmation
 │   └── changelog.md       # Audit log of changes to .agents/
 ├── docs/archive/          ← Optional human-doc archive, only if the project uses it
@@ -211,6 +212,7 @@ A clear boundary between human control and agent autonomy:
 | Project notes, decisions, gotchas | `memory/` | Agent writes, merges, prunes freely |
 | Project conventions and reusable patterns | `rules/` | Agent writes freely; deletion needs user confirmation |
 | Complex workflows | `workflows/` | Agent writes freely; deletion needs user confirmation |
+| Runtime-supported skills | `skills/` | Optional focused workflows; deletion needs user confirmation |
 | Source document inventory | `.agents/memory/source-index.md` | Agent indexes active project references |
 | Obsolete agent-only configs | `.agents/archive/` | **Archived only after user confirmation** |
 | Obsolete human-facing docs | Project docs archive, e.g. `docs/archive/` | **Archived only after user confirmation** |
@@ -239,7 +241,7 @@ A clear boundary between human control and agent autonomy:
 <details>
 <summary><strong>Should I commit .agents/ to git?</strong></summary>
 
-It depends. For personal projects, gitignore the whole `.agents/` — it's your private working memory. For team projects, commit static config (`rules/`, `workflows/`) to share team conventions, but gitignore dynamic data (`memory/`) since it's session-level. `AGENTS.md` itself should always be committed — it's the contract between project and agent.
+It depends. For personal projects, gitignore the whole `.agents/` — it's your private working memory. For team projects, commit static config (`rules/`, `workflows/`, optionally `skills/`) to share team conventions, but gitignore dynamic data (`memory/`) since it's session-level. `AGENTS.md` itself should always be committed — it's the contract between project and agent.
 
 Common team pattern:
 ```gitignore

README.zh-CN.md

@@ -1,11 +1,11 @@
 <h1 align="center">AgentGo</h1>
 
 <p align="center">
-  <strong>放入一份 AGENTS.md，让项目马上 agent-ready。</strong>
+  <strong>一份 AGENTS.md，让任何项目 agent-ready。</strong>
 </p>
 
 <p align="center">
-  <sub>内置最佳实践 —— 在任何项目里都能用。</sub>
+  <sub>内置最佳实践，无需自定义配置。</sub>
 </p>
 
 <p align="center"><a href="./README.md">English</a> | 简体中文</p>
@@ -133,7 +133,7 @@ flowchart LR
     style D fill:#B45309,color:#fff
 ```
 
-新发现按类型归档：来源文档清单 → `memory/source-index.md`、项目约定 → `rules/`、决策 → `memory/decisions.md`、踩坑 → `memory/gotchas.md`、可复用模式 → `memory/patterns.md`、审阅发现 → `memory/review-findings.md`、未决事项 → `memory/open-items.md`。每次有意义任务后，Agent 记录持久结果并追加 `.agents/changelog.md`。维护节奏由 `AGENTS.md` 强制——**写入容易，留下来要难**，避免笔记越攒越多变成噪音。
+新发现按类型归档：来源文档清单 → `memory/source-index.md`、项目约定 → `rules/`、决策 → `memory/decisions.md`、踩坑 → `memory/gotchas.md`、可复用模式 → `memory/patterns.md`、可复用流程 → `workflows/`、运行时支持的 skills → `skills/`（确有帮助时）、审阅发现 → `memory/review-findings.md`、未决事项 → `memory/open-items.md`。每次有意义任务后，Agent 记录持久结果并追加 `.agents/changelog.md`。维护节奏由 `AGENTS.md` 强制——**写入容易，留下来要难**，避免笔记越攒越多变成噪音。
 
 推荐记忆条目字段：`date`、`artifact`、`note`、`evidence`、`status`、`next action`。项目不需要必须使用 git；没有 git 仓库时，`.agents/changelog.md` 仍作为本地审计记录。
 
@@ -170,6 +170,7 @@ your-project/
 │   ├── memory/            # 项目概览、决策记录、审阅发现、未决事项
 │   ├── rules/             # 从产物/配置中提取的项目约定
 │   ├── workflows/         # 重复流程的标准操作手册
+│   ├── skills/            # 可选；供支持的运行时使用的仓库级 skills
 │   ├── archive/           # 确认后归档的旧 agent 专用配置
 │   └── changelog.md       # .agents/ 的变更审计日志
 ├── docs/archive/          ← 可选的人类文档归档区，项目使用时才有
@@ -211,6 +212,7 @@ your-project/
 | 项目笔记、决策、踩坑记录 | `memory/` | Agent 自由写入、合并、清理 |
 | 项目约定和可复用模式 | `rules/` | Agent 自由写入；删除需用户确认 |
 | 复杂流程 | `workflows/` | Agent 自由写入；删除需用户确认 |
+| 运行时支持的 skills | `skills/` | 可选的聚焦流程；删除需用户确认 |
 | 来源文档清单 | `.agents/memory/source-index.md` | Agent 索引活跃项目参考资料 |
 | 过时的 agent 专用配置 | `.agents/archive/` | **用户确认后**才归档 |
 | 过时的面向人文档 | 项目文档归档区，如 `docs/archive/` | **用户确认后**才归档 |
@@ -239,7 +241,7 @@ your-project/
 <details>
 <summary><strong>.agents/ 目录要不要提交到 git？</strong></summary>
 
-取决于场景。个人项目建议 gitignore 整个 `.agents/` 目录——它是你私人的工作记忆。团队项目建议提交静态配置（`rules/`、`workflows/`）共享团队规范，但 gitignore 动态数据（`memory/`），因为它们是会话级别的。`AGENTS.md` 本身应该始终提交——它是项目与 Agent 的契约。
+取决于场景。个人项目建议 gitignore 整个 `.agents/` 目录——它是你私人的工作记忆。团队项目建议提交静态配置（`rules/`、`workflows/`，以及可选的 `skills/`）共享团队规范，但 gitignore 动态数据（`memory/`），因为它们是会话级别的。`AGENTS.md` 本身应该始终提交——它是项目与 Agent 的契约。
 
 常见团队模式：
 ```gitignore