审计

---
name: 归档skill
description: 当用户想清理 WorkBuddy 线程、做项目交接审计、把"未完成且有价值的工作"归档并共享给团队成员时使用。触发词：归档、线程大扫除、项目交接、审计未完成事项、交接文档、团队资产库归档、把手头的活交给员工。该 Skill 会审计当前线程/工作区对应项目的未完成有价值工作，规范化分类索引，并写入项目共享资产库（资料库空间 / Project Drive），供接手员工直接执行。通用模板，可套用于任何项目线程。
---

# 归档技能 · 项目未完成事项交接审计

你是一个项目交接审计助手。当用户要求"归档 / 线程大扫除 / 项目交接 / 审计未完成事项"时，按本 Skill 执行：审计当前线程（或工作区）所指向项目的"未完成且有价值工作"，产出规范化交接文档，存入**项目共享资产库**，供接手员工直接执行。

## 填前必读（变量模式）

两种用法：
- **快速模式（推荐）**：下面 `{{}}` 变量全部留空，你先读取工作区 AGENTS.md/README/CLAUDE.md/memory 自动推断项目边界。
- **精确模式**：若用户已给出项目名、路径、云空间等，直接替换变量。

变量清单：
- `{{项目名}}`
- `{{项目简介/线上域名}}`
- `{{本地工作区路径}}`
- `{{仓库权威}}`（如 GitHub org/repo）
- `{{外部依赖/上游}}`（可选）
- `{{生产环境}}`（可选）
- `{{云空间根路径}}`（项目共享资产库 / Project Drive 根目录，**必须填共享空间，勿填个人路径**）
- `{{已知阻塞项}}`（可选，本会话已明确的卡点）

---

## 执行步骤

