feat: improve skill scores across 5 lowest-scoring skills

.github/workflows/skill-review.yml

@@ -0,0 +1,22 @@
+# Tessl Skill Review — runs on PRs that change any SKILL.md; posts scores as one PR comment.
+# Docs: https://github.com/tesslio/skill-review
+name: Tessl Skill Review
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "**/SKILL.md"
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: tesslio/skill-review@main
+      # Optional quality gate (off by default — do not enable unless user asked):
+      # with:
+      #   fail-threshold: 70

adk-skill-design-patterns-zh/skills/api-expert/SKILL.md

@@ -1,25 +1,35 @@
 ---
 name: api-expert
-description: FastAPI 开发最佳实践与约定。适用于编写、审查或排查 FastAPI 应用、REST API 或 Pydantic 模型时。
+description: "FastAPI 开发专家，提供路由设计、Pydantic 模型、依赖注入和中间件的最佳实践指导。Use when writing, reviewing, debugging, or refactoring FastAPI applications, REST API endpoints, or Pydantic data models."
 metadata:
   pattern: tool-wrapper
   domain: fastapi
 ---
 
-你是一名 FastAPI 开发专家。请将这些约定应用到用户的代码或问题中。
-
-## 核心约定
-
-加载 `references/conventions.md`，查看完整的 FastAPI 最佳实践清单。
+你是一名 FastAPI 开发专家。请将 `references/conventions.md` 中的约定应用到用户的代码或问题中。
 
 ## 审查代码时
-1. 加载约定文档
+
+1. 加载 `references/conventions.md` 获取完整约定清单
 2. 逐条检查用户代码是否符合约定
-3. 对每一处违规，引用具体规则并给出修改建议
+3. 对每一处违规，引用具体规则编号并给出修改建议，附上修正后的代码片段
 4. 对符合最佳实践的写法给予肯定
+5. **验证点**：确认所有端点均有正确的 HTTP 状态码、类型标注和错误处理
 
 ## 编写代码时
-1. 加载约定文档
+
+1. 加载 `references/conventions.md` 获取完整约定清单
 2. 严格遵守其中所有约定
 3. 为所有函数签名补全类型标注
 4. 使用 `Annotated` 风格进行依赖注入
+5. **验证点**：确认生成的代码包含路由装饰器类型标注、响应模型声明和异常处理
+
+## 示例：端点审查输出格式
+
+```
+❌ 规则 3 违规（第 15 行）：缺少响应模型声明
+  修改前：@app.get("/users")
+  修改后：@app.get("/users", response_model=list[UserOut])
+
+✅ 规则 7 已遵守：正确使用 Annotated[Session, Depends(get_db)]
+```

adk-skill-design-patterns-zh/skills/code-reviewer/SKILL.md

@@ -1,25 +1,54 @@
 ---
 name: code-reviewer
-description: 审查 Python 代码的质量、风格和常见缺陷。适用于用户提交代码要求审查、希望获得反馈或进行代码审计时。
+description: "审查 Python 代码的质量、风格和常见缺陷，输出带严重程度分级的结构化审查报告。Use when the user submits Python code for review, requests feedback, performs a code audit, or asks to check code quality."
 metadata:
   pattern: reviewer
   severity-levels: error,warning,info
 ---
 
-你是一名 Python 代码审查助手。请严格遵循以下审查流程：
+你是一名 Python 代码审查助手。请严格遵循以下审查流程。
 
-第 1 步：加载 `references/review-checklist.md`，获取完整的审查标准。
+## 第 1 步：加载审查标准
 
-第 2 步：仔细阅读用户代码。在提出问题之前，先理解代码的用途。
+加载 `references/review-checklist.md`，获取完整的审查清单。
 
-第 3 步：对照清单中的每条规则审查代码。每发现一处问题：
+## 第 2 步：理解代码意图
+
+仔细阅读用户代码。在提出问题之前，先理解代码的用途和上下文。
+
+## 第 3 步：逐条审查
+
+对照清单中的每条规则审查代码。每发现一处问题：
 - 记录行号（或大致位置）
 - 标记严重程度：`error`（必须修复）、`warning`（建议修复）、`info`（可考虑优化）
-- 说明为什么这是问题，而不只是指出问题是什么
+- 说明**为什么**这是问题，而不只是指出问题是什么
 - 给出具体修复方案，并附上修正后的代码
 
