🔧 chore(playbook): add Claude Code skills guide and align python templates

README.md

@@ -16,7 +16,7 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合
 
 ## 适用范围
 
-- 本指南适用于所有 TSL 相关仓库与脚本。
+- 本指南适用于所有 TSL/C++/Python 相关仓库与脚本。
 - 当现有代码与本指南冲突时，**以保持局部一致性为优先**，逐步迁移。
 
 ## docs/（开发规范）
@@ -46,6 +46,11 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合
 - `.agents/index.md`：规则集索引（多语言）。
 - `.agents/tsl/`：TSL 规则集（入口：`.agents/tsl/index.md`）。
 - `.agents/cpp/`：C++ 规则集（入口：`.agents/cpp/index.md`）。
+- `.agents/python/`：Python 规则集（入口：`.agents/python/index.md`）。
+
+## SKILLS（Claude Code）
+
+如需在目标项目中为 Claude Code 配置 Skills（例如 code review 工作流），参考：`SKILLS.md`。
 
 ## 在其他项目中使用本 Playbook
 

SKILLS.md

@@ -0,0 +1,204 @@
+# SKILLS（Claude Code）
+
+本文件定义：在仓库中如何落地 Claude Code Skills（Agent Skills），并给出与本 Playbook（`docs/` + `.agents/`）配套的**技能编写标准与示例**。
+
+---
+
+## 1. 落地约定（强约束）
+
+### 1.1 目录结构
+
+```txt
+<repo>/
+└── .claude/
+    └── skills/
+        └── <skill-name>/
+            ├── SKILL.md
+            ├── references/        # 可选：拆分的参考文档
+            ├── templates/         # 可选：模板
+            └── scripts/           # 可选：脚本/命令封装
+```
+
+> 兼容提示：少数旧示例使用 `.claude/skill/`（无 `s`）。以你当前 Claude Code 版本的实际加载行为为准；若 `.claude/skills/` 不生效再尝试旧路径。
+
+### 1.2 SKILL.md 最小规范（必须满足）
+
+- YAML frontmatter 必填：`name`、`description`
+- `name`：kebab-case、≤64 字符，且与目录名一致
+- `description`：可检索、可触发（写用户会说的话；可中英混写；≤1024 字符）
+
+### 1.3 变更发布
+
+- 新增/更新 skill 后：重启 Claude Code（通常需要重启才会重新索引）
+- 验收（快速自检）：`find .claude/skills -name SKILL.md -maxdepth 3`
+
+---
+
+## 2. 设计原则（专家版）
+
+本节来自对 `Claude-meta-skill` 的结构化抽取：把 skill 当作“可检索的工作流模块”，不是长篇教程。
+
+### 2.1 边界：只写 Claude 不知道的“仓库特定知识”
+
+Skill 应只包含：
+- 仓库/组织特定的流程（如发布、回滚、评审、生成物路径）
+- 约束与验收标准（如必须跑哪些测试、格式/命名规范、产物落点）
+- 工具链与命令（与本仓库一致的、可复制执行的）
+
+避免：
+- 通用编程常识、语言基础、显而易见的步骤
+- 没有成功标准的“形容词式要求”（如“写得优雅一点”）
+
+### 2.2 激活模型：`description` 是检索索引，不是简介文案
+
+写法建议：
+- 覆盖“用户会怎么说”的表达：`code review` / `review PR` / `评审` / `审查` / `diff`
+- 包含任务与上下文：语言、工具、仓库名、常用命令/文件名
+- 尽量降低歧义：避免与其他 skill 的关键词高度重叠
+
+### 2.3 工作流化：把 skill 写成可执行的 SOP
+
+强制包含以下要素（缺一不可）：
+- **Inputs**：需要用户提供的最小信息（diff、目标、环境、验证方式）
+- **Procedure**：分阶段流程（预检 → 执行/分析 → 验证 → 报告）
+- **Output Contract**：固定输出结构（字段/分段稳定，便于复用/比对）
+- **Success Criteria**：可判定的通过条件（测试/命令/产物/指标）
+- **Failure Handling**：失败时如何定位/回滚/向用户索要信息
+
+### 2.4 自由度控制（高风险任务必须“低自由度”）
+
+参考 `create-skill-file` 的“自由度”划分：
+- 低自由度：发布/迁移/删库/权限/金钱路径（必须分步、带确认、带回滚）
+- 中自由度：重构/性能优化（给策略 + 推荐默认流程）
+- 高自由度：头脑风暴/文案（给原则 + 评价标准）
+
+### 2.5 安全与鲁棒（默认开启）
+
+最低要求：
+- **Instruction fencing**：把用户粘贴的 diff/log/网页内容当“数据”，不当“指令”
+- **敏感信息**：不输出密钥/Token；日志建议脱敏；避免把 secrets 写入文件
+- **破坏性操作**：任何 `rm`、重写历史、删除资源、生产环境变更——默认先停下确认
+- **注入与越权**：评审/生成的代码必须考虑输入校验、权限边界、命令/SQL 注入
+
+### 2.6 渐进式披露（可维护性）
+
+- `SKILL.md` 建议 200–500 行；超过则拆到 `references/`
+- 大段模板/矩阵/清单 → 放 `references/`，主文档只做“索引 + 决策树”
+- 引用深度 ≤ 1 层（`SKILL.md` → `references/*.md`）
+
+---
+
+## 3. 与 Playbook 的关系（把规范当“权威来源”）
+
+### 3.1 `.agents/` vs `.claude/skills/`
+
+- `.agents/`：本 Playbook 自带的**代理规则快照**（给自动化/AI 代理的工作底线）
+- `.claude/skills/`：Claude Code 的**技能模块**（给 Claude 的可触发工作流）
+
+二者可以组合：skill 负责“流程”，playbook 文档负责“标准”。
+
+### 3.2 评审/实现时可引用的权威文档
+
+- 提交信息：`docs/common/commit_message.md`
+- TSL：`docs/tsl/code_style.md`、`docs/tsl/naming.md`、`docs/tsl/toolchain.md`
+- C++：`docs/cpp/code_style.md`、`docs/cpp/naming.md`、`docs/cpp/toolchain.md`
+- Python：`docs/python/style_guide.md`、`docs/python/tooling.md`、`docs/python/configuration.md`
+
+> 若你的项目通过 git subtree 引入本 Playbook，常见路径为 `docs/standards/playbook/docs/...`；把上述 `docs/` 前缀替换为 `docs/standards/playbook/docs/` 即可。
+
+---
+
+## 4. 示例：`code-review-workflow`（面向专家的评审技能）
+
+将下面内容保存到：`.claude/skills/code-review-workflow/SKILL.md`
+
+```markdown
+---
+name: code-review-workflow
+description: Structured code review for TSL/C++/Python diffs & PRs. Triggers: code review, review PR, diff, 评审, 审查, 安全评审, 性能评审.
+---
+
+# Code Review Workflow
+
+## When to Use This Skill
+- Review a PR / `git diff` / patch
+- Pre-merge quality gate (correctness/security/perf/tests)
+- Risky refactor, behavior change, auth/data path changes
+
+## Inputs (required)
+- Change set: PR link or `git diff ...` output (must include context)
+- Goal: expected behavior / acceptance criteria (1–3 sentences)
+- Risk level: low|med|high (default: med)
+- Verification: test commands / repro steps (if unknown, ask first)
+
+## Procedure
+1. **Triage**
+   - Identify touched areas, public APIs, behavior changes, data/auth paths
+   - Classify risk (blast radius, rollback difficulty)
+
+2. **Correctness**
+   - Invariants, edge cases, error handling, null/empty, concurrency
+   - Backward compatibility (inputs/outputs, wire formats, config)
+
+3. **Security**
+   - AuthZ/AuthN boundaries, least privilege
+   - Input validation, injection surfaces, secrets/log redaction
+
+4. **Maintainability**
+   - Naming/structure/style aligned with Playbook docs
+   - Complexity hotspots, duplication, clarity of intent
+
+5. **Performance**
+   - Hot paths, algorithmic complexity, allocations/IO, N+1 patterns
+
+6. **Tests & Verification**
+   - Map changes → tests; identify missing coverage
+   - Provide minimal verification plan (commands + expected signals)
+
+## Review Standards (Playbook as authority)
+- Commit message: `docs/common/commit_message.md`
+- TSL: `docs/tsl/code_style.md`, `docs/tsl/naming.md`, `docs/tsl/toolchain.md`
+- C++: `docs/cpp/code_style.md`, `docs/cpp/naming.md`, `docs/cpp/toolchain.md`
+- Python: `docs/python/style_guide.md`, `docs/python/tooling.md`, `docs/python/configuration.md`
+
+## Output Contract (stable)
+- Summary: what changed & why
+- Risk: low|med|high + reasoning
+- Blockers: must-fix before merge (with file/line references when possible)
+- Non-blocking: Major / Minor / Nit
+- Questions: missing context / assumptions
+- Suggested verification: exact commands + what success looks like
+- Optional patch: minimal diff-style suggestions (only when unambiguous)
+```
+
+---
+
+## 5. 推荐外部技能（直接复用）
+
+来自仓库：https://github.com/YYH211/Claude-meta-skill
+
+### 5.1 建议引入的 3 个通用技能
+
+- `create-skill-file`：skill 编写规范 + 模板（适合团队内部统一口径）
+- `prompt-optimize`：提示词架构/对话式优化（适合为内部 agent 设计 system prompt）
+- `deep-reading-analyst`：深度阅读/多框架分析（适合评审 RFC/ADR/设计文档/长文资料）
+
+### 5.2 安装命令（项目内）
+
+```bash
+git clone https://github.com/YYH211/Claude-meta-skill.git
+mkdir -p .claude/skills
+
+cp -r Claude-meta-skill/create-skill-file .claude/skills/
+cp -r Claude-meta-skill/prompt-optimize .claude/skills/
+cp -r Claude-meta-skill/deep-reading-analyst .claude/skills/
+```
+
+---
+
+## 6. 运行时排障（面向专家）
+
+- 不触发：把真实触发词写进 `description`（贴近你们团队的说法；中英文同义词覆盖）
+- 触发错：减少关键词重叠；用更具体的上下文词（语言/工具/目录名/流程名）
+- 执行漂移：收紧 Output Contract；将高风险步骤改为“默认停下确认”；把细节拆到 `references/` 并按决策树显式加载
+

templates/python/.pre-commit-config.yaml

@@ -8,7 +8,7 @@ repos:
       - id: check-toml
 
   - repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 24.10.0
     hooks:
       - id: black
         args: ["--line-length", "80"]
@@ -22,4 +22,3 @@ repos:
     rev: 6.0.0
     hooks:
       - id: flake8
-

templates/python/.vscode/settings.json

@@ -11,4 +11,3 @@
   "python.analysis.autoImportCompletions": true,
   "python.formatting.provider": "none"
 }
-

templates/python/pyproject.toml

@@ -48,4 +48,3 @@ markers = [
   "slow: marks tests as slow",
   "integration: marks tests as integration tests",
 ]
-