diff --git a/common/pkm/conversation-summary/SKILL.md b/common/pkm/conversation-summary/SKILL.md index 176c709..fa18007 100644 --- a/common/pkm/conversation-summary/SKILL.md +++ b/common/pkm/conversation-summary/SKILL.md @@ -1,10 +1,10 @@ --- name: conversation-summary -description: Save the current conversation as a comprehensive report note in your Obsidian vault. +description: Save the current conversation as a comprehensive report note in your Obsidian vault, following OKF v0.1 conventions. disable-model-invocation: true --- -Save this conversation as two linked files in your Obsidian vault: a report (the narrative) and a transcript (the raw conversation). +Save this conversation as two linked files in your Obsidian vault: a report (the narrative) and a transcript (the raw conversation). The files live inside the `AI Conversation Summaries/` bundle and follow OKF v0.1 conventions. ## Report @@ -18,7 +18,32 @@ Write a thorough, standalone report as a Markdown note. A rich narrative in pros The report must be self-contained — someone reading it later should understand the full discussion, including the reasoning and all relevant details, without having been there. Err on the side of including too much detail rather than too little. -Include a link to the companion transcript where it fits naturally — an Obsidian wikilink like `[[{{title}}_transcript]]` in the section where it makes the most sense (often near the end). +Include a link to the companion transcript where it fits naturally — a markdown link like `[transcript](2026-05-23_16-35_obsidian-summary-skill-upgrade_A7K2_transcript.md)` in the section where it makes the most sense (often near the end). + +## Frontmatter + +Both the report and the transcript use the merged OKF + vault frontmatter schema: + +```yaml +--- +type: Conversation Report # report: Conversation Report, transcript: Conversation Transcript +title: +description: +tags: [conversation, ] +timestamp: +id: +aliases: [] +area: +project: '' +--- +``` + +## Bundle Awareness + +`AI Conversation Summaries/` is an OKF bundle. After writing each new report/transcript pair: + +1. Update `AI Conversation Summaries/index.md` — add an entry for the new report and transcript. +2. Append an entry to `AI Conversation Summaries/log.md` noting the addition. ## Transcript @@ -33,6 +58,14 @@ Save both files to `AI Conversation Summaries/` under your vault root. Create th - Report: `YYYY-MM-DD_HH-mm_.md` - Transcript: `YYYY-MM-DD_HH-mm__transcript.md` +## Links + +Use standard markdown links: `[text](relative/path.md)`. Do NOT use `[[wikilinks]]`. + +Link the report to its transcript and vice versa using filenames: +- In report: `[transcript](YYYY-MM-DD_HH-mm__transcript.md)` +- In transcript: `[report](YYYY-MM-DD_HH-mm_.md)` + ## Safety - Use only facts from the conversation. Do not invent references, decisions, or conclusions. @@ -40,4 +73,4 @@ Save both files to `AI Conversation Summaries/` under your vault root. Create th ## Done -Confirm both file paths and a one-sentence description of what the report covers. +Confirm both file paths and a one-sentence description of what the report covers. Also confirm that `AI Conversation Summaries/index.md` and `log.md` were updated. diff --git a/common/pkm/pkm-curation/SKILL.md b/common/pkm/pkm-curation/SKILL.md index 4d74d18..0f913f1 100644 --- a/common/pkm/pkm-curation/SKILL.md +++ b/common/pkm/pkm-curation/SKILL.md @@ -1,23 +1,24 @@ --- name: pkm-curation -description: Curate an Obsidian vault — classify notes, normalize frontmatter, add wikilinks, extract atomic notes. Use when curating, batch-processing, reviewing, or doing a serendipity pick. +description: Curate an Obsidian vault — classify notes, normalize frontmatter, add links, extract atomic notes. Use when curating, batch-processing, reviewing, or doing a serendipity pick. --- # PKM Curation -Use this skill when working inside a Markdown-first vault that values curation over collection. +Use this skill when working inside a Markdown-first vault that follows the [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) conventions. ## Goals - Turn raw notes into reusable atomic notes. - Keep new notes consistent with vault conventions. -- Strengthen the link graph with meaningful `[[wikilinks]]`. +- Strengthen the link graph with meaningful markdown links. - Extract atomic notes from long or mixed-topic notes. +- Maintain bundle integrity: update index.md and log.md when adding or changing bundle contents. ## Read This First - Read `AGENTS.md` in the current repo scope before editing notes. -- Read `references/vault-conventions.md` when normalizing metadata, deciding note types, or choosing folders. +- Read `references/vault-conventions.md` when normalizing metadata, deciding note types, or choosing folders. This reference now documents the merged OKF + vault frontmatter schema. - Read `references/agent-integration.md` when running this skill through an agent. - Keep changes small and reviewable. - Keep file operations local to the vault unless the user explicitly asks otherwise. @@ -29,13 +30,13 @@ Use this skill when working inside a Markdown-first vault that values curation o fd --type f ".md" "path/to/obsidian-vault" | rg -i "keyword" # Search by content -rg -l "keyword" "path/to/obsidian-vault" --include "*.md" +rg -l "keyword" "path/to/obsidian-vault" -g "*.md" -# Find backlinks to a note -rg -l "\\[\\[Note Title\\]\\]" "path/to/obsidian-vault" --include "*.md" +# Find backlinks to a note (markdown link form) +rg -l "Note Title" "path/to/obsidian-vault" -g "*.md" -# Find index notes -fd --type f "Index" "path/to/obsidian-vault" +# Find bundle index files +fd "index.md" "path/to/obsidian-vault" ``` ## Rules @@ -46,60 +47,85 @@ fd --type f "Index" "path/to/obsidian-vault" - Preserve the user's voice unless the user asks for a rewrite. - Keep source material and evergreen ideas separate when possible. - Treat `Inbox/` as temporary capture, not long-term storage. -- Preserve all command blocks, code snippets, configuration directives, and - step-by-step instructions verbatim. Do not summarize or condense them. -- For reference/source notes: add a brief overview at the top, but keep the - original commands and details intact below. Completeness > brevity. +- Preserve all command blocks, code snippets, configuration directives, and step-by-step instructions verbatim. Do not summarize or condense them. +- For reference/source notes: add a brief overview at the top, but keep the original commands and details intact below. Completeness > brevity. - Read every file completely before moving, renaming, or modifying it. Do not rely on head/tail, heading-only scans, or partial reads to judge a file's content. +- **Bundle awareness**: When creating or editing notes inside a bundle directory, update the bundle's `index.md` (add or update the entry) and append an entry to `log.md`. ## Note-Type Heuristics -### Inbox note +Use the type vocabulary from `references/vault-conventions.md`. When inferring a type for a note, use these heuristics: +### Inbox note → `type: Inbox` Use when the note is raw capture, partial thinking, copied text, or an unprocessed link dump. +- Actions: clean obvious structure issues, add frontmatter if missing, classify for later promotion, avoid over-polishing unless requested. -Actions: -- clean obvious structure issues -- add frontmatter if missing -- classify for later promotion -- avoid over-polishing unless requested - -### Source note - +### Source note → `type: Source` Use when the note is based on an article, video, book, paper, transcript, or other external material. +- Actions: keep source context intact, summarize key takeaways, extract reusable ideas into separate atomic notes, link to related concepts and projects. -Actions: -- keep source context intact -- summarize key takeaways -- extract reusable ideas into separate atomic notes -- link to related concepts and projects - -### Atomic note - +### Atomic note → `type: Concept` Use when the note captures one durable idea, concept, claim, pattern, or insight. +- Actions: ensure one main idea per note, make the title concept-focused, add links to neighboring ideas, keep it concise and self-contained. -Actions: -- ensure one main idea per note -- make the title concept-focused -- add links to neighboring ideas -- keep it concise and self-contained - -### Project note - +### Project note → `type: Project` Use when the note supports active work, planning, resources, decisions, or tasks. +- Actions: preserve project context, link tasks to the project note, avoid turning active project logistics into evergreen notes unless there is a reusable insight. -Actions: -- preserve project context -- link tasks to the project note -- avoid turning active project logistics into evergreen notes unless there is a reusable insight - -### Daily note - +### Daily note → `type: Daily` Use when the note is date-based and captures activity, learning, tasks, or reflection for a single day. +- Actions: preserve chronology, link out to durable notes rather than stuffing ideas into the daily note. -Actions: -- preserve chronology -- link out to durable notes rather than stuffing ideas into the daily note +### Reference note → `type: Reference` +Use when the note is lookup material, documentation, specs, or external reference. +- Actions: preserve the reference content, add structured overview at top, link to related notes. + +## Frontmatter Normalization + +All notes should have the merged OKF + vault frontmatter schema: + +```yaml +--- +type: # OKF required +title: # OKF recommended +description: # OKF recommended +resource: # OKF recommended (when applicable) +tags: [, ...] # OKF recommended + vault required +timestamp: # OKF recommended +id: # vault required +aliases: [, ...] # vault required +area: # vault required +project: # vault required +--- +``` + +When normalizing existing frontmatter: +- Add `type` using the classification heuristics above. +- Ensure `id` is a stable kebab-case slug. +- Ensure `timestamp` is ISO 8601 format. +- Ensure `project` is a plain string, not a `[[wikilink]]`. +- Preserve any additional OKF extension keys. + +## Link Convention + +Use **standard markdown links**: `[text](relative/path.md)`. Do NOT use `[[wikilinks]]`. + +When converting existing wikilinks: +- `[[Note Title]]` → `[Note Title](Note%20Title.md)` +- `[[Note Title|alias]]` → `[alias](Note%20Title.md)` + +Use vault-relative paths from the linking file to the target. + +## Bundle Awareness + +When working inside a bundle directory: +- **After creating a new note**: add an entry to the bundle's `index.md` and append an entry to `log.md`. +- **After modifying an existing note**: if the change is significant, update the description in `index.md` and append an entry to `log.md`. +- **After deleting or moving a note**: remove or update its entry in `index.md` and append an entry to `log.md`. + +The bundle map is defined in `references/vault-conventions.md`. Key bundle directories include: `Knowledge/`, `Notes/` (with sub-bundles), `Resources/` (with sub-bundles), `Profiles/`, `AI Conversation Summaries/`, `Research//`, `Projects//`. + +Non-bundle directories (`Inbox/`, `Dailies/`, `Templates/`, `Clippings/`) do not get `index.md` or `log.md`. ## Linking Guidance @@ -122,21 +148,22 @@ Extract atomic notes when a note contains: - a reusable method, distinction, or definition - a concept that should be linked from many places -Keep extracted notes short. One note, one idea. +Keep extracted notes short. One note, one idea. When extracting into a bundle directory, update `index.md` and `log.md`. ## Common Tasks ### Curate one note 1. Inspect the target note and locate its file in the vault. -2. Identify the note type: inbox, source, atomic, project, daily, or reference. -3. Normalize frontmatter and basic structure. +2. Identify the note type: inbox, source, concept, project, daily, reference, or person. +3. Normalize frontmatter and basic structure using the merged schema. 4. Clarify the title if vague or timestamp-like. 5. Tighten headings and summary; distill if it mixes too many ideas. -6. Inspect nearby related notes, then add a few strong `[[wikilinks]]`. +6. Inspect nearby related notes, then add a few strong markdown links. 7. If the note contains multiple durable ideas, extract 1-3 atomic notes. 8. Suggest moving only if the destination is clearly better. -9. Patch the note in place and return a short summary of edits. +9. If inside a bundle, update `index.md` and `log.md`. +10. Patch the note in place and return a short summary of edits. **Completion Criterion**: Note inspected, classified, normalized, linked, and patched, with a summary returned to the user. @@ -187,6 +214,7 @@ When responding to the user: - name the file or files touched - separate completed edits from suggested next actions - call out anything that still needs user confirmation +- mention any bundle index/log updates made ## If You Need More Context diff --git a/common/pkm/pkm-curation/references/agent-integration.md b/common/pkm/pkm-curation/references/agent-integration.md index a75f378..0d8a78b 100644 --- a/common/pkm/pkm-curation/references/agent-integration.md +++ b/common/pkm/pkm-curation/references/agent-integration.md @@ -5,15 +5,16 @@ aliases: tags: - knowledge-management - reference + - okf area: Personal Knowledge Management -project: +project: '' --- # Agent Integration ## Purpose -This skill should be usable from any agent, and it should also fit chat environments where the agent as tool access. +This skill should be usable from any agent, and it should also fit chat environments where the agent has tool access. ## Recommended Role @@ -21,6 +22,14 @@ This skill should be usable from any agent, and it should also fit chat environm - interactive note refinement, serendipity review, and exploratory linking sessions - editor-side entry point that delegates vault actions to agent where possible +## Bundle Awareness + +The vault follows OKF v0.1 bundle conventions. When running curation tasks: + +- Creating a note inside a bundle directory: add an entry to `index.md` and an event to `log.md`. +- Modifying a note inside a bundle: update `index.md` description if the note's purpose changes; append to `log.md` for significant changes. +- Moving notes between bundle directories: update both source and destination bundle files. + ## Preferred Behaviors - search the vault before proposing links @@ -29,14 +38,16 @@ This skill should be usable from any agent, and it should also fit chat environm - summarize edits in plain Markdown - ask before removing any content or links from a note - ask before moving, renaming, or creating many files +- update bundle `index.md` and `log.md` when creating notes inside bundles ## Good Task Shapes -- curate a specific note -- process a small `Inbox/` batch +- curate a specific note (normalize frontmatter, classify type, add markdown links) +- process a small `Inbox/` batch (classify and normalize) - review recent notes for missing links - extract atomic notes from one source note - run a serendipity review against a current topic +- update or regenerate bundle `index.md` for a directory ## Avoid @@ -44,8 +55,10 @@ This skill should be usable from any agent, and it should also fit chat environm - broad speculative linking passes - converting every long note into atomic notes - changing note titles without stating why +- using `[[wikilinks]]` — always use standard markdown `[...](...)` links ## Portability Guidance - keep the workflow in `SKILL.md` tool-agnostic where possible - prefer small deterministic file edits so the skill remains portable to other `SKILL.md`-based agents +- always reference `vault-conventions.md` for the current frontmatter schema and type vocabulary diff --git a/common/pkm/research-vault/SKILL.md b/common/pkm/research-vault/SKILL.md index bee1bbb..bde226e 100644 --- a/common/pkm/research-vault/SKILL.md +++ b/common/pkm/research-vault/SKILL.md @@ -1,16 +1,95 @@ --- name: research-vault -description: Research a topic through a one-question-at-a-time learning conversation, answer directly, share resources when useful, and save a linked Obsidian research packet. +description: Research a topic through a one-question-at-a-time learning conversation, answer directly, share resources when useful, and save a linked OKF-conformant research packet in the Obsidian vault. disable-model-invocation: true --- # Research Vault -Use when the user wants to learn or research a topic conversationally and save the outcome in an Obsidian vault. +Use when the user wants to learn or research a topic conversationally and save the outcome in an Obsidian vault using the [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md). ## Packet -Create one vault folder per research run, normally `Research/ /`, containing all notes from the run: `Index.md`, `Sources.md`, `Synthesis.md`, `Claims.md`, `Questions.md`, `Conversation.md`, `Glossaries.md`, `Log.md`, and any atomic notes. Treat the packet as a Karpathy-style compiled wiki for the topic: raw sources stay immutable, packet notes are the maintained synthesis layer, and this skill is the schema. Load `references/research-packet-template.md` before writing packet files or when exact structure matters. +Create one vault folder per research run, normally `Research/ /`, containing an OKF bundle with `index.md` (progressive-disclosure listing, no frontmatter), `log.md` (chronological), and packet pages. Load `references/research-packet-template.md` before writing packet files or when exact structure matters. + +### Bundle structure + +``` +Research/ / +├── index.md # OKF progressive-disclosure, no frontmatter +├── log.md # OKF chronological, datestamped entries (newest first) +├── Sources.md # Research Source List +├── Synthesis.md # Research Synthesis +├── Claims.md # Research Claim Index +├── Questions.md # Research Questions +├── Conversation.md # Conversation Report +├── Glossaries.md # Research Glossary +└── .md # Concept / atomic notes +``` + +### Reserved filenames + +`index.md` and `log.md` are reserved — they MUST follow OKF format and MUST NOT be used for concept documents. + +### Frontmatter schema (merged — OKF + vault fields) + +Every concept document (non-reserved `.md` file) MUST have: + +```yaml +--- +type: # OKF required +title: # OKF recommended +description: # OKF recommended +resource: # OKF recommended (when applicable) +tags: [, ...] # OKF recommended + vault required +timestamp: # OKF recommended +id: # vault required +aliases: [, ...] # vault required +area: # vault required +project: # vault required +--- +``` + +Use the type vocabulary from `references/vault-conventions.md`. + +### `index.md` (OKF progressive-disclosure) + +No frontmatter. Sections with bullet links and descriptions: + +```markdown +# + +## Purpose +- Learning goal: +- Scope: +- Success criteria: + +## Packet Map +- [Sources](Sources.md) — compiled source list +- [Synthesis](Synthesis.md) — synthesized answer +- [Claims](Claims.md) — evidence-backed claims +- [Questions](Questions.md) — open and resolved questions +- [Conversation](Conversation.md) — raw conversation record +- [Glossaries](Glossaries.md) — term definitions +- [Log](Log.md) — session log + +## Compiled Pages +| Page | Type | Purpose | Status | +|---|---|---|---| +| | | | draft \| reviewed \| promoted | +``` + +### `log.md` (OKF chronological) + +Datestamped entries, newest first: + +```markdown +# Log + +## YYYY-MM-DD +* **Event type**: Description of what happened. +* **Files changed**: ... +``` ## Workflow @@ -18,12 +97,12 @@ Create one vault folder per research run, normally `Research/ /` unless the vault has a clearer convention. -## Required files +The packet is an OKF bundle. See [vault-conventions.md](../../pkm-curation/references/vault-conventions.md) for the full frontmatter schema and type vocabulary. -### `Index.md` +## Bundle structure + +``` +Research/ / +├── index.md # OKF progressive-disclosure, no frontmatter +├── log.md # OKF chronological, datestamped entries (newest first) +├── Sources.md # Research Source List +├── Synthesis.md # Research Synthesis +├── Claims.md # Research Claim Index +├── Questions.md # Research Questions +├── Conversation.md # Conversation Report +├── Glossaries.md # Research Glossary +└── .md # Concept +``` + +### `index.md` + +No frontmatter. Progressive-disclosure listing: ```markdown # @@ -18,19 +35,19 @@ Use inside `Research/ /` unless the vault has a clearer conve - ## Packet Map -- [[Sources]] -- [[Synthesis]] -- [[Claims]] -- [[Questions]] -- [[Conversation]] -- [[Glossaries]] -- [[Log]] +- [Sources](Sources.md) — compiled source list +- [Synthesis](Synthesis.md) — synthesized answer +- [Claims](Claims.md) — evidence-backed claims +- [Questions](Questions.md) — open and resolved questions +- [Conversation](Conversation.md) — raw conversation record +- [Glossaries](Glossaries.md) — term definitions +- [Log](Log.md) — session log ## Related Vault Notes - ## Compiled Pages -| Page | Type | One-line purpose | Source basis | Status | +| Page | Type | Purpose | Source basis | Status | |---|---|---|---|---| | | source summary \| concept \| claim cluster \| synthesis \| promoted | | | draft \| reviewed \| promoted | @@ -38,9 +55,33 @@ Use inside `Research/ /` unless the vault has a clearer conve - ``` +### `log.md` + +Datestamped entries, newest first. No frontmatter required (concept notes in the bundle DO need frontmatter, but log.md follows OKF §7 format). + +```markdown +# Log + +## YYYY-MM-DD +* **Event**: Description of what changed. +* **Files changed**: ... +``` + ### `Sources.md` ```markdown +--- +type: Research Source List +title: - Sources +description: Compiled source list for . +tags: [research, sources] +timestamp: +id: -sources +aliases: [] +area: Research +project: '' +--- + # Sources | Source | Type | Why useful | Reliability notes | Accessed | @@ -60,6 +101,18 @@ Include source links, books, papers, docs, videos, examples, search terms, or re ### `Synthesis.md` ```markdown +--- +type: Research Synthesis +title: - Synthesis +description: Compiled answer for research. +tags: [research, synthesis] +timestamp: +id: -synthesis +aliases: [] +area: Research +project: '' +--- + # Synthesis ## Short Answer @@ -79,6 +132,18 @@ Include source links, books, papers, docs, videos, examples, search terms, or re ### `Claims.md` ```markdown +--- +type: Research Claim Index +title: - Claims +description: Evidence-backed claims for research. +tags: [research, claims] +timestamp: +id: -claims +aliases: [] +area: Research +project: '' +--- + # Claims ## Claim: @@ -96,6 +161,18 @@ Include source links, books, papers, docs, videos, examples, search terms, or re ### `Questions.md` ```markdown +--- +type: Research Questions +title: - Questions +description: Open and resolved questions for research. +tags: [research, questions] +timestamp: +id: -questions +aliases: [] +area: Research +project: '' +--- + # Questions ## User Questions @@ -114,6 +191,18 @@ Include source links, books, papers, docs, videos, examples, search terms, or re ### `Conversation.md` ```markdown +--- +type: Conversation Report +title: - Conversation +description: Narrative summary of the research conversation for . +tags: [research, conversation] +timestamp: +id: -conversation +aliases: [] +area: Research +project: '' +--- + # Conversation ## Learning Goal @@ -132,25 +221,21 @@ Include source links, books, papers, docs, videos, examples, search terms, or re Record important answers, corrections, and scope decisions as the session progresses. -### `Log.md` - -```markdown -# Log - -Append one entry for each ingest, query filed back into the packet, lint pass, promotion, or major correction. - -## YYYY-MM-DD HH:MM — -- Input: -- Files read: -- Files changed: -- Claims added or revised: -- Links added: -- Open issues: -``` - ### `Glossaries.md` ```markdown +--- +type: Research Glossary +title: - Glossary +description: Term definitions for research. +tags: [research, glossary] +timestamp: +id: -glossary +aliases: [] +area: Research +project: '' +--- + # Glossaries ## @@ -167,12 +252,17 @@ Add every acronym, abbreviation, domain-specific phrase, specialized term, jargo ```markdown --- +type: Concept +title: +description: . +tags: [research, atomic-note, ] +timestamp: id: aliases: [] -tags: [research, atomic-note] area: -project: [[]] +project: --- + # ## Idea @@ -182,7 +272,7 @@ project: [[]] ## Evidence or source -- Claim: [[Claims#Claim ]] +- Claim: [Claims](Claims.md) - Source: ## Links @@ -191,5 +281,9 @@ project: [[]] - Contrasts: ## Promotion status -- Packet-local | candidate for main vault | promoted to [[path/to/promoted note]] +- Packet-local | candidate for main vault | promoted to [path/to/promoted note](path/to/promoted.md) ``` + +## Linking + +Use standard markdown links `[text](relative/path.md)` throughout. Do NOT use `[[wikilinks]]`. Intra-packet links are bundle-relative (e.g., `[Claims](Claims.md)`). Cross-bundle links use vault-relative paths.