### #0. 项目边界（严格限定，不要跑题）
- 项目：{{项目名}} — {{项目简介}}
- 本地工作区：{{本地工作区路径}}
- 仓库权威：{{仓库权威}}
- 外部依赖：{{外部依赖/上游}}（未实际交付前不得声称已迁移）
- 生产环境：{{生产环境}}
- 审计输入源：仓库源码、AGENTS.md/README/CLAUDE.md、记忆文件（如 .workbuddy/memory/*）、git 分支与 PR、本会话已知上下文、{{已知阻塞项}}
- 若上面任一字段为空，先读取工作区内的项目说明文件自动推断，并在输出开头显式列出"推断所得的项目边界"，再继续。
- 禁止：审计与本项目无关的内容；新建功能；顺手改代码；只做盘点、分类、归档。

### #1. 审计方法（底层逻辑，必须逐条执行）
从以下来源提取"未完成且仍有价值"的事项：
(a) git 分支：列出所有未合并的功能/修复分支，记录最后提交、状态、关联需求
(b) 已合并但留 follow-up：从 commit/PR 标题与记忆文件中扫描"待做/后续/TODO/待补"
(c) 已知阻塞项：本会话与记忆中明确卡住的事（如缺失的 Token / 控制台权限 / 上游端点）
(d) 项目说明文件中声明但未落实的约束
(e) scripts/ 或校验中 failing / 带 TODO 的项

【有价值判定，满足任一才收录】
- 阻塞于明确外部条件（Token / 控制台权限 / 上游端点），解除后可直接推进
- 有业务或安全风险，不处理会影响线上质量或安全
- 含可复用结论，员工接手能明显省时

【无价值，直接排除】
- 已合并且验收通过、无后续动作
- 纯临时沟通、已过期、结论已迁移别处
- 仅闲聊、无执行含义

### #2. 分类与索引规范（规范化，必须统一）
分类 Category：
  F-功能开发 / S-安全合规 / O-部署运维 / B-Bug修复 / T-测试验收 / D-技术债务
优先级 Priority：P0 阻断或高危 / P1 重要 / P2 常规
状态 Status：待办 / 进行中 / 已阻塞 / 已放弃
稳定 ID：<Category>-<两位序号>，例 S-01、O-02

索引总表字段（输出为表格）：
  ID | 分类 | 优先级 | 状态 | 标题 | 阻塞点 | 接手所需条件 | 关联文件/PR/commit

每条明细必须包含（员工可照做）：
  - 背景与目标（为什么要做）
  - 当前进展与证据（读了哪个文件/哪次部署，不要凭空断言）
  - 卡点与解除条件（谁、什么权限、什么端点）
  - 执行 SOP（具体步骤 + 验证命令）
  - 验收标准（怎样算做完）
  - 需要的 Skill / 文件 / 权限清单

### #3. 需要的 Skill / 文件清单（单独成章，便于员工准备）
- 逐项列出接手人要用到的能力；先盘点每条事项实际需要的动作，再归并。
- 自动探测本环境可用能力（如：资料库/tencent-docs 写共享空间、测试验收角色指令、部署脚本、SSH/Docker 等），列出名称与用途。
- 对需要但本环境没有的能力（如外部控制台、上游改造），标注负责角色（如"后端 owner""云控制台管理员"）。

### #4. 云空间落盘（交接交付物）
- 目标库必须是【项目共享资产库】（WorkBuddy 资料库空间 / 项目 Project Drive），
  严禁落到个人腾讯文档、个人网盘或本机路径——否则接手员工看不到。
- 使用"资料库"能力，在该共享空间下创建：
    /项目交接/<YYYY-MM-DD>-未完成事项交接/
      ├─ 00-索引总表.md        （索引总表 + 分类统计）
      ├─ 01-分类明细.md        （每条完整 SOP）
      ├─ 02-Skill与文件清单.md （接手准备）
      └─ 03-接手须知.md        （环境、权限申请、沟通链路、禁止项）
- 共享范围：对该项目/空间的成员可见（非全公司）。如需特定人可见，明列成员。
- 遵循写入规则：本地生成并展示 → 取得用户确认 → 再上传，不覆盖他人文件。
- 落盘前在 chat 返回结构化摘要供核对。

### #5. 执行约束
- 不展开新任务、不修改业务代码
- 所有"证据"必须来自实际读取的文件/分支/日志，禁止猜测
- 输出先结构化返回给用户确认，再落盘云空间
- 最后给出：本次审计覆盖了多少源、收录多少条、各分类数量、最该优先处理的 P0 是哪几条

---

## 完成判定
当用户在 chat 中确认结构化摘要、且文件已成功写入项目共享资产库对应路径后，本 Skill 完成。未获用户确认前不得上传。

---
name: skill-optimizer
description: "Diagnose and optimize Agent Skills (SKILL.md) with real session data and research-backed static analysis. Use when auditing skill quality, checking trigger/undertrigger problems, or reviewing SKILL.md structure. Works with WorkBuddy, Claude Code, Codex, and any Agent Skills-compatible agent."
risk: safe
source: hqhq1025/skill-optimizer (MIT)，WorkBuddy 适配版
date_added: "2026-08-24"
---

## When to Use This Skill

- Use when skills are not triggering as expected or seem broken
- Use when you want to audit and improve your skill library's quality
- Use when you want to understand which skills are underperforming or wasting context tokens

## Rules

- **Read-only**: never modify skill files. Only output report.
- **All 8 dimensions**: do not skip any. If data is insufficient, report "N/A — insufficient session data" rather than omitting.
- **Quantify**: "you had 12 research tasks last week but the skill never triggered" beats "you often do research".
- **Suggest, don't prescribe**: give specific wording suggestions for description improvements, but frame as suggestions.
- **Show evidence**: for undertrigger claims, quote the actual user message that should have triggered the skill.
- **Evidence-based suggestions**: when suggesting description rewrites, cite the specific research finding that motivates the change (e.g., "front-load trigger keywords — MCP study shows 3.6x selection rate improvement").

## Overview

Analyze skills using **historical session data + static quality checks**, output a diagnostic report with P0/P1/P2 prioritized fixes. Scores each skill on a 5-point composite scale across 8 dimensions.

CSO (Claude/Agent Search Optimization) = writing skill descriptions so agents select the right skill at the right time. This skill checks for CSO violations.

## Usage

- `/optimize-skill` → scan all skills
- `/optimize-skill my-skill` → single skill
- `/optimize-skill skill-a skill-b` → multiple specified skills

## Data Sources

Auto-detect the current agent platform and scan the corresponding paths:

| Source | WorkBuddy | Claude Code | Codex | Shared |
|--------|-----------|------------|-------|--------|
| Session transcripts | `~/.workbuddy/sessions/*.json`（按会话 ID 存 JSON，非 JSONL；结构未公开，解析失败时按规则报 N/A）；`~/.workbuddy/audit-log/*.jsonl`（工具审计日志，可作调用证据） | `~/.claude/projects/**/*.jsonl` | `~/.codex/sessions/**/*.jsonl` | — |
| Skill files | `~/.workbuddy/skills/*/SKILL.md` | `~/.claude/skills/*/SKILL.md` | `~/.codex/skills/*/SKILL.md` | `~/.agents/skills/*/SKILL.md` |

**Platform detection:** Check which directories exist. Scan all available sources — a user may have multiple agents installed. WorkBuddy 会话 JSON 结构未知时，不要猜测字段；改用 audit-log JSONL 与静态维度出报告，会话维度标 N/A。

## Workflow

```
Identify target skills
        ↓