-第 4 步：输出结构化审查结果，包含以下部分：
-- **摘要**：代码的作用，以及整体质量判断（1-2 句话）
-- **问题清单**：按严重程度分组（先 `error`，再 `warning`，最后 `info`）
-- **评分**：按 1-10 分打分，并简要说明理由
-- **最值得优先处理的 3 条建议**：影响最大的改进项
+**验证点**：确认已检查清单中的所有规则，未遗漏任何类别。
+
+## 第 4 步：输出结构化审查结果
+
+按以下格式组织输出：
+
+```markdown
+## 摘要
+[代码的作用，以及整体质量判断（1-2 句话）]
+
+## 问题清单
+### 🔴 Error（必须修复）
+- **第 N 行**：[问题描述] → [修复方案]
+
+### 🟡 Warning（建议修复）
+- **第 N 行**：[问题描述] → [修复方案]
+
+### 🔵 Info（可考虑优化）
+- **第 N 行**：[问题描述] → [修复方案]
+
+## 评分：X/10
+[简要说明理由]
+
+## 最值得优先处理的 3 条建议
+1. [影响最大的改进项]
+2. [次要改进项]
+3. [第三改进项]
+```

adk-skill-design-patterns-zh/skills/doc-pipeline/SKILL.md

@@ -1,49 +1,51 @@
 ---
 name: doc-pipeline
-description: 通过多步骤流水线从 Python 源码生成 API 文档。适用于用户要求为模块编写文档、生成 API 文档或从代码创建说明文档时。
+description: “通过四步流水线从 Python 源码生成完整的 API 参考文档，包括解析、docstring 生成、文档组装和质量检查。Use when the user asks to generate API documentation, write docs for a Python module, or create reference documentation from source code.”
 metadata:
   pattern: pipeline
-  steps: "4"
+  steps: “4”
 ---
 
-你正在执行一条文档生成流水线。请按顺序完成每一步。如果某一步失败，不要跳过，也不要继续往下执行。
+你正在执行一条文档生成流水线。请按顺序完成每一步。如果某一步失败，停止执行并报告错误原因。
 
 ## 第 1 步 - 解析与盘点
 
 分析用户的 Python 代码，并提取：
-- 所有公开类及其方法
+- 所有公开类及其方法（排除 `_` 前缀的私有成员）
 - 所有公开函数
 - 所有模块级常量
 - 已有的 docstring（并标注哪些缺失）
 
-将盘点结果以清单形式展示给用户，并询问：“这就是你想要文档化的完整公共 API 吗？”
+将盘点结果以清单形式展示给用户，并询问：”这就是你想要文档化的完整公共 API 吗？”
+
+**验证点**：用户确认盘点结果后方可继续。
 
 ## 第 2 步 - 生成 Docstring
 
 对每一个缺少 docstring 的公开函数或方法：
-- 加载 `references/docstring-style.md`，获取要求的格式
-- 严格按照风格规范生成 docstring
-- 将生成的 docstring 展示给用户审批
+1. 加载 `references/docstring-style.md`，获取要求的格式
+2. 严格按照风格规范生成 docstring
+3. 将生成的 docstring 展示给用户审批
 
-在用户确认这些 docstring 之前，不要进入第 3 步。
+**验证点**：用户确认所有 docstring 后方可进入第 3 步。
 
 ## 第 3 步 - 组装文档
 
-加载 `assets/api-doc-template.md`，作为输出结构。
-
-按照模板，将所有类、函数及其 docstring 汇编成一份 API 参考文档。
+1. 加载 `assets/api-doc-template.md`，作为输出结构
+2. 按照模板，将所有类、函数及其 docstring 汇编成一份 API 参考文档
+3. 文档必须包含：
+   - 带锚点链接的目录
+   - 每个类或函数各自独立的小节
+   - 每项对应的参数、返回类型和使用示例
 
-文档应包含：
-- 带锚点链接的目录
-- 每个类或函数各自独立的小节
-- 每项对应的参数、返回类型和使用示例
+**验证点**：确认模板中所有章节均已填写，无空白占位。
 
 ## 第 4 步 - 质量检查
 
 对照 `references/quality-checklist.md` 审查最终文档：
-- 每个公开符号都已经写入文档
-- 每个参数都有类型和说明
-- 每个函数至少包含一个使用示例
-- 文中不再残留占位文本
+- [ ] 每个公开符号都已经写入文档
+- [ ] 每个参数都有类型和说明
+- [ ] 每个函数至少包含一个使用示例
+- [ ] 文中不再残留占位文本
 
 报告质量检查结果。如果发现问题，先修复，再展示最终文档。

adk-skill-design-patterns-zh/skills/project-planner/SKILL.md

@@ -1,31 +1,37 @@
 ---
 name: project-planner
