Claude Skill

paper-glossary

Use when building reusable Obsidian glossary notes from an existing paper source manifest, optionally with a raw-sections override, especially when a reader needs a reviewed shortlist before glossary notes and article links are changed.

LLM Mart · 0 points · 19 views 1 listing impressions 0 install-command copies
Download 917Dhj-DeepPaperNote-skills_paper-glossary-fdcb620.zip · 87 KB

Install

skills CLI npx skills add https://github.com/917Dhj/DeepPaperNote/tree/main/skills/paper-glossary
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 917dhj-deeppapernote@llmmart
Git git clone https://github.com/917Dhj/DeepPaperNote.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole 917dhj/deeppapernote collection as a plugin from our marketplace. Git is the plain clone.

README

Paper Glossary

paper-glossary builds reusable Obsidian glossary notes from *_source_manifest.json and *_raw_sections.jsonl. It remains self-contained and does not call a paper-reading workflow.

One-Time Device Setup

Each person configures one term directory once per device. The directory must be inside an Obsidian vault: its nearest vault ancestor must contain .obsidian. The local configuration is ~/.paper-glossary/config.json; it stores an absolute resolved vault root and the terms subdirectory, not a repository setting. Relative and Windows drive-relative vault roots are rejected. Later runs reuse it.

Setup may create ~/.paper-glossary/config.json; before selection, no glossary notes or article Markdown are written. Run commands from the repository root and replace each quoted <vault> placeholder with the real vault path.

Windows PowerShell

py -3.12 skills\paper-glossary\scripts\configure_glossary.py --terms-dir '<vault>\Glossary'
py -3.12 skills\paper-glossary\scripts\configure_glossary.py --show
py -3.12 skills\paper-glossary\scripts\configure_glossary.py --reset
py -3.12 skills\paper-glossary\scripts\configure_glossary.py --validate-article '<vault>\Papers\example.md'
py -3.12 -m pytest -q skills\paper-glossary\tests --basetemp .pytest-tmp-paper-glossary

macOS / Linux Bash

python3 skills/paper-glossary/scripts/configure_glossary.py --terms-dir '<vault>/Glossary'
python3 skills/paper-glossary/scripts/configure_glossary.py --show
python3 skills/paper-glossary/scripts/configure_glossary.py --reset
python3 skills/paper-glossary/scripts/configure_glossary.py --validate-article '<vault>/Papers/example.md'
python3 -m pytest -q skills/paper-glossary/tests --basetemp .pytest-tmp-paper-glossary

When article links are requested, provide the article Markdown path explicitly. It must be a .md file in the same Obsidian vault as the configured term directory; the skill never guesses an article from the paper source artifacts.

--source-manifest is required for proposal, review recording, and triage. --raw-sections is an optional override for the manifest's raw_sections_path, not a standalone replacement. The artifact workflow is:

  1. Run plan_glossary.py --propose ... --output proposal.json.
  2. Perform one semantic review, then record its exact ordered subset with --review-proposal proposal.json --reviewed-terms ... --output reviewed.json. If this produces an empty reviewed shortlist, report no_candidates and stop without displaying an empty selector.
  3. Display the complete reviewed shortlist as numbers and wait. Resolve number responses or 全部写入 to exact names outside the CLI.
  4. Run triage with --reviewed-shortlist reviewed.json --terms ...; --terms alone is rejected.
  5. Pass triage to inventory, inventory to the writer at the configured glossary directory (use --config-path only to select that device-local configuration), and successful writer results to the linker when an article was requested.

For inventory, writer, and linker, always pass the current --source-manifest, optional --raw-sections, and saved --reviewed-shortlist. Inventory reads the saved --triage as its input; writer and linker also require that same saved --triage and enforce exact ordered term and surface_forms equality with it. These post-triage CLIs recompute the current proposal/review chain before writing. When the writer receives --article, paper_link is derived from the resolved article Markdown stem. A glossary-only writer invocation omits --article and derives paper_link from the validated manifest paper_id; do not run the linker for that branch because it rejects a writer artifact with no bound article path.

