lynxlangya · lynxlangya · May 24, 2026 · May 24, 2026 · May 24, 2026 · May 24, 2026
diff --git a/.github/workflows/skills.yml b/.github/workflows/skills.yml
@@ -0,0 +1,24 @@
+name: Skills
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  verify-skills:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: python -m pip install --upgrade pip pyyaml
+
+      - run: bash skills/scripts/verify.sh
+
+      - run: bash skills/scripts/test-install.sh
+
+      - run: git diff --check
diff --git a/README.md b/README.md
@@ -37,7 +37,8 @@ Claude Code and Codex can consume directly.
 The goal is simple: make handoff work cheaper. A PRD should become a usable
 HTML mock. A design screenshot should become a component decomposition plan. An
 OpenAPI file should become a typed client scaffold. A project should carry its
-own context so the next agent run does not start from zero.
+own context, source-cited memory, and review artifacts so the next agent run
+does not start from zero.
 
 ## What Knowject Skills Do
 
@@ -48,6 +49,9 @@ own context so the next agent run does not start from zero.
 | UI screenshot, PDF page, or Figma export | `knowject-read-design` | Component decomposition plan and skeleton files |
 | Express routes or OpenAPI document | `knowject-read-api` | Endpoint inventory and typed-client scaffold |
 | OpenAPI 3 document | `knowject-api-to-types` | TypeScript response types wired into the generated client |
+| Project artifacts, handoff notes, diffs, or decisions | `knowject-memory-capture` | Source-cited durable project memory under `knowject/memory/` |
+| Project knowledge sources | `knowject-rag-eval` | Source-cited RAG and citation eval cases under `knowject/evals/` |
+| API surfaces or endpoint inventories | `knowject-mcp-tool-designer` | MCP tool design artifacts under `knowject/tools/` |
 
 These Skills are intentionally not generic brainstorming or code-review
 prompts. Each one is scoped to a cross-role handoff where project context
@@ -57,8 +61,10 @@ matters.
 
 1. Run `knowject-context-init` once in your project.
 2. Commit `knowject/context.yaml` as the project anchor.
-3. Use the other Skills to turn PRDs, UI mocks, and API specs into concrete
-   artifacts.
+3. Optionally run `knowject-memory-capture` to preserve source-cited project
+   facts, decisions, workflows, risks, and lessons under `knowject/memory/`.
+4. Use the other Skills to turn PRDs, UI mocks, API specs, knowledge sources,
+   and endpoint inventories into concrete review artifacts.
 
 `knowject/context.yaml` is the shared contract. It records the project type,
 frontend and backend stack, design source paths, API source paths, client output
@@ -70,6 +76,18 @@ your-project/
   knowject/
     context.yaml
     README.md
+    memory/
+      README.md
+      project-memory.yaml
+    evals/
+      README.md
+      rag-eval-cases.yaml
+      rag-eval-report.md
+    tools/
+      README.md
+      mcp-tools.plan.md
+      mcp-tools.schema.json
+      tool-risk-report.md
 ```
 
 ## Install
@@ -109,7 +127,7 @@ pip install pyyaml
 bash skills/scripts/verify.sh
 ```
 
-The installer symlinks every `knowject-*` Skill into:
+The installer symlinks every `knowject-*` Skill plus the shared support folder `_shared` into:
 
 ```text
 ~/.claude/skills/
@@ -139,6 +157,9 @@ After that, use the Skills directly:
 /knowject design
 /knowject api
 /knowject types
+/knowject memory
+/knowject rag eval
+/knowject mcp tools
 ```
 
 Natural-language requests work too, as long as the intent matches the Skill:
@@ -148,6 +169,9 @@ Natural-language requests work too, as long as the intent matches the Skill:
 把这张设计稿拆成 React + Antd 组件骨架。
 找一下用户列表 endpoint，并生成 typed client。
 把这个 OpenAPI 文档转成 TypeScript response types。
