# Knowledge Check

> Knowledge Check is an Agent Skill for documents published in the Jasons-impart/Create-Delight-Remake repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

实现后知识检查、知识库维护、项目经验沉淀。用于代码、配置、脚本、文档或流程变更完成后，判断是否需要记录项目知识，并将知识路由到 AGENTS、docs/dev-knowledge、docs/plan、docs/lessons-learned 或项目 skill。

- Skill name: `knowledge-check`
- Category: [Documents](https://www.openparable.com/skill/documents/1)
- Source: https://github.com/Jasons-impart/Create-Delight-Remake/blob/HEAD/.agents/skills/knowledge-check/SKILL.md
- Repository: Jasons-impart/Create-Delight-Remake (283 GitHub stars when collected)

## SKILL.md

# 知识检查

本 skill 用于在实现工作结束后，判断是否学到了值得未来会话复用的项目知识，并把它写到正确位置。

## 何时使用

在以下情况调用本 skill：

- 刚完成代码改动、bug 修复或配置更新。
- 发现了非显而易见的项目模式、坑点或约束。
- 修正了未来 agent 可能再次犯的错误。
- 当前任务明确要求维护或整理知识库。

以下情况不要调用：

- 纯研究或探索，且没有代码/配置/文档改动。
- 完全按既有文档执行的琐碎改动。
- 与本项目无关的通用知识。

## 流程

### 第 1 步：判断是否值得记录

先问：“我是否学到了未来会话会受益的项目特定知识？”

如果存在 `tmp-opencode/knowledge-candidate-report.md`，先读取它再决定；除非当前任务明确要求维护知识库，否则 process note 候选需要用户接受后再落库。

Codex Stop hook 会运行 `scripts/validate-knowledge-base.ps1`，并写入 `tmp-opencode/knowledge-candidate-report.md`；该报告只提供建议，不会自动修改知识文件。

如果任务中途遇到非显而易见的失败或绕路做法，但最终还没决定是否落库，可用 `scripts/add-knowledge-note.ps1` 追加临时 note，让候选报告把它路由到这里。

通常值得记录的知识分为：

- **可复用的项目事实或位置** → 按 `.agents/skills/dev-knowledge/SKILL.md` 的存放表路由。
- **bug、坑点或历史教训** → 优先写入 `docs/lessons-learned.md`。
- **知识路由或 skill 行为变化** → 更新受影响的 skill。
- **没有可复用项目价值** → 不记录。

### 第 2 步：选择知识形态

读取 `.agents/skills/dev-knowledge/SKILL.md`，以其中的存放表作为知识落点的唯一来源。

### 第 3 步：选择目标文件

应用 dev-knowledge 存放表后，再检查这些覆盖规则：

- bug 修复、根因或非显而易见的 workaround → `docs/lessons-learned.md`。
- 新的 KubeJS helper/API 参考 → 内容很短时写入 `kubejs/AGENTS.md` 的 UNIQUE STYLES；否则写入 dev-knowledge how-to 或提升为 skill。
- knowledge-check prompt、候选报告路由或触发时机 → `.agents/skills/knowledge-check/SKILL.md`。
- dev-knowledge 存放规则 → `.agents/skills/dev-knowledge/SKILL.md`。

### 第 4 步：写入更新

更新知识文件时遵守这些规则：

1. **保持简洁**：每个事实尽量一句话，不写长篇说明。
2. **说明原因**：非显而易见的规则必须写出失败模式或原因。
3. **避免重复**：如果信息已存在于其他文件，改用引用，不要复制。
4. **控制 AGENTS 行数**：根 `AGENTS.md` 不超过 150 行，子目录 `AGENTS.md` 不超过 80 行；超限先精简。
5. **lessons 条目**：包含 Problem、Fix/Lesson 和日期。
6. **skill 条目**：触发条件写进 YAML `description`；正文聚焦可执行流程。
7. **dev-knowledge 条目**：使用表格行、路径和链接；不要复制长篇设计理由。
8. **迭代式维护**：只有出现重复错误或具体发现后才新增规则；删除 agent 已稳定遵守的规则。

允许的知识维护动作：

- 编辑根或模块级 `AGENTS.md`。
- 编辑 `docs/lessons-learned.md`。
- 编辑 `docs/dev-knowledge/`。
- 编辑 `.agents/skills/` 或 `.opencode/plugins/`。

作为 knowledge-check 调用时禁止：

- 修改与知识维护无关的代码、配方或配置。
- 运行 build/test 命令。
- 执行 Git 操作。

### 第 5 步：输出总结

如果应用或拒绝候选报告，决策后运行 `scripts/resolve-knowledge-candidate.ps1 -Status applied|rejected`，避免临时 process note 重复出现。

最后输出：

```text
Knowledge Check
- Learned: [1-3 条，或 “nothing significant”]
- Updated: [文件路径，或 “no update needed”]
- Reason: [一句话说明]
```

如果没有值得记录的内容，只输出：`Knowledge: no update needed`。

## 反模式

- 记录与本项目无关的通用编程知识。
- 在多个 AGENTS 或知识文件中复制同一事实。
- 文件超出行数限制时继续追加，而不是先精简。
- 用长篇散文替代简洁条目。
- 把知识维护流程规则放回根 `AGENTS.md`，而不是放在本 skill。

## 最终自检

保存任何 `AGENTS.md` 或 `docs/lessons-learned.md` 更新前，必须确认：

1. **行数**：根 `AGENTS.md` 是否 ≤150 行，子目录 `AGENTS.md` 是否 ≤80 行？超限先精简。
2. **无重复**：同一事实是否已存在于其他知识文件？如果存在，改为引用。
3. **简洁**：每个条目是否能继续删字而不丢信息？
4. **原因**：非显而易见的规则是否写清失败模式或理由？
5. **过期检查**：正在追加的文件是否已有过期条目？如有，标记或删除。
6. **skill 检查**：这是 workflow、checklist 或工具序列吗？如果是，应写入 skill，而不是常驻 AGENTS。
7. **位置检查**：目标文件是否符合 dev-knowledge 存放表和本 skill 的覆盖规则？

任何一项失败，都先修正再保存；这一步是长期保持知识库质量的主要机制。

---

Source: https://www.openparable.com/skill/documents/knowledge-check (OpenParable). Cite the canonical URL above.