diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f3bf10e70..5a3bd6d79 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -92,10 +92,10 @@ "tags": ["prototype", "spike", "throwaway", "design", "ui", "state-machine", "skill"] }, { - "name": "book-distill", - "source": "./plugins/book-distill", + "name": "knowledge", + "source": "./plugins/knowledge", "category": "knowledge", - "tags": ["book", "distill", "pdf", "epub", "skill", "knowledge", "reference", "documentation"] + "tags": ["knowledge", "distill", "book", "pdf", "epub", "skill", "reference", "synthesis", "ingest"] }, { "name": "context7", @@ -241,5 +241,8 @@ "category": "modeling", "tags": ["event-storming", "ddd", "domain-modeling", "bounded-contexts", "miro", "facilitation", "simulation", "skill"] } - ] + ], + "renames": { + "book-distill": "knowledge" + } } diff --git a/README.md b/README.md index 48a6ece94..70d3d670b 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ Browse and manage with `/plugin`. To refresh after updates: `/plugin marketplace | [`improve-architecture`](plugins/improve-architecture) | Skill | Scans an existing codebase for module-level architecture friction — shallow modules, seam leaks, locality gaps — using Ousterhout's deep-module lens, presents candidates as a self-contained HTML report, and interviews the selected candidate before handing off for planning. | | [`mcp-tool-audit`](plugins/mcp-tool-audit) | Skill | Audits MCP server tool definitions against MCP-spec and Anthropic tool-design criteria, returning a per-tool PASS/WARN/FAIL scorecard. Language-agnostic (Python, TypeScript, .NET). | | [`prototype`](plugins/prototype) | Skills | Builds throwaway code to answer a design question before committing to architecture. Ships two skills: `/prototype:logic` (an interactive terminal app over a portable state model) and `/prototype:ui` (radically different visual variants on one route). | -| [`book-distill`](plugins/book-distill) | Skill | Distills a technical book (PDF or EPUB) into concept-organized, author-attributed skill reference files through a structured multi-session read-write pipeline, updating the target skill's routing table. | +| [`knowledge`](plugins/knowledge) | Skills | Ingests external knowledge into durable, synthesized artifacts. Ships `/knowledge:book-distill` (distills a technical book — PDF or EPUB — into concept-organized, author-attributed skill reference files, updating the target skill's routing table) and `/knowledge:setup` (settles the configurable `library_dir` artifact-landing location). | | [`context7`](plugins/context7) | Skill | Looks up current library documentation, API references, and code examples via Context7 — a two-step resolve-then-query workflow over the `ctx7` CLI or the consumer's Context7 MCP server, plus an upstream drift-check `update` action. | | [`thariq-skills`](plugins/thariq-skills) | Skill | Ships Anthropic's internal skill-authoring playbook as an on-demand knowledge skill — 9 skill categories, 9 authoring tips (gotchas sections, progressive disclosure, description-as-trigger), and distribution guidance, with a vendored upstream baseline and drift-check update script. | | [`boris`](plugins/boris) | Skill | Ships Boris Cherny's Claude Code workflow tips (howborisusesclaudecode.com) as an on-demand knowledge skill — 107 tips across 95 sections routed through topic reference files, with a vendored upstream baseline and drift-check update script. | diff --git a/plugins/book-distill/.claude-plugin/plugin.json b/plugins/book-distill/.claude-plugin/plugin.json deleted file mode 100644 index a2e52911c..000000000 --- a/plugins/book-distill/.claude-plugin/plugin.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", - "name": "book-distill", - "version": "0.1.1", - "description": "Distills a technical book (PDF or EPUB) into concept-organized, author-attributed skill reference files through a structured multi-session read-write pipeline.", - "author": { - "name": "Melodic Software", - "email": "info@melodicsoftware.com" - }, - "license": "MIT", - "keywords": ["book", "distill", "pdf", "epub", "skill", "knowledge", "reference", "documentation"] -} diff --git a/plugins/book-distill/README.md b/plugins/book-distill/README.md deleted file mode 100644 index 353341b04..000000000 --- a/plugins/book-distill/README.md +++ /dev/null @@ -1,77 +0,0 @@ -# book-distill - -A Claude Code plugin that turns a technical book (PDF or EPUB) into -concept-organized, author-attributed **skill reference files** through a -structured, multi-session read-write pipeline. It is a neutral generator: it -applies a distillation method to whatever book you point it at. - -Invoke it with `/book-distill:book-distill` and give it a source path and a -target skill name. - -## What it produces - -- **Concept-organized reference files** (60-160 lines each), named by what they - teach rather than by chapter number, with the author attributed in section - headers. -- **Routing-table and quick-decision-guide updates** to the target skill's - `SKILL.md`, so the skill loads the right reference file for a given developer - question at query time. -- **Multi-author merges** — where two books cover the same concept, their - content is consolidated into a shared file. - -Output lands in a **target skill** inside your project -(`${CLAUDE_PROJECT_DIR}/.claude/skills//`) — either an existing skill it -extends or a new one it creates. You name the target when you invoke the tool, so -you always know where the output goes. - -## How it works - -A book is distilled over several sessions (~3 chapters each) using a strict -**read-one-chapter, write-its-file-immediately** loop — the interleave is what -keeps each file focused. Cross-session progress (the file plan, page map, and a -checklist) is tracked in a progress file under `${CLAUDE_PLUGIN_DATA}`, which -survives plugin updates, and a continuation prompt generated at each session end -tells the next session exactly where to resume. See the skill body for the full -five-phase method. - -## Usage caution — copyright - -This plugin is a neutral tool; **you own the rights decision** for everything you -distill with it. A condensed distillation of a copyrighted book is a -**derivative work** (17 U.S.C. §§ 101, 106) — the copyright holder's exclusive -rights include preparing and distributing derivatives — so distilled outputs -carry **redistribution risk**. Keeping a private distillation for your own study -is a different act from publishing, committing, or sharing one; fair use is a -defense raised after the fact, not a safe harbor you can assume in advance. -Publish, commit, or redistribute a distilled output only once you have satisfied -yourself that doing so is lawful for that book. This is a caution, not legal -advice. - -The distilled output is written into a skill that Claude later **auto-loads as -model context** — so review it before you commit or share it: treat the source -book as untrusted input and confirm the distillation reflects the book rather than -any instructions injected through its text. - -## Requirements - -- A PDF or EPUB you have the right to read. PDF works natively with Claude - Code's Read tool; EPUB requires unzipping and text extraction first. - -## Install - -```shell -/plugin marketplace add melodic-software/claude-code-plugins -/plugin install book-distill@melodic-software -``` - -## Configuration - -This plugin has no `userConfig`. The two things it needs are supplied when you -invoke it — the **source path** and the **target skill name** — and its -cross-session state persists automatically under `${CLAUDE_PLUGIN_DATA}`. There -is nothing to configure and nothing to edit in the plugin itself. - -## License - -MIT (SPDX-License-Identifier: MIT). See the LICENSE file at the root of the -melodic-software/claude-code-plugins repository. diff --git a/plugins/knowledge/.claude-plugin/plugin.json b/plugins/knowledge/.claude-plugin/plugin.json new file mode 100644 index 000000000..335530618 --- /dev/null +++ b/plugins/knowledge/.claude-plugin/plugin.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", + "name": "knowledge", + "version": "0.1.1", + "description": "Ingest external knowledge into durable, synthesized artifacts. Ships a book-distillation pipeline (PDF/EPUB into concept-organized, author-attributed skill reference files) plus a re-runnable setup action; a configurable library directory governs where synthesized artifacts land in the consuming repo.", + "author": { + "name": "Melodic Software", + "email": "info@melodicsoftware.com" + }, + "license": "MIT", + "keywords": ["knowledge", "distill", "book", "pdf", "epub", "skill", "reference", "synthesis", "ingest"], + "userConfig": { + "library_dir": { + "type": "directory", + "title": "Knowledge library directory", + "description": "Project-relative directory in the consuming repo where synthesized knowledge artifacts land. Default is the repo root. A working-notes or artifacts convention declared in your own project's CLAUDE.md or rules takes precedence.", + "default": "." + } + } +} diff --git a/plugins/knowledge/README.md b/plugins/knowledge/README.md new file mode 100644 index 000000000..e3ba63a2c --- /dev/null +++ b/plugins/knowledge/README.md @@ -0,0 +1,89 @@ +# knowledge + +A Claude Code plugin that ingests external knowledge into durable, synthesized +artifacts. Its first shipped pipeline distills a technical book (PDF or EPUB) into +concept-organized, author-attributed **skill reference files**; a re-runnable +`setup` action settles where synthesized artifacts land in the consuming repo. + +## Skills + +| Skill | Invoke | What it does | +|---|---|---| +| `book-distill` | `/knowledge:book-distill` | Turns a technical book (PDF/EPUB) into concept-organized, author-attributed skill reference files through a structured, multi-session read-write pipeline, updating the target skill's routing table. | +| `setup` | `/knowledge:setup` | Interviews the consumer and persists the `library_dir` config (idempotent — re-run to reconfigure). | + +## What book-distill produces + +- **Concept-organized reference files** (60-160 lines each), named by what they + teach rather than by chapter number, with the author attributed in section + headers. +- **Routing-table and quick-decision-guide updates** to the target skill's + `SKILL.md`, so the skill loads the right reference file for a given developer + question at query time. +- **Multi-author merges** — where two books cover the same concept, their + content is consolidated into a shared file. + +You name the target skill when you invoke `/knowledge:book-distill`, so output +lands somewhere you chose (`${CLAUDE_PROJECT_DIR}/.claude/skills//`) — +either an existing skill it extends or a new one it creates. Cross-session state +(the file plan, page map, and a checklist) persists under `${CLAUDE_PLUGIN_DATA}`, +which survives plugin updates. + +## Usage caution — copyright + +This plugin is a neutral tool; **you own the rights decision** for everything you +distill with it. A condensed distillation of a copyrighted book is a +**derivative work** (17 U.S.C. §§ 101, 106) — the copyright holder's exclusive +rights include preparing and distributing derivatives — so distilled outputs +carry **redistribution risk**. Keeping a private distillation for your own study +is a different act from publishing, committing, or sharing one; fair use is a +defense raised after the fact, not a safe harbor you can assume in advance. +Publish, commit, or redistribute a distilled output only once you have satisfied +yourself that doing so is lawful for that book. This is a caution, not legal +advice. + +The distilled output is written into a skill that Claude later **auto-loads as +model context** — so review it before you commit or share it: treat the source +book as untrusted input and confirm the distillation reflects the book rather than +any instructions injected through its text. + +## Requirements + +- A PDF or EPUB you have the right to read. PDF works natively with Claude + Code's Read tool; EPUB requires unzipping and text extraction first. + +## Install + +```shell +/plugin marketplace add melodic-software/claude-code-plugins +/plugin install knowledge@melodic-software +``` + +Migrating from the standalone `book-distill` plugin? Nothing to do — the +marketplace's `renames` map migrates `book-distill@melodic-software` to +`knowledge@melodic-software` automatically on your next session; the skill is now +invoked as `/knowledge:book-distill`. + +One exception: an **in-progress multi-session distillation** stores its resume +checklist under the plugin's `${CLAUDE_PLUGIN_DATA}` directory, which is keyed by +plugin id and is **not** migrated by `renames` (that map rewrites `enabledPlugins` +and `pluginConfigs`, not plugin data). If you have a distillation in flight, copy +your old `book-distill` plugin-data directory to the new `knowledge` one before +resuming so the resume pointer survives. + +## Configuration + +One option, prompted at enable time (or set any time with `/knowledge:setup`): + +| Option | Type | Default | Purpose | +|---|---|---|---| +| `library_dir` | directory | `.` (repo root) | Project-relative directory where the plugin's ingestion pipelines land synthesized artifacts. `book-distill` is unaffected — it writes to the target skill you name at invocation — so today this is a reserved seam. A working-notes or artifacts convention declared in your own project's `CLAUDE.md` or rules takes precedence. | + +`book-distill` itself writes to a **target skill** you name at invocation, so it +needs no configuration to run; `library_dir` is the shared artifact-landing seam +the plugin's ingestion pipelines resolve through. + +## License + +MIT (SPDX-License-Identifier: MIT). See the LICENSE file at the root of the +melodic-software/claude-code-plugins repository. diff --git a/plugins/book-distill/skills/book-distill/SKILL.md b/plugins/knowledge/skills/book-distill/SKILL.md similarity index 100% rename from plugins/book-distill/skills/book-distill/SKILL.md rename to plugins/knowledge/skills/book-distill/SKILL.md diff --git a/plugins/book-distill/skills/book-distill/context/templates.md b/plugins/knowledge/skills/book-distill/context/templates.md similarity index 100% rename from plugins/book-distill/skills/book-distill/context/templates.md rename to plugins/knowledge/skills/book-distill/context/templates.md diff --git a/plugins/book-distill/skills/book-distill/templates/checklist.md b/plugins/knowledge/skills/book-distill/templates/checklist.md similarity index 100% rename from plugins/book-distill/skills/book-distill/templates/checklist.md rename to plugins/knowledge/skills/book-distill/templates/checklist.md diff --git a/plugins/knowledge/skills/setup/SKILL.md b/plugins/knowledge/skills/setup/SKILL.md new file mode 100644 index 000000000..8477c083e --- /dev/null +++ b/plugins/knowledge/skills/setup/SKILL.md @@ -0,0 +1,65 @@ +--- +name: setup +description: "Configure the knowledge plugin for this repository: interview the user, infer a sensible artifact-landing location from the repo layout, and persist the library_dir userConfig option. Use when: 'set up knowledge', 'configure the knowledge plugin', 'knowledge setup', 'where do knowledge artifacts land', or a knowledge skill reports missing or thin config. Re-runnable — safe to invoke again to reconfigure." +argument-hint: "(no arguments — interactive interview)" +user-invocable: true +--- + +## Purpose + +Settle the `library_dir` seam — the project-relative directory where the knowledge plugin's synthesized +artifacts land in the CONSUMING repo — and persist it so the plugin's skills resolve it deterministically +instead of re-inferring every run. `library_dir` is a typed `directory` `userConfig` option (seam 1 of the +extensibility contract): its value lives in `pluginConfigs["knowledge@melodic-software"].options.library_dir` +and substitutes into skill content as `${user_config.library_dir}`. + +Idempotent: re-running reads the current value and offers an update rather than overwriting blind. + +## Task + +Apply the convention-resolution ladder — config present → use it; absent → infer from the repo and persist; +cannot infer → ask and offer to persist; otherwise a safe generic default (repo root `.`). + +1. **Read the current value first, in precedence order.** Look for `library_dir` under + `pluginConfigs["knowledge@melodic-software"].options` in all three scopes and resolve the *effective* + value the way Claude Code does — **Local (`.claude/settings.local.json`) > Project + (`.claude/settings.json`) > User (`~/.claude/settings.json`)**, local winning. Report the effective + value and which scope supplies it; the interview proposes a change against that baseline. If a local + override is present, say so explicitly — step 4 writes the *project* (team) value, which stays shadowed + by the local override until the developer updates or removes it, so a project-scope edit alone will not + change what the plugin actually uses on that machine. Read each scope **narrowly** — query only the + single `pluginConfigs["knowledge@melodic-software"].options.library_dir` key (e.g. with `jq`), never + loading `.claude/settings.local.json` wholesale: that overlay is secret-bearing (API tokens, env + secrets), so do not read or echo unrelated settings content. +2. **Infer a default before asking.** If no value is set, explore the consuming repo for an existing + artifact/notes convention rather than guessing: + - A working-notes or artifacts directory declared in the repo's own `CLAUDE.md`, `AGENTS.md`, or + `.claude/rules` (that declared convention wins — surface it as the recommended value). + - An existing docs or knowledge directory (`docs/`, `knowledge/`, `.claude/notes/`) that synthesized + artifacts would naturally join. + - If nothing is found, the safe default is the repo root `.` (the plugin's declared `userConfig` + default), meaning artifacts land at the top of the consuming repo unless a skill is told otherwise. +3. **Interview — one decision.** Present the inferred value with a recommendation and let the user accept + or edit it. Keep it to the single `library_dir` knob; do not invent further options (Rule of Three — add + a knob only when a real repeated repo-specific need surfaces). +4. **Persist to project scope.** Write the chosen value to the project `.claude/settings.json` at + `pluginConfigs["knowledge@melodic-software"].options.library_dir` so it is tracked and shared with the + team. Create the `pluginConfigs` / options path if absent; do not disturb unrelated keys. The value is + stored verbatim (Claude Code does not normalize a `directory` option to absolute or validate existence), + so store it exactly as the user intends it to resolve relative to their working directory. +5. **Offer the personal overlay.** A per-developer override goes in the local overlay + `.claude/settings.local.json` (same `pluginConfigs` path); recommend the consumer keep + `.claude/settings.local.json` gitignored if it is not already. + +## Output + +An updated project `.claude/settings.json` carrying `library_dir`, plus a one-line summary of the value +written, its scope, and how to re-run this setup to reconfigure. Note in the summary that `library_dir` +governs where the plugin's ingestion pipelines land synthesized artifacts — `/knowledge:book-distill` +is unaffected, since it always writes to the target skill you name at invocation. + +## What this skill does NOT do + +- Run a distillation or ingestion — that is the plugin's pipeline skills (e.g. `/knowledge:book-distill`). +- Write machine-local state — configuration lives in the consumer's tracked settings, never in the plugin + directory or the plugin data directory (`${CLAUDE_PLUGIN_DATA}` is for caches and generated state only). diff --git a/plugins/teach/skills/teach/SKILL.md b/plugins/teach/skills/teach/SKILL.md index 02c75d7c3..c953fb4dc 100644 --- a/plugins/teach/skills/teach/SKILL.md +++ b/plugins/teach/skills/teach/SKILL.md @@ -10,7 +10,7 @@ disable-model-invocation: true Teach a user interactively across multiple sessions — not by lecturing, but by coaching through the Knowledge-Skills-Wisdom progression grounded in the user's real goals. Maintains persistent learning state so each session builds on prior understanding. -**Use when:** user asks to learn across sessions (`teach me`, `study session`, `help me learn`, `onboard me to`). **Skip when:** one-off inline question (answer directly); task-context codebase investigation (use the project's own code-exploration tooling); extracting book knowledge to a reference file (`/book-distill:book-distill` when installed). +**Use when:** user asks to learn across sessions (`teach me`, `study session`, `help me learn`, `onboard me to`). **Skip when:** one-off inline question (answer directly); task-context codebase investigation (use the project's own code-exploration tooling); extracting book knowledge to a reference file (`/knowledge:book-distill` when installed). Two modes share pedagogy but differ in source material: @@ -206,6 +206,6 @@ Learning artifacts persist for months; durable teaching content (references, glo ## What This Skill Does NOT Do - **Does not write production code** — teaches understanding, not implementation. Use the project's own implementation workflow for code changes -- **Does not replace `/book-distill:book-distill`** — that extracts book knowledge into skill reference files; `/teach:teach` delivers knowledge interactively to the user +- **Does not replace `/knowledge:book-distill`** — that extracts book knowledge into skill reference files; `/teach:teach` delivers knowledge interactively to the user - **Does not do task-context codebase investigation** — that's for the project's code-exploration tooling; `/teach:teach codebase` is structured learning for understanding - **Does not auto-invoke** — `disable-model-invocation: true`. The user initiates learning sessions