Collect session data (python3 scripts scan JSONL transcripts)
        ↓
Run 8 analysis dimensions
        ↓
Compute composite scores
        ↓
Output report with P0/P1/P2
```

### Step 1: Identify Target Skills

Scan skill directories in order: `~/.workbuddy/skills/`, `~/.claude/skills/`, `~/.codex/skills/`, `~/.agents/skills/`. Deduplicate by skill name (same name in multiple locations = same skill). For each, read `SKILL.md` and extract:
- name, description (from YAML frontmatter)
- trigger keywords (from description field)
- defined workflow steps (Step 1/2/3... or ### sections under Workflow)
- word count

If user specified skill names, filter to only those.

### Step 2: Collect Session Data

Use python3 scripts via Bash to scan session JSONL files. Extract:

**Claude Code sessions** (`~/.claude/projects/**/*.jsonl`):
- `Skill` tool_use calls (which skills were invoked)
- User messages (full text)
- Assistant messages after skill invocation (for workflow tracking)
- User messages after skill invocation (for reaction analysis)

**Codex sessions** (`~/.codex/sessions/**/*.jsonl`):
- `session_meta` events → extract `base_instructions` for skill loading evidence
- `response_item` events → assistant outputs (workflow tracking)
- `event_msg` events → tool execution and skill-related events
- User messages from `turn_context` events (for reaction analysis)

**Note:** Codex injects skills via context rather than explicit `Skill` tool calls. Skill loading (present in `base_instructions`) does NOT equal active invocation. To detect actual use, search for skill-specific workflow markers (step headers, output formats) in `response_item` content within that session. A skill is "invoked" only if the agent produced output following the skill's defined workflow.

**Aggregated:**
- Per-skill: invocation count, trigger keyword match count
- Per-skill: user reaction sentiment after invocation
- Per-skill: workflow step completion markers

### Step 3: Run 8 Analysis Dimensions

**You MUST run ALL 8 dimensions.** The baseline behavior without this skill is to skip dimensions 4.2, 4.3, 4.5b, and 4.8. These are the most valuable dimensions — do not skip them.

#### 4.1 Trigger Rate

Count how many times each skill was actually invoked vs how many times its trigger keywords appeared in user messages.

**Claude Code:** count `Skill` tool_use calls in transcripts.
**Codex:** count sessions where the agent produced output following the skill's workflow markers (not merely loaded in context).

**Diagnose:**
- Never triggered → skill may be useless or trigger words wrong
- Keywords match >> actual invocations → undertrigger problem, description needs work
- High frequency → core skill, worth optimizing

#### 4.2 Post-Invocation User Reaction

**This dimension is critical and easy to skip. Do not skip it.**

After a skill is invoked in a session, read the user's next 3 messages. Classify:
- **Negative**: "no", "wrong", "never mind", "not what I wanted", user interrupts
- **Correction**: user re-describes their intent, manually overrides skill output
- **Positive**: "good", "ok", "continue", "nice", user follows the workflow
- **Silent switch**: user changes topic entirely (likely false positive trigger)

Report per-skill satisfaction rate.

#### 4.3 Workflow Completion Rate

**This dimension is critical and easy to skip. Do not skip it.**

For each skill invocation found in session data:
1. Extract the skill's defined steps from SKILL.md
2. Search the assistant messages in that session for step markers (Step N, specific output formats defined in the skill)
3. Calculate: how far did execution get?

Report: `{skill-name} (N steps): avg completed Step X/N (Y%)`

If a specific step is frequently where execution stops, flag it.

#### 4.4 Static Quality Analysis

Check each SKILL.md against these 14 rules:

| Check | Pass Criteria |
|-------|--------------|
| Frontmatter format | Only `name` + `description`, total < 1024 chars |
| Name format | Letters, numbers, hyphens only |
| Description trigger | Starts with "Use when..." or has explicit trigger conditions |
| Description workflow leak | Description does NOT summarize the skill's workflow steps (CSO violation) |
| Description pushiness | Description actively claims scenarios where it should be used, not just passive |
| Overview section | Present |
| Rules section | Present |
| MUST/NEVER density | Count ALL-CAPS directive words; >5 per 100 words = flag |
| Word count | < 500 words (flag if over) |
| Narrative anti-pattern | No "In session X, we found..." storytelling |
| YAML quoting safety | description containing `: ` must be wrapped in double quotes |
| Critical info position | Core trigger conditions and primary actions must be in the first 20% of SKILL.md |
| Description 250-char check | Primary trigger keywords must appear within the first 250 characters of description |
| Trigger condition count | ≤ 2 trigger conditions in description is ideal |

#### 4.5a False Positive Rate (Overtrigger)

Skill was invoked but user immediately rejected or ignored it.

#### 4.5b Undertrigger Detection

**This is the highest-value dimension.** For each skill, extract its **capability keywords** (not just trigger keywords — what the skill CAN do). Then scan user messages for tasks that match those capabilities but where the skill was NOT invoked.

Report: which user messages SHOULD have triggered the skill but didn't, and suggest description improvements.

**Compounding Risk Assessment:**
For skills with chronic undertriggering (0 triggers across 5+ sessions where relevant tasks appeared), flag as "compounding risk" — undertriggered skills cannot self-improve through usage feedback, causing the gap to widen over time. Recommend immediate description rewrite as P0.

#### 4.6 Cross-Skill Conflicts

Compare all skill pairs:
- Trigger keyword overlap (same keywords in two descriptions)
- Workflow overlap (two skills teach similar processes)
- Contradictory guidance

#### 4.7 Environment Consistency

For each skill, extract referenced:
- File paths → check if they exist (`test -e`)
- CLI tools → check if installed (`which`)
- Directories → check if they exist

Flag any broken references.

#### 4.8 Token Economics

**This dimension is critical and easy to skip. Do not skip it.**

For each skill:
- Word count (from Step 1)
- Trigger frequency (from 4.1)
- Cost-effectiveness = trigger count / word count
- Flag: large + never-triggered skills as candidates for removal or compression

**Progressive Disclosure Tier Check:**
Evaluate each skill against the 3-tier loading model:
- Tier 1 (frontmatter): ~100 tokens. Check: is description ≤ 1024 chars?
- Tier 2 (SKILL.md body): <500 lines recommended. Check: word count.
- Tier 3 (reference files): loaded on demand. Check: does skill use reference files for detailed content, or cram everything into SKILL.md?

Flag skills that put 500+ words in SKILL.md without using reference files as "poor progressive disclosure".

### Step 4: Composite Score

Rate each skill on a 5-point scale:

| Score | Meaning |
|-------|---------|
| 5 | Healthy: high trigger rate, positive reactions, complete workflows, clean static |
| 4 | Good: minor issues in 1-2 dimensions |
| 3 | Needs attention: significant gap in 1 dimension or minor gaps in 3+ |
| 2 | Problematic: never triggered, or negative user reactions, or major static issues |
| 1 | Broken: doesn't work, references missing, or fundamentally misaligned |

**Scored dimensions** (weighted average):
- Trigger rate: 25%
- User reaction: 20%
- Workflow completion: 15%
- Static quality: 15%
- Undertrigger: 15%
- Token economics: 10%

**Qualitative dimensions** (reported but not scored):
- 4.5a Overtrigger: reported as count + examples
- 4.6 Cross-Skill Conflicts: reported as conflict pairs
- 4.7 Environment Consistency: reported as pass/fail per reference

## Report Format

```markdown
# Skill Optimization Report
**Date**: {date}
**Scope**: {all / specified skills}
**Session data**: {N} sessions, {date range}

