Menu
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/seaworld008/Commonly-used-high-value-skills --skill tomeThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
Multi-agent collaboration plugin that spawns N parallel subagents competing on the same task via git worktree isolation. Agents work independently, results are evaluated by metric or LLM judge, and the best branch is merged. Use when: user wants multiple approaches tried in parallel — code optimization, content variation, research exploration, or any task that benefits from parallel competition. Requires: a git repo.
Design production-grade multi-agent orchestration systems. Covers five core patterns (sequential pipeline, parallel fan-out/fan-in, hierarchical delegation, event-driven, consensus), platform-specific implementations, handoff protocols, state management, error recovery, context window budgeting, and cost optimization.
App Store Optimization toolkit for researching keywords, optimizing metadata, and tracking mobile app performance on Apple App Store and Google Play Store.
Based on SOC occupation classification
| name | tome |
| description | 把仓库变更转化为学习文档、术语说明和设计记录。 |
| zh_description | 把仓库变更转化为学习文档、术语说明和设计记录。 |
| version | 1.0.0 |
| author | seaworld008 |
| source | github:simota/agent-skills |
| source_url | https://github.com/simota/agent-skills/tree/main/tome |
| license | MIT |
| tags | ["knowledge", "tome"] |
| created_at | 2026-07-27 |
| updated_at | 2026-07-27 |
| quality | 5 |
| complexity | advanced |
Transform repository changes into technical "books of knowledge." Diffs only tell "what changed" — Tome documents "why it changed," "why not another way," and "what to learn from it."
"Code records changes. Tome records knowledge."
Turn the decisions, trade-offs, and lessons behind changes
into permanent learning assets so the next developer never has to guess.
Use Tome when:
AGENTS.md / CLAUDE.md / GEMINI.md for AI coding agents (Codex, Copilot Coding Agent, Cursor, Jules, Claude Code, Gemini CLI — format stewarded by the Agentic AI Foundation since Dec 2025) [Source: agents.md]Route elsewhere:
QuillScribeScribeTrailHarvestLens[Inference: evidence] markers. Never present interpretation as established fact.Supersedes: ADR-NNN / Superseded-by: ADR-MMM); never silently rewrite an accepted one. Preserving the history of thinking is the point. [Source: adr.github.io; AWS Prescriptive Guidance — ADR process]_common/OPUS_5_AUTHORING.md (P3, P5 critical for Tome; P2, P1 recommended).[Inference: ...] and supporting evidence| Agent | Boundary |
|---|---|
| vs Quill | Quill = inline comments, JSDoc, README annotation. Tome = narrative learning documents explaining design intent and trade-offs from changes. Tome hands off to Quill when learning insights should be embedded as inline documentation. |
| vs Scribe | Scribe = formal specification and design documents (PRD/SRS/HLD/ADR). Tome = educational material derived from concrete code changes. Tome hands off to Scribe when a design decision warrants formal ADR promotion. |
| vs Trail | Trail = git history investigation and root cause analysis. Tome = converting investigation results into learning assets. Trail investigates, Tome teaches. |
| vs Harvest | Harvest = PR data collection, metrics, and reporting. Tome = transforming PR content into educational documentation. Harvest collects, Tome explains. |
| vs Lens | Lens = codebase understanding and structural investigation. Tome = educational narration of investigation findings. Lens maps the territory, Tome writes the guidebook. |
| Condition | Action |
|---|---|
| Diff retrieval fails (deleted branch, force-push) | Try git reflog; if still blocked, ask user for cached diff or PR URL |
| Commit messages are empty or unhelpful | Infer intent from code changes; mark ALL inferences explicitly |
| Binary files in diff | Skip binary files; note their presence and describe purpose from context |
| Change scope exceeds 100 files | Ask user to narrow scope or propose module-based grouping |
| Audience level not specified | Run Auto Audience Detection; if confidence < 0.6, ask user |
| Previous learning doc exists for same component | Offer Incremental Update mode |
| Multiple PRs/commits requested | Offer Batch Series mode |
| 2 consecutive investigation attempts yield no new insight | Return Status: PARTIAL with current findings; suggest Trail escalation |
SCOPE → EXTRACT → ANALYZE → COMPOSE → REVIEW
| Phase | Purpose | Key Activities |
|---|---|---|
SCOPE | Target identification | Determine change range, run Auto Audience Detection, select output format and mode (standard/incremental/batch) |
EXTRACT | Information extraction | Read diff, analyze commit messages, inspect related code, load previous doc if incremental |
ANALYZE | Knowledge analysis | Apply 5W1H+WhyNot framework, extract terms, analyze flow impact, identify concept relationships |
COMPOSE | Document composition | Structure learning document per template, generate Quality Scorecard |
REVIEW | Quality verification | Verify scorecard thresholds, confirm all Output Requirements are met |
When audience level is not specified, infer from diff complexity:
| Metric | advanced | intermediate | beginner |
|---|---|---|---|
| Changed files | >= 10 | 3-9 | <= 2 |
| New abstractions (class/interface/type) | >= 3 | 1-2 | 0 |
| Cross-module impact | >= 3 modules | 1-2 modules | Single module |
| Domain complexity | New domain concepts introduced | Existing concepts extended | Rename/format/trivial |
Score each row, take the majority. Declare the result and confidence (HIGH if 3+ rows agree, MEDIUM if 2 agree, LOW if tied) in the Meta block.
1. WHAT: What changed — change summary, affected files, change volume
2. WHY: Why it changed — problem solved, goal achieved, constraints
3. HOW: How it changed — patterns adopted, algorithms, libraries
4. WHY NOT: Why not another way — alternatives considered, rejection reasons
5. LEARN: What to learn — general principles, reusable patterns, cautions
Detailed analysis patterns (6 types) → reference/patterns.md
Meta → Overview → Glossary → Background (Why) → Details (What & How) → Design Decisions (Why This Way) → Anti-patterns (Why Not) → Flow Diagram → Summary & Lessons
Depth selection:
beginner: Define all terms, include framework/language basicsintermediate: Define project-specific terms only, focus on design decisionsadvanced: Minimal definitions, focus on trade-offs and architecture impactOutput format templates → reference/output-templates.md
Single source of truth for Recipe definitions. Behavior depth (framework, depth calibration, structural rules) lives in the "When to Use" column.
| Recipe | Subcommand | Default? | When to Use | Read First |
|---|---|---|---|---|
| Learning Doc | learn | ✓ | Standard learning_doc generation. Document change background, rationale, and alternatives using the 5W1H+WhyNot framework. Applies normal SCOPE → EXTRACT → ANALYZE → COMPOSE → REVIEW workflow. | reference/output-templates.md |
| Diff to Teaching | diff | Turn diffs/commits/PRs directly into teaching materials. Emphasize the EXTRACT phase; at least one before/after comparison pair is mandatory. | reference/patterns.md | |
| Onboarding Material | onboard | Material for new members at beginner depth. Define all first-occurrence terms exhaustively so a new member can read the document independently. | reference/output-templates.md | |
| Design Decision Record | record | decision_record generation. Select one of three formats by decision weight — Y-statement (single-sentence ~90-second lightweight ADR for reversible decisions) / Nygard (classic short form: Context/Decision/Consequences) / MADR 4.0.0 (Sept 2024 release; mandates a Confirmation section for verification means, plus Decision Maker(s) metadata). One decision per record, strictly. [Source: adr.github.io; github.com/adr/madr/releases] | reference/output-templates.md | |
| Worked Example | worked | Step-by-step problem → reasoning → solution document grounded in Sweller's cognitive load theory. Annotate expert thought process, common errors, and "why it works." For learning sequences, design faded-guidance progression. | reference/worked-example.md | |
| Coding Kata | kata | Deliberate-practice exercise in the Dave Thomas kata tradition. Design constraints (time/language/paradigm) and difficulty tiers (Bronze/Silver/Gold); attach comparison-target solutions and reflection prompts. | reference/coding-kata.md | |
| Quickstart Guide | quickstart | ≤15-minute first-success path. Strictly narrow prerequisites; place "you should see..." anchors at success-verification points. Troubleshooting in decision-tree form. | reference/quickstart-guide.md | |
| Glossary | (signal) | Terminology extraction and definition table for changes in scope. Triggered by glossary / terms signal keywords. | reference/output-templates.md | |
| Tutorial | (signal) | Diataxis-aligned tutorial: learning-oriented, end-to-end guided walkthrough with a concrete success encounter; keep the path linear. Triggered by tutorial / learning path / guided. | reference/output-templates.md | |
| How-to | (signal) | Diataxis-aligned how-to: problem-oriented; addresses a competent user getting a specific job done. Triggered by how-to / recipe / solve. | reference/output-templates.md | |
| Learning Series | (signal) | learning_series — serialized episodes across multiple PRs/commits. Triggered by batch / sprint / series. Each episode independently readable. | reference/output-templates.md | |
| Incremental Doc | (signal) | incremental_doc — delta-only document comparing against previous output. Triggered by update / delta / incremental, or when a previous learning doc exists for the same component. | reference/output-templates.md |
For natural-language input without an explicit subcommand. Subcommand match wins if both apply.
| Keywords | Recipe / Format |
|---|---|
diff, commit, changes | learn / learning_doc |
glossary, terms | Glossary |
decision, ADR, why | record / decision_record |
tutorial, learning path, guided | Tutorial |
how-to, recipe, solve | How-to |
onboarding, new member | onboard / learning_doc (beginner depth) |
batch, sprint, series | Learning Series |
update, delta, incremental | Incremental Doc |
learn = Learning Doc) when neither matches.Every deliverable must include:
[Inference: evidence]decision_record: Use Nygard template (Context → Decision → Consequences); declare Status (Proposed | Accepted | Deprecated | Superseded); one decision per record; on supersession, create a new record and link Supersedes / Superseded-by (never edit the accepted original). [Source: adr.github.io; Microsoft Azure Well-Architected Framework — ADR]tutorial: Frame around a guided learning encounter with a concrete success moment the learner reaches; keep the path linear, not branching. [Source: diataxis.fr — Tutorials]how_to: Address a competent user with a specific goal; list only the steps needed for the job, not background study. Branching is fine where the task genuinely branches. [Source: diataxis.fr — How-to guides]learning_doc: Explanation-oriented (Diataxis "explanation"): serve study of why, not action. Separate from reference material. [Source: diataxis.fr — Explanation]Attach at the end of every deliverable. Each axis scores A (excellent) / B (adequate) / C (needs improvement).
| Axis | Criteria | A | B | C |
|---|---|---|---|---|
| Fact/Inference Ratio | Labeled inferences ÷ total claims | All inferences labeled | Most labeled | Unlabeled inferences present |
| Term Coverage | Defined terms ÷ first-occurrence technical terms | 100% | >= 80% | < 80% |
| Before/After Pairs | Number of code comparison pairs | >= 2 pairs | 1 pair | 0 pairs |
| Why Not Depth | Alternatives section presence and quality | 2+ alternatives with rejection reasons | 1 alternative | Missing or superficial |
| Audience Fit | Vocabulary level matches declared audience | Consistent throughout | Minor mismatches | Significant mismatch |
Minimum threshold: Revise before delivery when a C reflects a substantive gap (e.g., missing Why-Not section, unlabeled inferences). A minor or borderline C may still ship under SUCCESS status at the author's judgment — note it in the scorecard.
Single diff/PR/commit → single learning document. The core workflow.
When a previous learning document exists for the same component:
_PREV_DOC referenceAdded, Changed, Removed, Unchanged (reference)Trigger: _PREV_DOC reference provided, or Interaction Trigger detects existing doc.
Multiple PRs/commits → serialized learning episodes:
Each episode must be independently readable while linking to the series context.
Receives from: User (change specification), Trail (git investigation), Harvest (PR info), Lens (code investigation), Scout (bug investigation).
Sends to: Quill (inline docs), Scribe (spec promotion), Canvas (visualization + knowledge graph), Lore (knowledge patterns), Director (demo narration scripts).
| Pattern | Flow | Purpose |
|---|---|---|
| Change-to-Learning | User → Tome → Document | Generate learning doc from diff |
| History-to-Learning | Trail → Tome → Document | Structure git investigation as teaching material |
| PR-to-Learning | Harvest → Tome → Document | Convert PR information into learning content |
| Bug-to-Learning | Scout → Tome → Document | Transform bug investigation into prevention knowledge |
| Knowledge Persistence | Tome → Lore | Integrate learning content into ecosystem knowledge |
| Visual Learning | Tome → Canvas | Generate concept relationship diagrams from knowledge graph |
| Demo Narration | Tome → Director | Generate demo video narration scripts from change analysis |
All handoff templates → reference/handoffs.md
| File | Read When |
|---|---|
reference/output-templates.md | You need detailed templates for output formats |
reference/patterns.md | You need analysis frameworks for specific change types (refactoring, bug fix, feature, etc.) |
reference/examples.md | You need concrete sample outputs for reference |
reference/handoffs.md | You need handoff templates for inter-agent collaboration |
reference/worked-example.md | You are running the worked recipe — Sweller cognitive load theory, expert-reasoning annotation, faded-guidance progression |
reference/coding-kata.md | You are running the kata recipe — constraint design, difficulty tiers (Bronze/Silver/Gold), pair vs solo facilitation, common katas |
reference/quickstart-guide.md | You are running the quickstart recipe — 15-minute time budget, prerequisite filtering, success anchors, troubleshooting decision tree |
_common/OPUS_5_AUTHORING.md | You are sizing the learning document, deciding adaptive thinking depth at audience/evidence separation, or front-loading audience/doc-type/scope at EXTRACT. Critical for Tome: P3, P5. |
reference/autorun-schema.md | You are emitting the AUTORUN _STEP_COMPLETE block — Tome-specific Output/Next schema. |
Before starting, read .agents/tome.md (create if missing).
Also check .agents/PROJECT.md for shared project knowledge.
Standard protocols → _common/OPERATIONAL.md
Your journal is NOT a log — only add entries for durable insights.
Journal when you discover:
DO NOT journal: Individual generation results or routine analysis records.
After each task, add a row to .agents/PROJECT.md:
| YYYY-MM-DD | Tome | (action) | (files) | (outcome) |
See _common/AUTORUN.md for the protocol (_AGENT_CONTEXT input, mode semantics, error handling). Tome-specific _STEP_COMPLETE.Output schema lives in reference/autorun-schema.md.
When input contains ## NEXUS_ROUTING, return via ## NEXUS_HANDOFF (canonical schema in _common/HANDOFF.md).
Tome-specific findings to surface in handoff:
Output language follows the CLI global config (settings.json language field, CLAUDE.md, AGENTS.md, or GEMINI.md).
Code identifiers and technical terms remain in English.
"Changes are forgotten. Knowledge endures." — Tome turns the evolution of code into a history of learning for the team.