firelive/agent-skills

Sources / Upstream

• Upstream: https://github.com/kangarooking/cangjie-skill
• License: MIT
• Vendored into: .agents/skills/book-to-skill-distill/SKILL.md for Moi/Codex shared install
• Note: Full pipeline also needs methodology/ extractors/ from upstream repo.

This file may be a vendored copy or a thin pointer. Prefer installing/cloning the upstream repo when it ships assets, scripts, or AGPL obligations.

cangjie-skill — Distill a book into executable skills

Mission

Deconstruct the methodology embedded in a book into atomic capabilities that an agent can invoke in real-world scenarios, compiling them into the appropriate number of skills based on user intent, enabling the reader to truly apply them.

Terminology Convention: In this document and all files in methodology/ and extractors/, "book" refers broadly to any long-form content being distilled — books, long-video transcripts, podcast transcripts, courses, interviews, long articles, or reference collections.

Boundaries:

• ✅ Does: Distillation of methodologies / decision frameworks / operational workflows / calculation rules / troubleshooting / checklists / principles, with underlying concepts serving as supporting references
• ❌ Does not: Book summaries / reading notes / role-playing as the author (for the latter, use nuwa-skill)

Core Methodology: RIA-TV++ (v2.5 Bundle Edition)

A pipeline of five stages + parallel extraction + triple verification + promotion gate + darwin compatibility testing. See methodology/00-overview.md.

Stage 0:   Adler whole-book understanding     → BOOK_OVERVIEW.md
Stage 1:   5 agents parallel extraction        → Candidate methodology unit pool
Stage 1.5: Triple verification screening       → Passed units (user light confirmation)
Stage 1.6: Standalone Skill promotion gate     → promoted / router destination
Stage 2:   RIA++ capability card construction  → .cangjie/capabilities/cards/<slug>.md
Stage 3:   Zettelkasten linking                → verified.yaml also_read + GLOSSARY
Stage 4:   Pressure testing (darwin compatibility) → Evaluation cases + remediation elimination
Stage 5:   Compilation and delivery            → cangjie.py compile (single/pack) + DIGEST.md + installation