Proposal candidates carry ordered paper-grounded surface_forms plus SHA-256 provenance and the bounded candidate/summary material needed to recompute it. Inventory and writer both fail closed unless proposal, review, and selection digests recompute from one matching paper/source chain and the exact ordered forms. Review, triage, inventory, and writer results preserve those forms; model-authored note aliases are metadata and are not article-match forms. Writer output also preserves triage_sha256, validated provenance, and context and binds the triage identity plus exact ordered mappings with mappings_sha256; the linker recomputes that digest and validates every note path, stem, and grounded form. See SKILL.md and references/file-contract.md for exact article and glossary-only invocations and JSON contracts.

Skill manifest

Paper Glossary

Build shared glossary notes from *_source_manifest.json. --source-manifest is always required; --raw-sections only overrides its raw_sections_path with an explicit *_raw_sections.jsonl. This skill never runs or modifies a paper-reading workflow; the manifest and raw-sections file are its only paper-content boundary. See references/file-contract.md for JSON and CLI contracts.

Preview And Wait (Default)

  1. Show saved configuration on first use per person/device. If absent, ask for a term directory inside an Obsidian vault and configure it; reuse valid configuration later. Setup may create ~/.paper-glossary/config.json.
  2. Require an explicit article Markdown path when article links are requested. Validate it and the configured term directory are in the same Obsidian vault; never infer an article path.
  3. Run deterministic proposal from the effective body.
  4. Perform exactly one grounded host semantic review, bounded by shortlist_limit. It may only drop or reorder candidates and must preserve each retained proposal candidate's exact term string.
  5. Record the reviewed shortlist with plan_glossary.py --review-proposal PROPOSAL --reviewed-terms NAMES; this validates the saved proposal against the current paper source and preserves each full candidate, ordered surface_forms, and provenance. If review produces an empty reviewed shortlist, report no_candidates and stop without presenting a selector.
  6. Present every retained term from that reviewed artifact as a numbered Markdown list. This is the terminal, Codex, and Claude Code interaction. Show the resolved term directory, the article Markdown path (or that none was requested), and that selection authorizes glossary writes/enrichment plus first-safe-occurrence article links when an article was supplied.
  7. State: No glossary notes or article Markdown have been written before selection. End the response and wait. Do not triage, inventory, generate, link, or lint during preview.

A broad request, manifest, raw sections path, or article path is not selection approval. A host-native selector is allowed only when it displays the complete same list in one interaction.

After Selection

Accept only numbers, exact term names, or 全部写入 from the immediately preceding numbered list. Resolve them to the exact displayed term strings before invoking a script; 全部写入 applies only to that list. Invalid selections receive the valid range and another wait. Triage requires both --reviewed-shortlist REVIEW and the resolved exact names in --terms; never use --terms alone or add alias syntax.

Pass the current --source-manifest, optional --raw-sections, and saved --reviewed-shortlist to inventory, writer, and linker. Inventory consumes the saved --triage artifact as its selected-term input; writer and linker must also receive that same saved --triage. They require exact ordered term and surface_forms equality with this independent authorization before any glossary or article write.

  1. Triage the selection; its selection identity binds each exact selected name and ordered paper-grounded forms.
  2. Run library inventory from that triage artifact; it recomputes the complete proposal/review/selection provenance chain and fails closed on mismatched paper, source, shortlist, or forms.
  3. Then generate one action-aware batch.
  4. Run one writer invocation against the configured glossary directory; it revalidates the same provenance chain and requires its ordered inventory results to match the authorized triage exactly, then performs whole-batch preflight followed by the create/enrich/reuse commit. The writer resolves device-local configuration (or an explicit --config-path for that device) and does not accept a standalone write destination. With --article, its backlink is derived from the resolved article Markdown stem. Without an article, the glossary-only backlink comes from the validated manifest paper_id. The successful artifact preserves triage_sha256, provenance, article context, ordered mappings, and their deterministic mappings_sha256; the mapping digest binds the triage identity.
  5. Link each successful writer result at its first safe occurrence only if an article Markdown was supplied/requested. The linker authenticates the writer provenance, context, digest, note paths, stems, and forms against the same current source/review, and rejects an artifact with no bound article path. For a glossary-only request, skip link_glossary_terms.py.
  6. Lint writer-returned changed glossary note files whose action is created, enriched, or updated in one lint_glossary.py invocation with repeated --input PATH arguments. Do not pass article Markdown to lint_glossary.py.
  7. Report observable wall-clock timing and statuses. Time host-only phases separately. Each CLI emits top-level elapsed_ms for its own complete invocation. The single writer invocation includes whole-batch preflight and commit. Do not report separate preflight and commit timings.