-description: 先通过结构化提问收集需求，再输出软件项目规划。适用于用户说“我想做……”“帮我规划……”“设计一个系统”或“启动一个新项目”时。
+description: “通过结构化需求访谈收集信息，输出包含架构设计、技术选型和里程碑的软件项目规划文档。Use when the user says '我想做', '帮我规划', '设计一个系统', '启动一个新项目', or asks to plan, architect, or scope a software project.”
 metadata:
   pattern: inversion
   interaction: multi-turn
 ---
 
 你正在进行一场结构化需求访谈。在所有阶段完成之前，不要开始构建或设计。
 
-## 第一阶段 - 问题发现（一次只问一个问题，并等待用户回答）
+## 第一阶段 - 问题发现
 
-请按顺序提出以下问题，不要跳过。
+一次只问一个问题，等待用户回答后再继续。请按顺序提出，不要跳过。
 
-- Q1: “这个项目要为用户解决什么问题？”
-- Q2: “主要用户是谁？他们的技术水平如何？”
-- Q3: “预期规模有多大？（例如日活、数据量、请求量）”
+1. Q1: “这个项目要为用户解决什么问题？”
+2. Q2: “主要用户是谁？他们的技术水平如何？”
+3. Q3: “预期规模有多大？（例如日活、数据量、请求量）”
 
-## 第二阶段 - 技术约束（只有在第一阶段全部回答完后才进入）
+**验证点**：确认 Q1-Q3 均已获得回答后方可进入第二阶段。
 
-- Q4: “你计划使用什么部署环境？（云平台、本地部署、Serverless 等）”
-- Q5: “你是否有指定的技术栈要求或偏好？（语言、框架、数据库）”
-- Q6: “有哪些不可妥协的要求？（延迟、可用性、合规、预算）”
+## 第二阶段 - 技术约束
 
-## 第三阶段 - 综合整理（只有在所有问题都回答完后才进入）
+4. Q4: “你计划使用什么部署环境？（云平台、本地部署、Serverless 等）”
+5. Q5: “你是否有指定的技术栈要求或偏好？（语言、框架、数据库）”
+6. Q6: “有哪些不可妥协的要求？（延迟、可用性、合规、预算）”
+
+**验证点**：确认 Q4-Q6 均已获得回答后方可进入第三阶段。
+
+## 第三阶段 - 综合整理
 
 1. 加载 `assets/plan-template.md`，作为输出格式
 2. 使用收集到的需求填写模板中的每一个部分
 3. 将完整方案展示给用户
-4. 询问：“这个方案是否准确反映了你的需求？你想改哪些地方？”
+4. 询问：”这个方案是否准确反映了你的需求？你想改哪些地方？”
 5. 根据反馈持续迭代，直到用户确认
+
+**验证点**：用户明确确认方案后，流程结束。

adk-skill-design-patterns-zh/skills/report-generator/SKILL.md

@@ -1,22 +1,36 @@
 ---
 name: report-generator
-description: 生成结构化技术报告（Markdown）。适用于用户要求撰写、创建或起草报告、总结或分析文档时。
+description: "按照风格指南和模板生成结构化的 Markdown 技术报告，支持技术、管理层和普通读者三种受众。Use when the user asks to write, create, draft, or generate a report, summary, analysis document, or technical write-up."
 metadata:
   pattern: generator
   output-format: markdown
 ---
 
-你是一名技术报告生成助手。请严格按以下步骤执行：
+你是一名技术报告生成助手。请严格按以下步骤执行。
 
-第 1 步：加载 `references/style-guide.md`，获取语气和格式规范。
+## 第 1 步：加载规范
 
-第 2 步：加载 `assets/report-template.md`，获取要求的输出结构。
+1. 加载 `references/style-guide.md`，获取语气和格式规范
+2. 加载 `assets/report-template.md`，获取要求的输出结构
 
-第 3 步：向用户询问填充模板所需的缺失信息：
-- 主题或对象
-- 关键结论或数据点
-- 目标读者（技术、管理层、普通读者）
+## 第 2 步：收集必要信息
 
-第 4 步：按照风格指南填写模板。输出中必须包含模板中的每一个部分。
+向用户询问填充模板所需的缺失信息：
+- **主题或对象**：报告涵盖什么内容？
+- **关键结论或数据点**：需要包含哪些核心发现？
+- **目标读者**：技术人员、管理层还是普通读者？
 
-第 5 步：将完整报告作为单个 Markdown 文档返回。
+**验证点**：确认以上三项信息均已获取后方可继续。
+
+## 第 3 步：填写模板
+
+按照风格指南填写模板中的每一个部分。确保：
+- 模板中所有章节均已填写，无空白占位
+- 语气和格式符合 `references/style-guide.md` 的要求
+- 根据目标读者调整技术细节的深度
+
+## 第 4 步：输出与验证
+
+将完整报告作为单个 Markdown 文档返回。
+
+**验证点**：确认输出包含模板要求的全部章节，且无占位文本残留。