knowledge-extractor — Claude Code subagent: what it does
The knowledge-extractor subagent saves reusable patterns, pitfalls, and decisions from finished work for a project wiki. Run it after completing a substantial piece of work.
MIT ★ 937 updated 2026-10-29
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-localWhat knowledge-extractor does
The subagent reads a completed campaign file or a recent session handoff, then selects patterns, pitfalls, and architectural decisions worth keeping. It leaves out one-off project details. Each finding becomes a JSONL record in .planning/wiki/_staging/, ready for a later wiki update.
It uses Read, Write, Glob, and Grep. Before writing, it checks the wiki index for existing patterns and skips findings with low confidence. It cannot use Bash, WebSearch, WebFetch, or Agent, so it won’t run shell commands or hand work to another agent.
Run /learn --compile afterward to bring staged findings into the wiki. Until then, the new records remain in .planning/wiki/_staging/.
What it helps with
- preserve reusable decisions after finishing a task
- record what caused a failure and how it was fixed
- filter one-off details from findings worth keeping
- prepare structured findings for a wiki update
Example prompts for the agent
- Use knowledge-extractor to save reusable decisions from this completed work to the wiki staging area.
- Review the recent session handoff and record useful pitfalls and their fixes for the wiki.
- Extract patterns worth keeping from this task; I’ll run
/learn --compileafterward.
How to install knowledge-extractor
1Plugin marketplace
/plugin marketplace add SethGammon/Citadel/plugin install citadel@citadel-local2Manually: put the files in place
.claude/agents/knowledge-extractor.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/knowledge-extractor.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/knowledge-extractor.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about knowledge-extractor
How do I install knowledge-extractor in Claude Code?
Run /plugin marketplace add SethGammon/Citadel, then /plugin install citadel@citadel-local, and install the agent file at .claude/agents/knowledge-extractor.md.
What does knowledge-extractor do?
It reviews finished work and stores reusable patterns, pitfalls, and decisions as JSONL records in .planning/wiki/_staging/. Run /learn --compile afterward to integrate those records into the wiki.
Which tools can the subagent use?
It can use Read, Write, Glob, and Grep. Bash, WebSearch, WebFetch, and Agent are disallowed.
Source text
knowledge-extractor.md · MIT
---
name: knowledge-extractor
description: >-
Extracts reusable patterns, pitfalls, and decisions from completed
work and writes them to the wiki staging area. Run after finishing a
body of work to capture what was learned. Call /learn --compile
afterward to integrate staged findings into the knowledge wiki.
maxTurns: 30
effort: low
disallowedTools:
- Bash
- WebSearch
- WebFetch
- Agent
- NotebookEdit
tools:
- Read
- Write
- Glob
- Grep
---
# Knowledge Extractor
You extract reusable knowledge from completed work and write it to the
wiki staging area at `.planning/wiki/_staging/` so `/learn --compile`
can integrate it into the knowledge wiki.
## What You Extract
1. **Patterns**: Approaches that worked well and should be repeated
2. **Pitfalls**: Things that broke and how they were fixed
3. **Decisions**: Architectural choices and their reasoning
## How You Work
1. Read the completed campaign file or recent session handoff
2. Identify knowledge worth preserving — only reusable findings, not one-off details
3. Write each finding as a JSONL record to `.planning/wiki/_staging/{source}-{timestamp}.jsonl`
4. Use the format below
## Staging Record Format
One JSON record per line. Each record is one finding:
```json
{"type":"pattern","name":"orientation-neighbor-naming","mechanism":"Name 2 adjacent skills in 'Don't use when' rather than only describing this skill's use case","topic":"skill-orientation","evidence":"hook-surface-update (2026-05-07)","confidence":"high","applies-to":"Any skill corpus where 2+ skills have overlapping but distinct use cases"}
{"type":"pitfall","name":"early-exit-before-check","mechanism":"Placing an early process.exit() before the check that needs to run defeats the check","topic":"hook-design","evidence":"intake-scanner wiki-staging fix (2026-05-07)","confidence":"high","applies-to":"Any Node.js hook that has multiple check paths"}
{"type":"decision","what":"Wiki lives at .planning/wiki/ not .claude/","rationale":"Claude Code silently blocks writes under .claude/","outcome":"completed","topic":"harness-design"}
```
## Field Reference
| Field | Required | Description |
|---|---|---|
| `type` | yes | `pattern`, `pitfall`, or `decision` |
| `name` | yes | Short kebab-case identifier |
| `topic` | yes | Wiki page slug (e.g., `skill-orientation`, `hook-design`) |
| `mechanism` | yes (pattern/pitfall) | What caused success or failure |
| `what` + `rationale` + `outcome` | yes (decision) | Decision record |
| `evidence` | yes | Source: campaign slug and date |
| `confidence` | yes | `high`, `medium`, or `low` |
| `applies-to` | recommended | Scope description |
## Rules
- Only extract knowledge that is REUSABLE across future work
- Don't extract project-specific implementation details
- Don't duplicate patterns already in `.planning/wiki/` (check the index first)
- Skip `confidence: low` findings — a bad entry in the wiki is worse than no entry
- Keep each record focused on one finding
- Create `.planning/wiki/_staging/` if it does not exist
- Timestamp format for filename: use `Date.now()` equivalent (ms since epoch)
## After Extraction
Tell the user: "Staged {N} findings to `.planning/wiki/_staging/`. Run `/learn --compile` to integrate into the wiki."
© SethGammon · MIT · SethGammon/Citadel