new entries are created; existing_thin entries receive only missing structured fields and a missing occurrence; existing_complete entries may receive only a missing occurrence. Do not overwrite existing note content. See references/file-contract.md for existing_thin, entry operations, writer forms, and link statuses.

Grounding

  • anchor_only: concise paper use plus a thin general explanation.
  • needs_explanation: labeled background explanation with confidence and paper occurrence.
  • Exclude reference-only occurrences as evidence. Keep paper facts in occurrence and outside knowledge labeled.
Files (deeppapernote)
  • agents
    • openai.yaml 475 B
      Loading…
  • references
    • file-contract.md 12.9 KB
      Loading…
    • optimization-design.md 10 KB
      Loading…
  • scripts
    • configure_glossary.py 2.7 KB
      Loading…
    • glossary_common.py 11.7 KB
      Loading…
    • glossary_config.py 4.8 KB
      Loading…
    • glossary_contracts.py 518 B
      Loading…
    • glossary_library.py 13.5 KB
      Loading…
    • inspect_glossary_library.py 2.6 KB
      Loading…
    • link_glossary_terms.py 34.5 KB
      Loading…
    • lint_glossary.py 4.5 KB
      Loading…
    • plan_glossary.py 27.4 KB
      Loading…
    • write_glossary_terms.py 30 KB
      Loading…
  • tests
    • conftest.py 5.3 KB
      Loading…
    • test_glossary_config.py 12.1 KB
      Loading…
    • test_glossary_library.py 19.1 KB
      Loading…
    • test_link_glossary_terms.py 49.4 KB
      Loading…
    • test_plan_glossary.py 29.4 KB
      Loading…
    • test_skill_boundary.py 12.2 KB
      Loading…
    • test_workflow_integration.py 12.2 KB
      Loading…
    • test_write_and_lint_glossary.py 66.6 KB
      Loading…
  • README.md 4.5 KB
    # Paper Glossary
    
    `paper-glossary` builds reusable Obsidian glossary notes from `*_source_manifest.json` and `*_raw_sections.jsonl`. It remains self-contained and does not call a paper-reading workflow.
    
    ## One-Time Device Setup
    
    Each person configures one term directory once per device. The directory must be inside an Obsidian vault: its nearest vault ancestor must contain `.obsidian`. The local configuration is `~/.paper-glossary/config.json`; it stores an absolute resolved vault root and the terms subdirectory, not a repository setting. Relative and Windows drive-relative vault roots are rejected. Later runs reuse it.
    
    Setup may create `~/.paper-glossary/config.json`; before selection, no glossary notes or article Markdown are written. Run commands from the repository root and replace each quoted `<vault>` placeholder with the real vault path.
    
    ## Windows PowerShell
    
    ```powershell
    py -3.12 skills\paper-glossary\scripts\configure_glossary.py --terms-dir '<vault>\Glossary'
    py -3.12 skills\paper-glossary\scripts\configure_glossary.py --show
    py -3.12 skills\paper-glossary\scripts\configure_glossary.py --reset
    py -3.12 skills\paper-glossary\scripts\configure_glossary.py --validate-article '<vault>\Papers\example.md'
    py -3.12 -m pytest -q skills\paper-glossary\tests --basetemp .pytest-tmp-paper-glossary
    ```
    
    ## macOS / Linux Bash
    
    ```bash
    python3 skills/paper-glossary/scripts/configure_glossary.py --terms-dir '<vault>/Glossary'
    python3 skills/paper-glossary/scripts/configure_glossary.py --show
    python3 skills/paper-glossary/scripts/configure_glossary.py --reset
    python3 skills/paper-glossary/scripts/configure_glossary.py --validate-article '<vault>/Papers/example.md'
    python3 -m pytest -q skills/paper-glossary/tests --basetemp .pytest-tmp-paper-glossary
    ```
    
    When article links are requested, provide the article Markdown path explicitly. It must be a `.md` file in the same Obsidian vault as the configured term directory; the skill never guesses an article from the paper source artifacts.
    
    `--source-manifest` is required for proposal, review recording, and triage. `--raw-sections` is an optional override for the manifest's `raw_sections_path`, not a standalone replacement. The artifact workflow is:
    
    1. Run `plan_glossary.py --propose ... --output proposal.json`.
    2. Perform one semantic review, then record its exact ordered subset with `--review-proposal proposal.json --reviewed-terms ... --output reviewed.json`.
       If this produces an **empty reviewed shortlist**, report `no_candidates` and stop without displaying an empty selector.
    3. Display the complete reviewed shortlist as numbers and wait. Resolve number responses or `全部写入` to exact names outside the CLI.
    4. Run triage with `--reviewed-shortlist reviewed.json --terms ...`; `--terms` alone is rejected.
    5. Pass triage to inventory, inventory to the writer at the **configured glossary directory** (use `--config-path` only to select that device-local configuration), and successful writer results to the linker when an article was requested.
    
    For inventory, writer, and linker, always pass the current `--source-manifest`, optional `--raw-sections`, and saved `--reviewed-shortlist`. Inventory reads the saved `--triage` as its input; writer and linker also require that same saved `--triage` and enforce exact ordered `term` and `surface_forms` equality with it. These post-triage CLIs recompute the current proposal/review chain before writing. When the writer receives `--article`, `paper_link` is **derived from the resolved article Markdown stem**. A glossary-only writer invocation omits `--article` and derives `paper_link` from the **validated manifest `paper_id`**; do not run the linker for that branch because it rejects a writer artifact with **no bound article path**.
    
    Proposal candidates carry ordered paper-grounded `surface_forms` plus SHA-256 provenance and the bounded candidate/summary material needed to recompute it. Inventory and writer both fail closed unless proposal, review, and selection digests recompute from one matching paper/source chain and the exact ordered forms. Review, triage, inventory, and writer results preserve those forms; model-authored note aliases are metadata and are not article-match forms. Writer output also preserves `triage_sha256`, validated provenance, and context and binds the triage identity plus exact ordered mappings with `mappings_sha256`; the linker recomputes that digest and validates every note path, stem, and grounded form. See `SKILL.md` and `references/file-contract.md` for exact article and glossary-only invocations and JSON contracts.
    
  • SKILL.md 6 KB
    ---
    name: paper-glossary
    description: Use when building reusable Obsidian glossary notes from an existing paper source manifest, optionally with a raw-sections override, especially when a reader needs a reviewed shortlist before glossary notes and article links are changed.
    ---
    
    # Paper Glossary
    
    Build shared glossary notes from `*_source_manifest.json`. `--source-manifest` is always required; `--raw-sections` only overrides its `raw_sections_path` with an explicit `*_raw_sections.jsonl`. This skill never runs or modifies a paper-reading workflow; the manifest and raw-sections file are its only paper-content boundary. See `references/file-contract.md` for JSON and CLI contracts.
    
    ## Preview And Wait (Default)
    
    1. **Show saved configuration** on first use per person/device. If absent, ask for a term directory inside an Obsidian vault and configure it; reuse valid configuration later. **Setup may create `~/.paper-glossary/config.json`**.
    2. **Require an explicit article Markdown path** when article links are requested. Validate it and the configured term directory are in the **same Obsidian vault**; never infer an article path.
    3. **Run deterministic proposal** from the effective body.
    4. **Perform exactly one grounded host semantic review**, bounded by `shortlist_limit`. It may **only drop or reorder candidates** and must preserve each retained proposal candidate's **exact `term` string**.
    5. **Record the reviewed shortlist** with `plan_glossary.py --review-proposal PROPOSAL --reviewed-terms NAMES`; this validates the saved proposal against the current paper source and preserves each full candidate, ordered `surface_forms`, and provenance.
       If review produces an **empty reviewed shortlist**, report `no_candidates` and stop without presenting a selector.
    6. **Present every retained term** from that reviewed artifact as a numbered Markdown list. This is the terminal, Codex, and Claude Code interaction. Show the resolved term directory, the article Markdown path (or that none was requested), and that selection authorizes glossary writes/enrichment plus first-safe-occurrence article links when an article was supplied.
    7. State: **No glossary notes or article Markdown have been written before selection.** **End the response and wait.** Do not triage, inventory, generate, link, or lint during preview.
    
    A broad request, manifest, raw sections path, or article path is not selection approval. A host-native selector is allowed only when it displays the complete same list in one interaction.
    
    ## After Selection
    
    **Accept only numbers**, exact term names, or `全部写入` from the immediately preceding numbered list. Resolve them to the exact displayed `term` strings before invoking a script; `全部写入` applies only to that list. Invalid selections receive the valid range and another wait. Triage requires both `--reviewed-shortlist REVIEW` and the resolved exact names in `--terms`; never use `--terms` alone or add alias syntax.
    
    Pass the current `--source-manifest`, optional `--raw-sections`, and saved `--reviewed-shortlist` to inventory, writer, and linker. Inventory consumes the saved `--triage` artifact as its selected-term input; writer and linker must also receive that same saved `--triage`. They require exact ordered `term` and `surface_forms` equality with this independent authorization before any glossary or article write.
    
    1. **Triage** the selection; its selection identity binds each exact selected name and ordered paper-grounded forms.
    2. Run library **inventory** from that triage artifact; it recomputes the complete proposal/review/selection provenance chain and fails closed on mismatched paper, source, shortlist, or forms.
    3. Then **generate one action-aware batch**.
    4. **Run one writer invocation** against the **configured glossary directory**; it revalidates the same provenance chain and requires its ordered inventory results to match the authorized triage exactly, then performs **whole-batch preflight** followed by the **create/enrich/reuse commit**. The writer resolves device-local configuration (or an explicit `--config-path` for that device) and does not accept a standalone write destination. With `--article`, its backlink is **derived from the resolved article Markdown stem**. Without an article, the glossary-only backlink comes from the **validated manifest `paper_id`**. The successful artifact preserves `triage_sha256`, provenance, article context, ordered mappings, and their deterministic `mappings_sha256`; the mapping digest binds the triage identity.
    5. **Link each successful writer result** at its first safe occurrence **only if an article Markdown was supplied/requested**. The linker authenticates the writer provenance, context, digest, note paths, stems, and forms against the same current source/review, and rejects an artifact with **no bound article path**. **For a glossary-only request, skip `link_glossary_terms.py`**.
    6. **Lint writer-returned changed glossary note files** whose **`action` is `created`, `enriched`, or `updated`** in **one `lint_glossary.py` invocation with repeated `--input PATH`** arguments. **Do not pass article Markdown to `lint_glossary.py`**.
    7. **Report observable wall-clock timing** and statuses. **Time host-only phases separately**. **Each CLI emits top-level `elapsed_ms`** for its own complete invocation. The **single writer invocation includes whole-batch preflight and commit**. **Do not report separate preflight and commit timings**.
    
    `new` entries are created; `existing_thin` entries receive only missing structured fields and a missing occurrence; `existing_complete` entries may receive only a missing occurrence. **Do not overwrite** existing note content. See `references/file-contract.md` for `existing_thin`, entry operations, writer `forms`, and link statuses.
    
    ## Grounding
    
    - `anchor_only`: concise paper use plus a thin general explanation.
    - `needs_explanation`: labeled background explanation with confidence and paper occurrence.
    - Exclude reference-only occurrences as evidence. Keep paper facts in `occurrence` and outside knowledge labeled.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.