Key v2.5 Change (ADR-002): Stages 2–4 no longer directly write each unit as its own final Skill directory; instead, they produce a single Capability Bundle (books/<slug>/.cangjie/capabilities/verified.yaml + cards/*.md). Both single and pack are deterministically compiled from this same Bundle by scripts/cangjie.py compile, both referencing the same set of stable capability_ids. The old one-to-one output is still supported (legacy-pack, see docs/migrations/2026-08-25-v2.0-to-v2.1.md).

When to Call This Skill

The user says something like:

• "Help me distill 'Poor Charlie's Almanack'"
• "Distill 'Mao Zedong's Selected Works' into skills"
• "Distill this Bilibili video/podcast/course into skills"
• "distill this book into skills: "
• "I want to turn the methodology from this book into usable skills"

Input Requirements

Before starting, must confirm the following with the user:

Script Dependency: The deterministic scripts (scripts/) require Python 3.10+ and PyYAML (python3 -m pip install pyyaml). If PyYAML is missing, first run python3 scripts/cangjie.py doctor for a self-check; it will provide installation instructions.

1. Content text source: Path to PDF / EPUB / TXT / subtitle file / transcript, or accessible plain text. Do not distill "from memory" without text — if text is unavailable, stop and ask the user. (For videos/podcasts, it is recommended to first obtain transcript text using tools like video-downloader.)
2. Content metadata: For a book: "book title + author + publication year"; for a video/podcast/course: "title + author (creator/host/speaker) + publication date". Used for directory naming and auditing.
3. Purpose of use (determines recommended output mode): Learning/referencing the book → prefer single; integrating into daily workflows, cross-book combination → prefer pack. When uncertain, follow the single-first principle and recommend single.
4. First trial?: If the user is using cangjie-skill for the first time, recommend distilling 1 piece of content first to verify the process before batch processing.

Field Mapping for Non-Book Content: For chapter-like fields, use timestamps or segment numbers for videos, episode numbers for podcasts, and lecture numbers for courses — ensure traceability.

Output Structure

books/<book-slug>/
├── PIPELINE_STATE.md          # Pipeline status: current stage + progress (for checkpoint restart)
├── BOOK_OVERVIEW.md           # Stage 0 output: theme/structure/terms/critique
├── verified.md                # Stage 1.5 output: units that passed triple verification + rationale
├── coverage-audit.md          # Original book key tasks → candidates → adjudication → actual delivery destination
├── references.md              # Reference content with evidence but not executed, plus delivery mapping
├── needs-review.md            # Source/condition/test gaps; not compiled as active capabilities
├── GLOSSARY.md                # Stage 3 output: shared term dictionary for the whole book
├── DIGEST.md                  # Stage 5 output: reader-oriented summary article
├── candidates/                # Stage 1 output: raw candidate pool (for auditing)
├── rejected/                  # Stage 1.5 eliminated units + reason (for auditing)
└── .cangjie/                  # v2.5 sidecar layer (compilation source of truth + runtime records)
    ├── capabilities/
    │   ├── verified.yaml      # Capability Bundle (sole compilation source of truth, capability-bundle.schema.json)
    │   ├── cards/<slug>.md    # RIA capability cards (R/I/A1/A2/E/B, Stage 2 output)
    │   ├── resources/         # UTF-8 scripts, CSV/JSON/Markdown templates explicitly declared by capabilities (optional)
    │   ├── destinations.json  # Promotion/router destination mapping (Stage 1.6 output)
    │   └── book/{overview.md,glossary.md}
    ├── runs/<run-id>/         # Decision reports and validation logs for each compilation/update
    └── snapshots/             # Pre-release snapshots (for rollback)

The final deliverables are compiled from the Bundle by scripts/cangjie.py compile (--output single yields 1 entry point + capability cards; --output pack yields 1 source router entry + a small number of promoted Skills).

Execution Flow (Strict Order)

Checkpoint Restart: Before starting, check if books/<slug>/PIPELINE_STATE.md exists. If it does, read it and resume from the recorded stage; do not restart from scratch. Update this file after completing each stage.

Stage 0 — Whole-Book Understanding

1. Read the user-provided book text. For large files, read in chunks.
2. Execute the Adler four steps (Structure / Interpretation / Critique / Application) as described in methodology/01-stage0-adler.md.
3. Populate the template from templates/BOOK_OVERVIEW.md.template and write to books/<slug>/BOOK_OVERVIEW.md.
4. Present the output to the user for confirmation: "Is my skeleton understanding correct? Are there any directions you'd like me to emphasize?" Proceed to Stage 1 only after receiving confirmation.

Stage 1 — Parallel Extraction by 5 Sub-Agents

In parallel, spawn 5 Task sub-agents (using Agent tools, initiate all 5 in a single call):

Sub-agent	Prompt read	Context strategy	Output
Framework extractor	extractors/framework-extractor.md	Full scan (covering both cross-chapter and self-contained mechanisms)	Decision frameworks / mental models / workflows / troubleshooting
Principle extractor	extractors/principle-extractor.md	Full scan (including formulas, tables, footnotes)	Principles / checklists / rules / calculation formulas
Case extractor	extractors/case-extractor.md	Retrieval-based chunking (local hit pattern)	Examples from the book, paraphrased cases, practice problems, with type annotation
Counter-example extractor	extractors/counter-example-extractor.md	Retrieval-based chunking (local hit pattern)	Failure modes warned about in the book
Glossary extractor	extractors/glossary-extractor.md	Retrieval-based chunking + script pre-filtering	Dictionary of key concepts

Each sub-agent independently judges and outputs to books/<slug>/candidates/<type>.md.

• Long text: Content exceeding a single sub-agent's context is handled according to the chunking strategy in methodology/02-stage1-parallel-extract.md; if a content index (.cangjie/index/) already exists, retrieval-based extractors fetch relevant chunks based on the index.
• Coverage hard gate: Cross-reference the full-scan candidates with the original book's key task list from Stage 0; do not only check previously passed items. Every important task must have a candidate and a clear destination; if there are unexplained gaps, re-read / fall back to full scan, and do not falsely claim zero omissions.
• Degradation plan: If the current environment does not support parallel sub-agents, execute the same 5 extractor prompts serially, keeping the same output format.

Stage 1.5 — Triple Verification Screening (Knowledge Verification)

Read methodology/03-stage1.5-triple-verify.md, and for each candidate unit perform:

• V1 Source sufficiency: Can the locatable original text adequately support the described practice within a defined scope? A complete mechanism explained in one pass also qualifies.
• V2 Executability: Can a legitimate new input be used to complete the task and verify the result? Cross-domain extrapolation is not required.
• V3 Task gain: Does it reduce omission, standardize criteria, or stabilize delivery? The author's originality is not required.

Route to verified / reference / needs_review / rejected, recording the basis and gaps; reference content must be mapped to the actual delivery overview/glossary; not all failed items are eliminated. Update coverage-audit.md.

User light confirmation ★: Present the four categories (verified candidates, references, needs review, eliminated) and important gaps before entering Stage 1.6; confirmation does not replace source verification.

Stage 1.6 — Standalone Skill Promotion Gate (Productization Verification)

Read methodology/03b-stage1.6-promotion-gate.md. Passing knowledge verification does not guarantee it deserves to be a standalone Skill. Evaluate each unit against five criteria (independent intent / independent contract / independent operation / independent reuse / independent evaluation; the first 3 must be met; at least 1 of the last 2). Write the destination into the Bundle's promotion.destination (promoted / router). Units that do not promote are not eliminated; they remain as capability cards accessible via the source router entry. The soft budget for entry points defaults to 8 (including 1 source router entry).

Stage 2 — RIA++ Capability Card Construction

For each passed unit, construct the six-section capability card (R / I / A1 / A2 / E / B) following methodology/04-stage2-ria-plus.md:

• Write the card body to books/<slug>/.cangjie/capabilities/cards/<slug>.md (without frontmatter; frontmatter data is recorded in the Bundle);
• Register the capability in verified.yaml: stable capability_id, intents, keywords, one_liner, importance (with basis), frontmatter.description (abbreviated version of A2).
• Distinguish between original book cases and explicitly marked synthetic exercises in A1; E must clearly specify input, output, branching, and completion criteria. When necessary, explicitly declare supporting text resources via resources, following the Stage 2 instructions.

Stage 3 — Zettelkasten Linking

Follow methodology/05-stage3-zettelkasten.md:

1. Identify cross-references between capabilities, write them into each capability's also_read in the Bundle, and backfill A2's "Differentiation from adjacent capabilities"
2. Organize candidates/glossary.md into books/<slug>/GLOSSARY.md, and copy to .cangjie/capabilities/book/glossary.md
3. The INDEX/router table is generated by the compiler from the Bundle; no manual writing required
4. Merge content from references.md that needs to be retained into the Bundle's book/overview.md or book/glossary.md, recording the actual path in the coverage audit; do not disguise needs-review content as executable methods

Stage 4 — Pressure Testing (darwin Compatibility)

Follow methodology/06-stage4-pressure-test.md. Promoted capabilities test triggering; router capabilities test reachability; both types must actually complete representative tasks and verify the output, not replace "doing it right" with "will call it." Missing outputs count toward the evaluation denominator; incomplete steps cannot claim passing. Those that fail must redo Stage 2.

Stage 5 — Compilation and Delivery

Follow methodology/07-stage5-deliver.md:

1. Generate books/<slug>/DIGEST.md — a reader-oriented summary article
2. Run python3 scripts/cangjie.py compile --bundle books/<slug>/.cangjie/capabilities --out <target directory> --output auto, present the decision report to the user for light confirmation (with recommendations / change to single / change to pack)
3. Ask the user for the installation location, then copy or symlink the compilation artifacts there
4. Inform the user: "Completed. It's ready to be fed to darwin-skill for automatic evolution."

Quality Red Lines (Violation Blocks Output)

1. Every capability must pass all three verifications
2. Every capability card must have complete six sections: R / I / A1 / A2 / E / B; if A1 has no original book case, annotate honestly; synthetic exercises must not masquerade as book facts
3. Original text quotes ≤ 150 characters per paragraph (English ≤ 100 words per paragraph)
4. Each active capability must have exactly one destination in destinations.json (promoted_to or served_by); non-promoted capabilities must be reachable via the source router entry
5. Promoted Skills' description must clearly specify trigger conditions, and serve as positive/negative examples for the source router entry
6. Compilation artifacts must pass scripts/validate_skill_pack.py (format/relative references/frontmatter 100%)
7. Output directories are read-only: if local manual edits are detected, do not silently overwrite (compiler enforces a three-way choice)
8. Key task coverage must have traceable destinations; actual output evaluation and source verification are recorded separately. If important gaps exist, only deliver a draft with explicitly scoped caveats; do not claim full passing

Ecosystem Position with nuwa-skill / darwin-skill

• nuwa-skill: Distills a person (way of thinking / expression DNA)
• cangjie-skill (this skill): Distills a book (methodology / frameworks / principles)
• darwin-skill: Evolves any skill

They interlock: The evaluation cases output by this skill follow the darwin-skill format, so the produced skills can directly hook into darwin for automatic evolution.

Calling Conventions

• Always pilot 1 book first — unless the user explicitly says "batch"
• Proactively report progress between stages — do not silently run to completion and dump results
• Don't distill from memory — if no text is available, stop and ask
• Preserve audit trail — always keep candidates/ and rejected/
• Resumable at any point — update PIPELINE_STATE.md after each stage; resume from the state file after interruption
• Output strategy persistence — update/repair defaults to the original output mode; do not silently change artifact form due to new material