skill-finder

Files (69)

• SKILL.md
• README.md · evals/
• evals.json · evals/
• make-world.mjs · evals/fixtures/
• trigger-eval.json · evals/
• adapter-contract.md · references/
• eval-harvest.md · references/
• evidence-schema.md · references/
• family-prompt.md · references/
• family-schema.md · references/
• gate-brief.md · references/
• learnings-format.md · references/
• ranking.md · references/
• report-format.md · references/
• claude-sessions.md · references/sources/
• openspec-archive.md · references/sources/
• summary-prompt.md · references/
• summary-schema.md · references/
• aggregate.mjs · scripts/
• aggregate.test.mjs · scripts/
• audit-evidence.mjs · scripts/
• audit-evidence.test.mjs · scripts/
• check-summaries.mjs · scripts/
• check-summaries.test.mjs · scripts/
• extract-claude-sessions.mjs · scripts/
• extract-claude-sessions.test.mjs · scripts/
• extract-openspec-archive.mjs · scripts/
• extract-openspec-archive.test.mjs · scripts/
• build.mjs · scripts/fixtures/catalog/
• 11111111-1111-4111-8111-111111111111.jsonl · scripts/fixtures/claude-sessions/store/
• agent-a1.jsonl · scripts/fixtures/claude-sessions/store/11111111-1111-4111-8111-111111111111/subagents/
• 22222222-2222-4222-8222-222222222222.jsonl · scripts/fixtures/claude-sessions/store/
• .openspec.yaml · scripts/fixtures/openspec-archive/openspec/changes/archive/2026-09-01-add-sim-runner-deploy/
• design.md · scripts/fixtures/openspec-archive/openspec/changes/archive/2026-09-01-add-sim-runner-deploy/
• proposal.md · scripts/fixtures/openspec-archive/openspec/changes/archive/2026-09-01-add-sim-runner-deploy/
• spec.md · scripts/fixtures/openspec-archive/openspec/changes/archive/2026-09-01-add-sim-runner-deploy/specs/deploy-checks/
• spec.md · scripts/fixtures/openspec-archive/openspec/changes/archive/2026-09-01-add-sim-runner-deploy/specs/sim-runner/
• tasks.md · scripts/fixtures/openspec-archive/openspec/changes/archive/2026-09-01-add-sim-runner-deploy/
• .openspec.yaml · scripts/fixtures/openspec-archive/openspec/changes/archive/2026-09-05-fix-grafana-alerts/
• proposal.md · scripts/fixtures/openspec-archive/openspec/changes/archive/2026-09-05-fix-grafana-alerts/
• spec.md · scripts/fixtures/openspec-archive/openspec/changes/archive/2026-09-05-fix-grafana-alerts/specs/alerts/
• tasks.md · scripts/fixtures/openspec-archive/openspec/changes/archive/2026-09-05-fix-grafana-alerts/
• proposal.md · scripts/fixtures/openspec-archive/openspec/changes/archive/2026-09-10-drop-legacy-api/
• tasks.md · scripts/fixtures/openspec-archive/openspec/changes/archive/2026-09-10-drop-legacy-api/
• README.md · scripts/fixtures/openspec-archive/openspec/changes/archive/notes/
• invalid-batch.json · scripts/fixtures/summaries/
• valid-batch.txt · scripts/fixtures/summaries/
• harvest-evals.mjs · scripts/
• harvest-evals.test.mjs · scripts/
• index-catalog.mjs · scripts/
• index-catalog.test.mjs · scripts/
• init-run.mjs · scripts/
• init-run.test.mjs · scripts/
• lib.test.mjs · scripts/
• args.mjs · scripts/lib/
• digest.mjs · scripts/lib/
• jsonl.mjs · scripts/lib/
• paths.mjs · scripts/lib/
• redact.mjs · scripts/lib/
• testing.mjs · scripts/lib/
• …and 9 more

SKILL.md (first lines)

# skill-finder

Find recurring work in the history that the user names. Compare it with the installed skills. Suggest changes of three kinds:

| Kind | Meaning | Output |
| :--- | :--- | :--- |
| `new-skill` | Recurring work. No catalog skill covers it. | A `skill-creator` handoff brief with harvested evals. |
| `silent-skill` | A catalog skill matches the work. It never fired in those episodes. | An exact description edit, with a trigger eval set. |
| `misfiring-skill` | A skill fired, and the user corrected the agent in the same episodes again and again. | A `## Learnings` entry, with behavior evals. |

The skill stops at a report. It changes a skill only after two approvals.

## Rules

- Keep raw history local. Do not put tool results, file contents, or raw session lines in the chat, the report, or the evals.
- Read `aggregate.json`, not all of `evidence.jsonl`. Open an evidence record or a digest only for a candidate that you judge.
- Do not force a suggestion. When no candidate passes, say so.
- Do not commit, push, or merge.
- Do not edit a plugin-origin skill. Stage the edit in the run folder.
- Do not edit `.gitignore`.