## Overview
| Skill | Triggers | Reaction | Completion | Static | Undertrigger | Token | Score |
|-------|----------|----------|------------|--------|--------------|-------|-------|
| example-skill | 2 | 100% | 86% | B+ | 1 miss | 486w | 4/5 |

## P0 Fixes (blocking usage)
1. ...

## P1 Improvements (better experience)
1. ...

## P2 Optional Optimizations
1. ...

## Per-Skill Diagnostics
### {skill-name}
#### 4.1 Trigger Rate
...
#### 4.2 User Reaction
...
(all 8 dimensions)
```

## Research Background

The analysis dimensions in this report are grounded in the following research:
- **Undertrigger detection**: Memento-Skills (arXiv:2603.18743) — skills as structured files require accurate routing; unrouted skills cannot self-improve via the read-write learning loop
- **Description quality**: MCP Description Quality (arXiv:2602.18914) — well-written descriptions achieve 72% tool selection rate vs. 20% random baseline (3.6x improvement)
- **Information position**: Lost in the Middle (Liu et al., TACL 2024) — U-shaped LLM attention curve
- **Format impact**: He et al. (arXiv:2411.10541) — format changes alone can cause 9-40% performance variance
- **Instruction compliance**: IFEval (arXiv:2311.07911) — LLMs struggle with multi-constraint prompts

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.