From 8b0fca4a4da7c6c99d494febdd38c69451328273 Mon Sep 17 00:00:00 2001 From: Alireza Rezvani Date: Tue, 25 Aug 2026 22:57:41 +0000 Subject: [PATCH] fix(book-to-skill): correct emitter docstring drift and the resident-core figure Addresses both review findings on #993. 1. skill_plugin_emitter.py's module docstring still described the behaviour this PR removed. Its tree diagram called plugin.json the "manifest with ./skills/ + attribution", and the rights-gate paragraph said cleared_for_distribution is recorded "in the manifest" -- both now the sidecar. A docstring asserting the opposite of its own file's point is worse than no docstring, and it is what `--help` readers see. Also corrects a third instance the review did not name but which shares the root cause: the tree diagram never listed authoring-notes.json at all, even though this PR's fix is what creates it. Added, with the issue #954 reason stated inline so the next reader knows why provenance cannot live in the manifest. 2. CLAUDE.md said the resident core is 2,066 tokens while, twelve lines later, the same file said 2,101. 2,066 predates the worked invocation block added for write-a-skill checklist item 5; token_budget_estimator.py reports 2,101 on the current tree, matching CHANGELOG.md and the PR body. CLAUDE.md was the only stale copy and it contradicted itself. Docstring-only and prose-only; no behaviour change. Verified the emitter still emits both plugin.json and authoring-notes.json via --sample after the edit. Gates: compileall, check_plugin_json --all, check_paths, check_frontmatter, check_dual_publish, check_model_freshness, smoke_scripts (696/696), derive_counters --check, book_skill_validator --strict. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UySnyf5upm4y8xhYA3w6yw --- CLAUDE.md | 2 +- .../skills/book-to-skill/scripts/skill_plugin_emitter.py | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5a6893ee..3f87018c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -247,7 +247,7 @@ Joshua Achiam). Source obtained by cloning `openai/spinningup` and compiling its tree — 38 files, ~37k words, ~49K tokens — through the full pipeline: `extract_document.py --mode technical` → analysis → 20 chapter files → glossary / patterns / cheatsheet → master `SKILL.md` → `book_skill_validator.py` → `skill_plugin_emitter.py`. Validator passes clean **in `--strict` mode**; every file is inside budget -(resident core 2,066 / 4,000 tokens; 20 chapters averaging ~1,256 tokens each, loaded on demand). +(resident core 2,101 / 4,000 tokens; 20 chapters averaging ~1,256 tokens each, loaded on demand). - **Rights basis is `open-license`, not fair use.** The emitter's Step-11 gate refuses a shareable package without one; MIT permits derivative distribution. Upstream's notice is reproduced in full in the plugin's diff --git a/engineering/book-to-skill/skills/book-to-skill/scripts/skill_plugin_emitter.py b/engineering/book-to-skill/skills/book-to-skill/scripts/skill_plugin_emitter.py index bc11b54b..05dd7580 100644 --- a/engineering/book-to-skill/skills/book-to-skill/scripts/skill_plugin_emitter.py +++ b/engineering/book-to-skill/skills/book-to-skill/scripts/skill_plugin_emitter.py @@ -10,7 +10,8 @@ This tool closes that gap. Point it at a generated book skill and it emits the plugin package this repo's conventions require: // - ├── .claude-plugin/plugin.json manifest with `./skills/` + attribution + ├── .claude-plugin/plugin.json manifest, spec fields only (no `source`) + ├── .claude-plugin/authoring-notes.json provenance the manifest may not carry ├── README.md what the skill knows and where it came from ├── agents/cs-.md persona that answers from the book ├── commands/cs-.md /cs: entry point @@ -24,7 +25,8 @@ Rights gate: a book skill built from a copyrighted work is personal study notes. `--distribution shareable` therefore refuses to emit unless `--rights` names a basis that permits redistribution. `--distribution local` (the default) emits with a notice and records `source.cleared_for_distribution: false` -in the manifest. +in `authoring-notes.json`. Provenance never goes in `plugin.json`: Claude Code +rejects the whole manifest on any unrecognized key (issue #954). Exit codes: 0 package emitted (or --dry-run / --sample completed)