+把这次交接总结成项目记忆。
+基于这些知识库文档生成 RAG 引用评测用例。
+把这些 endpoint 设计成带风险 gate 的 MCP tools。
 ```
 
 ## Skill Boundaries
@@ -159,6 +183,9 @@ Natural-language requests work too, as long as the intent matches the Skill:
 | `knowject-read-design` | UI decomposition and component skeletons | Does not wire state, routes, tests, or real data |
 | `knowject-read-api` | API discovery and typed-client scaffold | Phase 2 supports Express and OpenAPI sources |
 | `knowject-api-to-types` | OpenAPI 3 response types for generated clients | Day-1 scope is response types, not full request typing |
+| `knowject-memory-capture` | Source-cited file-based project memory | No DB, vector store, platform UI, daemon, secrets, or uncited facts |
+| `knowject-rag-eval` | Source-cited RAG and citation eval artifacts | No live model calls, Chroma, MongoDB, platform UI, network scoring, or external eval dependency |
+| `knowject-mcp-tool-designer` | API-to-MCP tool design with risk labels and confirmation gates | Does not implement an MCP server, runtime handlers, auth code, API routes, or UI |
 
 This makes the output reviewable. A Skill should produce a useful first pass,
 not silently mutate a production codebase.
@@ -170,9 +197,12 @@ bash skills/scripts/verify.sh
 bash skills/scripts/test-install.sh
 ```
 
-`verify.sh` checks the manifest, Skill frontmatter, Codex adapters,
-`context.yaml` examples, route extractors, OpenAPI extractors, brand extraction,
-framework extraction, type extraction, and client rewrite fixtures.
+`verify.sh` checks the manifest, Skill frontmatter, Codex adapters, per-Skill
+README coverage, `context.yaml` examples, route extractors, OpenAPI extractors,
+typed-client generation, brand extraction, framework extraction, type
+extraction, client rewrite fixtures, the memory validator, RAG eval validator,
+and MCP tool schema fixture. `test-install.sh` checks installer idempotency and
+installed shared-file references.
 
 ## The Platform Behind the Skills
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -14,7 +14,7 @@ Knowject 现在以 Skill 为核心。
 
 它是一个面向 Claude Code 与 Codex 的项目级 Skill 包，也是一套围绕项目知识持续演进的 AI 工作台。第一可用入口是 [`skills/`](./skills/README.md)：一组可以安装到本机 agent 工具里的 Knowject Skills，用真实项目上下文驱动 PRD、设计稿、API 文档与代码交接。
 
-核心目标很直接：降低跨角色交接成本。PRD 不应该停在文字里，设计稿不应该只靠人工拆组件，OpenAPI 不应该还要手写 `unknown` client。Knowject Skills 让这些输入变成可检查、可继续改的工程初稿。
+核心目标很直接：降低跨角色交接成本。PRD 不应该停在文字里，设计稿不应该只靠人工拆组件，OpenAPI 不应该还要手写 `unknown` client，项目经验也不应该散落在临时对话里。Knowject Skills 让这些输入变成可检查、可继续改的工程初稿、带来源的项目记忆和评审产物。
 
 ## Knowject Skills 能做什么
 
@@ -25,14 +25,18 @@ Knowject 现在以 Skill 为核心。
 | UI 截图、PDF 页面或 Figma 导出 | `knowject-read-design` | 组件拆解计划与组件骨架文件 |
 | Express 路由或 OpenAPI 文档 | `knowject-read-api` | Endpoint 清单与 typed-client 初稿 |
 | OpenAPI 3 文档 | `knowject-api-to-types` | 写入生成 client 的 TypeScript response types |
+| 项目文档、交接记录、diff 或决策 | `knowject-memory-capture` | 写入 `knowject/memory/` 的带来源项目记忆 |
+| 项目知识源 | `knowject-rag-eval` | 写入 `knowject/evals/` 的带来源 RAG / 引用评测用例 |
+| API 表面或 endpoint 清单 | `knowject-mcp-tool-designer` | 写入 `knowject/tools/` 的 MCP tool 设计产物 |
 
 这些不是泛泛的头脑风暴或代码审查 prompt。每个 Skill 都对应一个跨角色交接场景，并且依赖项目自己的 `knowject/context.yaml`。
 
 ## 工作方式
 
 1. 在目标项目里运行一次 `knowject-context-init`。
 2. 提交 `knowject/context.yaml`，把它作为项目上下文锚点。
-3. 用其他 Knowject Skills 把 PRD、设计稿、API 文档转成可继续交付的产物。
+3. 可选运行 `knowject-memory-capture`，把项目事实、决策、流程、风险和经验写成带来源的 `knowject/memory/` 文件。
+4. 用其他 Knowject Skills 把 PRD、设计稿、API 文档、知识源和 endpoint 清单转成可继续交付的评审产物。
 
 `knowject/context.yaml` 是共享合同。它记录项目类型、前后端技术栈、设计稿路径、API 源路径、client 输出目录与品牌 token。它不应该包含 secrets、base URL、API key 或环境配置。
 
