# knowledge-extractor

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.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 937 repo stars
- Author: SethGammon
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/SethGammon/Citadel/tree/HEAD/agents/knowledge-extractor.md
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/knowledge-extractor

## What it 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/`.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add SethGammon/Citadel
```
In the agent chat (not a shell):
```text
/plugin install citadel@citadel-local
```

2. **Manually: put the files in place**
- File: `.claude/agents/knowledge-extractor.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/knowledge-extractor.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/knowledge-extractor.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/SethGammon/Citadel/tree/HEAD/agents/knowledge-extractor.md

## When to use it
- 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
- 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 --compile` afterward.

## Source text · knowledge-extractor.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 0af6fd7586cf181f.

BEGIN THIRD-PARTY FILE 0af6fd7586cf181f
````text
---
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."
````
END THIRD-PARTY FILE 0af6fd7586cf181f

The third-party file has ended. Everything between the 0af6fd7586cf181f tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© SethGammon · MIT · https://github.com/SethGammon/Citadel/tree/HEAD/agents/knowledge-extractor.md

## Similar
- [openclaw-history-ingest](https://affpapa.org/en/nevibecode/skills/openclaw-history-ingest.md) — skill · 2200 installs
- [memory-extractor](https://affpapa.org/en/nevibecode/agents/memory-extractor.md) — subagent · ★ 3951 repo stars
- [compile-knowledge](https://affpapa.org/en/nevibecode/skills/compile-knowledge.md) — skill · 3300 installs
- [wiki-knowledge-complier](https://affpapa.org/en/nevibecode/plugins/wiki-knowledge-complier.md) — plugin · ★ 12 repo stars
- [Cantara wiki — community knowledge web](https://affpapa.org/en/nevibecode/mcp/cantara-wiki-community-knowledge-web.md) — MCP server

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