## Scripts

The scripts are in `${CLAUDE_SKILL_DIR}/scripts/`. Each script prints one JSON line. Exit code 0 is success, 1 is a usage or validation failure, and 2 is a missing or unreadable input. In the commands, `<run>` is the run folder from step 2.

## Procedure

### 1. Check and ask

1. Run `node --version`. Stop when the major version is less than 18.
2. Get the sources and the time window. When the user did not name them, ask one question. Offer this default: Claude Code sessions for the current project, for the last 90 days.

| Source | Knowledge | Extractor |
| :--- | :--- | :--- |
| `claude-sessions` | [references/sources/claude-sessions.md](references/sources/claude-sessions.md) | `extract-claude-sessions.mjs` |
| `openspec-archive` | [references/sources/openspec-archive.md](references/sources/openspec-archive.md) | `extract-openspec-archive.mjs` |

To add a source, follow [references/adapter-contract.md](references/adapter-contract.md).

### 2. Start a run

```bash
node "${CLAUDE_SKILL_DIR}/scripts/init-run.mjs" --cwd "$PWD" --slug <short-name> --source "<source and its flags>" --since <date>
```

Use the `run` value from the output as `<run>`. When `gitignoreWarning` is `true`, tell the user to add `.skill-finder/` to `.gitignore`.

### 3. Extract

Run one extractor for each source:

```bash
node "${CLAUDE_SKILL_DIR}/scripts/extract-claude-sessions.mjs" --out <run> --project "$PWD" --since <date>
node "${CLAUDE_SKILL_DIR}/scripts/extract-openspec-archive.mjs" --out <run> --path <repo>/openspec/changes/archive --since <date>
```

When the user names a session folder, use `--store <dir>` instead of `--project`. Use `--store` more than one time for worktree folders. Show the one-line summary of each extractor.

When an extractor exits 2, stop. Name the missing source. Do not continue with other sources, and do not suggest a skill.

### 4. Audit

```bash
node "${CLAUDE_SKILL_DIR}/scripts/audit-evidence.mjs" <run>/evidence.jsonl --strict
```

When it exits 1, stop and show the errors from `<run>/evidence-audit.json`. Keep the warnings for the report limitations.

### 5. Index the catalog

```bash
node "${CLAUDE_SKILL_DIR}/scripts/index-catalog.mjs" --cwd "$PWD" --out <run>/catalog.json
```

When the user names another home folder, add `--home <dir>`. Add `--root <dir>` for each extra skill folder that the user names.

When the summary shows `warnings` above 0, copy the messages from `catalog.json` into the report limitations.

### 6. Summarize episodes

Read [references/summary-schema.md](references/summary-schema.md). Then run:

```bash
node "${CLAUDE_SKILL_DIR}/scripts/check-summaries.mjs" --run <run> --plan
```

Tell the user the digest count, the total size, and the call count. Ask for a yes. A run without summaries finds much less, because task keys then come only from titles and corrections. When the user says no, tell them this. On a no, or when no backend is available, run the next command and go to step 7:

```bash
node "${CLAUDE_SKILL_DIR}/scripts/merge-summaries.mjs" --run <run> --backend none
```

On a yes, use the first backend that is available: `shunt:bulk-reader` (Pi), then the `Agent` tool. The schema document tells how to call each one. Run up to 4 batches at the same time. Check each batch:

```bash
node "${CLAUDE_SKILL_DIR}/scripts/check-summaries.mjs" --run <run> --batch <run>/summaries/batch-01.json
```

When a check exits 1, run that batch again one time. After a second failure, leave the batch. Then merge and audit again:

```bash
node "${CLAUDE_SKILL_DIR}/scripts/merge-summaries.mjs" --run <run> --backend <pi|subagent>
node "${CLAUDE_SKILL_DIR}/scripts/audit-evidence.mjs" <run>/evidence.jsonl --expect-summaries
```

### 7. Scope families

Read [references/family-schema.md](references/family-schema.md). Then run:

```bash
node "${CLAUDE_SKILL_DIR}/scripts/scope-families.mjs" --run <run> --plan
```

The plan writes one line for each episode, in batches of 400. This step needs one backend call for each batch. The yes from step 6 covers these calls. When the user said no in step 6, tell them the line count and ask for a yes now. Without families, the aggregation finds recurring work only when two summaries use the same words. On a no, or when no backend is available, run the next command and go to step 8:

```bash
node "${CLAUDE_SKILL_DIR}/scripts/scope-families.mjs" --run <run> --backend none
```

From Kotivskyi/skills, MIT.

More from Kotivskyi/skills