@@ -41,6 +45,18 @@ your-project/
   knowject/
     context.yaml
     README.md
+    memory/
+      README.md
+      project-memory.yaml
+    evals/
+      README.md
+      rag-eval-cases.yaml
+      rag-eval-report.md
+    tools/
+      README.md
+      mcp-tools.plan.md
+      mcp-tools.schema.json
+      tool-risk-report.md
 ```
 
 ## 安装
@@ -77,7 +93,7 @@ pip install pyyaml
 bash skills/scripts/verify.sh
 ```
 
-安装脚本会把所有 `knowject-*` Skill 软链接到：
+安装脚本会把所有 `knowject-*` Skill 和共享支持目录 `_shared` 软链接到：
 
 ```text
 ~/.claude/skills/
@@ -107,6 +123,9 @@ bash skills/scripts/verify.sh
 /knowject design
 /knowject api
 /knowject types
+/knowject memory
+/knowject rag eval
+/knowject mcp tools
 ```
 
 自然语言也可以触发对应 Skill：
@@ -116,6 +135,9 @@ bash skills/scripts/verify.sh
 把这张设计稿拆成 React + Antd 组件骨架。
 找一下用户列表 endpoint，并生成 typed client。
 把这个 OpenAPI 文档转成 TypeScript response types。
+把这次交接总结成项目记忆。
+基于这些知识库文档生成 RAG 引用评测用例。
+把这些 endpoint 设计成带风险 gate 的 MCP tools。
 ```
 
 ## Skill 边界
@@ -127,6 +149,9 @@ bash skills/scripts/verify.sh
 | `knowject-read-design` | UI 拆解与组件骨架 | 不接状态、路由、测试或真实数据 |
 | `knowject-read-api` | API 发现与 typed-client 初稿 | Phase 2 仅支持 Express 与 OpenAPI |
 | `knowject-api-to-types` | 为生成的 client 补 OpenAPI 3 response types | Day-1 只处理 response type，不做完整 request typing |
+| `knowject-memory-capture` | 带来源的文件型项目记忆 | 不做 DB、向量库、平台 UI、daemon，不写 secrets 或无来源事实 |
+| `knowject-rag-eval` | 带来源的 RAG / 引用评测产物 | 不做 live model call、Chroma、MongoDB、平台 UI、联网评分或外部 eval 依赖 |
+| `knowject-mcp-tool-designer` | 带风险标签和确认 gate 的 API-to-MCP tool 设计 | 不实现 MCP server、runtime handler、auth 代码、API 路由或 UI |
 
 这个边界是故意的。Knowject Skills 应该产出有用的一版初稿，而不是悄悄改动生产代码。
 
@@ -137,7 +162,7 @@ bash skills/scripts/verify.sh
 bash skills/scripts/test-install.sh
 ```
 
-`verify.sh` 会检查 manifest、Skill frontmatter、Codex adapter、`context.yaml` 示例、路由提取器、OpenAPI 提取器、品牌提取、框架提取、类型提取与 client rewrite fixtures。
+`verify.sh` 会检查 manifest、Skill frontmatter、Codex adapter、各 Skill README 覆盖、`context.yaml` 示例、路由提取器、OpenAPI 提取器、typed-client 生成、品牌提取、框架提取、类型提取、client rewrite fixtures、memory validator、RAG eval validator 与 MCP tool schema fixture。`test-install.sh` 会检查安装幂等性和安装后的共享文件相对路径。
 
 ## Skill 背后的平台
 

diff --git a/skills/README.md b/skills/README.md
@@ -2,7 +2,7 @@
 
 Cross-role collaboration Skills for Claude Code and Codex. Project-anchored. Opinionated.
 
-> Status: Phase 4 Day-1 complete. Shipped: `knowject-context-init`, `knowject-read-api`, `knowject-prd-to-mock`, `knowject-read-design`, `knowject-api-to-types`, `knowject-memory-capture`. Next: Claude Code plugin marketplace.
+> Status: Phase 6 Day-1 complete. Shipped: `knowject-context-init`, `knowject-read-api`, `knowject-prd-to-mock`, `knowject-read-design`, `knowject-api-to-types`, `knowject-memory-capture`, `knowject-rag-eval`, `knowject-mcp-tool-designer`. Next: Claude Code plugin marketplace.
 
 ---
 
@@ -18,11 +18,17 @@ Skill catalog:
 | `knowject-api-to-types` | Generate TypeScript response types from OpenAPI and wire them into generated clients. | [`README`](./knowject-api-to-types/README.md) |
 | `knowject-read-design` | Turn UI design sources into component decomposition plans and skeleton code. | [`README`](./knowject-read-design/README.md) |
 | `knowject-memory-capture` | Capture source-cited durable project memory from artifacts, handoffs, diffs, and decisions. | [`README`](./knowject-memory-capture/README.md) |
+| `knowject-rag-eval` | Generate source-cited RAG and citation evaluation cases and reports. | [`README`](./knowject-rag-eval/README.md) |
+| `knowject-mcp-tool-designer` | Design API-to-MCP tool candidates with risk labels and confirmation gates. | [`README`](./knowject-mcp-tool-designer/README.md) |
 
 Each Skill reads `knowject/context.yaml` in your project to ground its output in your brand, your tech stack, and your conventions instead of producing generic AI output.
 
 `knowject-memory-capture` turns project artifacts, handoff notes, diffs, and decisions into source-cited durable memory under `knowject/memory/`, so Claude Code and Codex can reuse stable context across sessions without guessing.
 
+`knowject-rag-eval` turns project knowledge sources into reviewable eval cases under `knowject/evals/` for retrieval, citation support, unsupported claims, and fact-vs-plan conflicts.
+
+`knowject-mcp-tool-designer` maps API surfaces into reviewable MCP tool design artifacts under `knowject/tools/`, including input schema, risk labels, confirmation gates, auth notes, audit notes, and rollback notes.
+
 This is not a new agent CLI. It is a pack of Skills that Claude Code and Codex consume directly, similar to the `longbridge` or `superpowers` skill packs.
 
 ---
@@ -65,7 +71,7 @@ cd knowject
 bash skills/scripts/install.sh
 ```
 
-`install.sh` symlinks every `knowject-*` Skill into `~/.claude/skills/` and `~/.codex/skills/`. Re-run anytime to refresh.
+`install.sh` symlinks every `knowject-*` Skill plus the shared support folder `_shared` into `~/.claude/skills/` and `~/.codex/skills/`. Re-run anytime to refresh.
 
 ### Fallback: copy instead of symlink
 
@@ -127,6 +133,33 @@ your-project/
 
 Every memory item must cite source evidence. Do not put secrets, environment values, tokens, DB URLs, cookies, auth headers, or private credentials in `knowject/memory/`.
 
+After running `knowject-rag-eval`, the same folder can also contain file-based RAG and citation eval artifacts:
+
+```text
+your-project/
+  knowject/
+    evals/
+      README.md
+      rag-eval-cases.yaml  # source-cited eval cases
+      rag-eval-report.md   # human review report
+```
+
+Every eval case must cite source evidence. Day-1 evals are review artifacts: no live model calls, vector-store queries, platform API calls, or external scoring.
+
+After running `knowject-mcp-tool-designer`, the same folder can also contain MCP tool design artifacts:
+
+```text
+your-project/
+  knowject/
+    tools/
+      README.md
+      mcp-tools.plan.md
+      mcp-tools.schema.json
+      tool-risk-report.md
+```
+
+Day-1 MCP tool design is artifact-only: no MCP server, runtime handlers, platform API, UI, auth code, or external API calls.
+
 ---
 
 ## Contribute
@@ -145,6 +178,7 @@ We do not accept:
 - Pure template generators that do not read project context.
 
 See [`_shared/contributing-skills.md`](./_shared/contributing-skills.md) for the full PR checklist.
+GitHub Actions runs `skills/scripts/verify.sh`, `skills/scripts/test-install.sh`, and `git diff --check` on pull requests and pushes to `main`.
 
 ---
 
@@ -160,4 +194,6 @@ See [LICENSE](./LICENSE). Source-available: personal evaluation and non-commerci
 - [x] Phase 2: `knowject-read-api`, `knowject-prd-to-mock`, `knowject-read-design`
 - [x] Phase 3: `knowject-api-to-types`
 - [x] Phase 4: `knowject-memory-capture`
+- [x] Phase 5: `knowject-rag-eval`
+- [x] Phase 6: `knowject-mcp-tool-designer`
 - [ ] Next: Claude Code plugin manifest, official marketplace listing
diff --git a/skills/ROADMAP.md b/skills/ROADMAP.md
@@ -14,6 +14,8 @@ Canonical product roadmap for the `skills/` distribution. The Active catalog, de
 | `knowject-read-design` | Phase 2 — Tier 1 | `docs/plans/tasks-knowject-skills-read-design.md` |
 | `knowject-api-to-types` | Phase 3 | `docs/plans/tasks-knowject-skills-api-to-types.md` |
 | `knowject-memory-capture` | Phase 4 — memory | GitHub issue #1 |
+| `knowject-rag-eval` | Phase 5 — RAG eval | GitHub issue #8 |
+| `knowject-mcp-tool-designer` | Phase 6 — MCP tool design | GitHub issue #9 |
 
 ## Deferred (2026-05-17 narrowing)
 
@@ -41,6 +43,64 @@ Versioning is on the whole product (`manifest.yaml#version`), not per-Skill.
 
 ## Decision log
 
+### 2026-05-24 — Phase 6 shipped: mcp-tool-designer
+
+**Trigger:** Hangzhou AI Agent / AI application market scan repeatedly
+mentions MCP, tool calling, function calling, OpenAPI, agent tool
+ecosystems, and permission / confirmation gates. `knowject-read-api`
+and `knowject-api-to-types` already discover and type API surfaces;
+the next conservative step is tool design, not runtime execution.
+
+**Outcome:** `knowject-mcp-tool-designer` shipped as a Day-1 Skill for
+mapping API endpoints into MCP tool candidates with input schema, risk
+labels, confirmation gates, auth notes, audit notes, and rollback
+notes.
+
+**Day-1 scope:** design artifacts only under `knowject/tools/`:
+`README.md`, `mcp-tools.plan.md`, `mcp-tools.schema.json`, and
+`tool-risk-report.md`. The Skill requires `knowject/context.yaml`,
+supports OpenAPI sources, Express route sources, `knowject-read-api`
+endpoint inventories, and explicit endpoint lists, labels risks as
+`read_only`, `low_write`, `destructive`, `external_side_effect`, or
+`sensitive_data`, and requires confirmation gates for destructive,
+external, sensitive, and bulk operations.
+
+**Deliberate non-goals:** no MCP server, no runtime tool handlers, no
+external API calls, no app route changes, no platform UI, no
+auth/permission code, and no `knowject-read-api` behavior changes.
+
+**Resume signal:** API-to-MCP tool design with input schema, risk
+labels, confirmation gates, auth notes, audit notes, and rollback
+considerations.
+
+### 2026-05-24 — Phase 5 shipped: rag-eval
+
+**Trigger:** Hangzhou AI Agent / AI application market scan shows
+RAG, Eval, citation traceability, knowledge bases, vector retrieval,
+and verifiable output as high-signal requirements. Existing Knowject
+Skills cover project anchoring, cross-role handoff, API-to-types, and
+durable memory, but not lightweight RAG/citation quality evaluation.
+
+**Outcome:** `knowject-rag-eval` shipped as a Day-1 Skill for creating
+reviewable RAG and citation evaluation artifacts from project knowledge
+sources.
+
+**Day-1 scope:** file-based, source-cited eval artifacts under
+`knowject/evals/`: `README.md`, `rag-eval-cases.yaml`, and
+`rag-eval-report.md`. The Skill requires `knowject/context.yaml`,
+requires source evidence for every eval case, documents source recall,
+citation support, unsupported-claim, fact-vs-plan, and conflict
+resolution eval types, avoids secrets and environment values, and uses
+a diff-confirm write gate.
+
+**Deliberate non-goals:** no live model calls, no Chroma queries, no
+MongoDB / API / UI changes, no RAGAS or external eval dependency, no
+automated scoring against a running chatbot, and no CI that requires
+network.
+
+**Resume signal:** source-cited RAG evaluation, citation support checks,
+unsupported-claim review, and fact-vs-roadmap conflict cases.
+
 ### 2026-05-24 — Phase 4 shipped: memory-capture
 
 **Trigger:** Hangzhou AI Agent / AI application market scan shows