steve/skills
Public Access
1
0
Fork 0
Code Issues 11 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

phase4-7: rewrite PKM skills for OKF v0.1 alignment

Browse Source 
Phase 4: Rewrite research-vault skill
- Packet becomes OKF bundle with index.md (no frontmatter) and log.md
- All packet pages get proper type frontmatter
- Atomic note template uses merged OKF + vault schema
- Links use markdown [...](...) not wikilinks
- Updated research-packet-template.md reference

Phase 5: Rewrite pkm-curation skill
- Frontmatter normalization adds type field using classification heuristics
- Links use markdown [...](...) not wikilinks
- Bundle awareness added (update index.md, log.md)
- Updated agent-integration.md for OKF conventions

Phase 6: Rewrite conversation-summary skill
- AI Conversation Summaries/ bundle awareness (update index.md, log.md)
- Report and transcript notes get merged frontmatter with proper type
- Links use markdown [...](...) not wikilinks

Phase 7: Review crit skill
- No vault I/O changes needed — pure brainstorming framework
This commit is contained in:
gitadmin
2026-07-06 21:34:55 -04:00
parent 41d1d48025
commit de4f6f137b
5 changed files with 354 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files
common/pkm/research-vault/SKILL.md
+94 -13
View File
@@ -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/<YYYY-MM-DD> <Topic>/`, 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/<YYYY-MM-DD> <Topic>/`, 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/<YYYY-MM-DD> <Topic>/
├── 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
└── <atomic-note>.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 type name> # OKF required
title: <display name> # OKF recommended
description: <one-line summary> # OKF recommended
resource: <canonical URI> # OKF recommended (when applicable)
tags: [<tag>, ...] # OKF recommended + vault required
timestamp: <ISO 8601 datetime> # OKF recommended
id: <unique identifier> # vault required
aliases: [<alias>, ...] # vault required
area: <area/domain> # vault required
project: <project name or ''> # 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
# <Topic>
## 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/<YYYY-MM-DD> <Topic
2. **Frame the goal.** Ask one question at a time until you can restate the topic, learning objective, scope, and success criteria. Discover the user's goal, prior knowledge, intended use, depth, constraints, output preference, and trusted/distrusted sources only as needed.
3. **Create or defer the folder.** Create the packet folder once the topic has a stable working title; if still vague, keep conversing. Before writing durable notes, every artifact must have a path inside the packet folder.
4. **Map context.** Search the vault for the topic, synonyms, projects, and neighboring concepts. Read enough relevant notes to make meaningful links, not keyword matches.
5. **Ingest sources into claims.** For each source, preserve its path in `Sources.md`, extract evidence-backed claims into `Claims.md`, update affected concept/summary pages, and append an event to `Log.md`. Completion: every non-trivial factual claim has source, evidence, confidence, and at least one related link or explicit note that no link exists yet.
5. **Ingest sources into claims.** For each source, preserve its path in `Sources.md`, extract evidence-backed claims into `Claims.md`, update affected concept/summary pages, and append an event to `log.md`. Completion: every non-trivial factual claim has source, evidence, confidence, and at least one related link or explicit note that no link exists yet.
6. **Research and teach.** Answer the user directly from the compiled packet when possible, explain findings in small chunks, cite claims, preserve uncertainty, share resources when they improve learning or evidence quality, and correct misunderstandings before moving on.
7. **File good answers.** When a query produces a durable synthesis, decision, comparison, or explanation, add it back into `Synthesis.md`, `Claims.md`, or an atomic note instead of leaving it only in chat. Append the query and filed destination to `Log.md`.
7. **File good answers.** When a query produces a durable synthesis, decision, comparison, or explanation, add it back into `Synthesis.md`, `Claims.md`, or an atomic note instead of leaving it only in chat. Append the query and filed destination to `log.md`.
8. **Check understanding and completeness.** Ask one diagnostic or completeness question per turn. Answer follow-ups with evidence, examples, counterarguments, implementation details, or resources as needed. Capture unresolved gaps in `Questions.md`.
9. **Write incrementally.** For long sessions, update `Conversation.md`, `Questions.md`, `Glossaries.md`, `Sources.md`, and `Log.md` as the work progresses. By the end, no research, teaching insight, user question, glossary term, source, or durable knowledge should exist only in chat.
10. **Lint the packet.** Before final report or promotion, check for unsupported claims, stale or contradictory claims, missing source links, orphan atomic notes, glossary terms without links, unanswered questions, and missing backlinks from `Index.md`. Record notable lint findings or fixes in `Log.md`.
9. **Write incrementally.** For long sessions, update `Conversation.md`, `Questions.md`, `Glossaries.md`, `Sources.md`, and `log.md` as the work progresses. By the end, no research, teaching insight, user question, glossary term, source, or durable knowledge should exist only in chat.
10. **Lint the packet.** Before final report or promotion, check for unsupported claims, stale or contradictory claims, missing source links, orphan atomic notes, glossary terms without links, unanswered questions, and missing backlinks from `index.md`. Record notable lint findings or fixes in `log.md`.
11. **Promote reusable notes.** If a packet note becomes broadly useful beyond the run, propose promotion to the main vault, copy or move only with user approval, leave a provenance link in the packet, and update relevant indexes/MOCs.
12. **Report.** Summarize the packet path, files changed, links or backlink suggestions, top takeaways, what the user now understands, remaining questions, lint status, and promotion candidates.
@@ -35,7 +114,7 @@ Create one vault folder per research run, normally `Research/<YYYY-MM-DD> <Topic
- Use a teach-back loop for complex topics: plain-language explanation → concrete example → one check question or restatement prompt → correction → continue only when the user is satisfied or uncertainty is captured.
- Ask checks before research, after initial framing, after major findings, and before finalizing notes.
- When the user corrects you, record the correction in `Conversation.md`, update affected packet notes, and prefer the corrected framing unless later evidence contradicts it.
- Record important answers and useful resources in `Conversation.md`; reflect scope-changing details in `Index.md`, `Sources.md`, or `Synthesis.md`.
- Record important answers and useful resources in `Conversation.md`; reflect scope-changing details in `index.md`, `Sources.md`, or `Synthesis.md`.
## Capture Rules
@@ -49,18 +128,20 @@ Create one vault folder per research run, normally `Research/<YYYY-MM-DD> <Topic
- Keep citations close to claims; mark confidence when evidence is incomplete or contested.
- Preserve useful quotes verbatim with attribution.
- Distinguish source claims from interpretation; record failed searches or missing evidence when they affect the conclusion.
- Create atomic notes in the packet folder for durable concepts; link each from `Index.md` and back to its source or synthesis section.
- Create atomic notes in the packet folder for durable concepts; link each from `index.md` and back to its source or synthesis section.
## Retrieval Checks
Run these checks before treating the packet as complete:
- Could a future agent answer the user's main question from `Index.md`, `Synthesis.md`, and `Claims.md` without rereading raw sources?
- Does `Index.md` point to every durable packet page with enough context to choose the right page?
- Could a future agent answer the user's main question from `index.md`, `Synthesis.md`, and `Claims.md` without rereading raw sources?
- Does `index.md` point to every durable packet page with enough context to choose the right page?
- Are important terms findable in `Glossaries.md` and linked from the pages that use them?
- Are contradictions, uncertainty, and missing evidence visible near the relevant claims?
- Does `Log.md` show the ingest/query/lint history well enough to reconstruct what changed and why?
- Does `log.md` show the ingest/query/lint history well enough to reconstruct what changed and why?
## Linking Rules
Use Obsidian wikilinks: `[[Note Title]]` or `[[path/to/Note|alias]]`. Add links only when they explain context: broader concepts, projects, areas, MOCs, sources, authors, methods, tools, domains, supporting/refining/contradicting claims, or active problems. Do not link on shared words alone.
Use standard markdown links: `[text](relative/path.md)`. Do NOT use `[[wikilinks]]`. Add links only when they explain context: broader concepts, projects, areas, MOCs, sources, authors, methods, tools, domains, supporting/refining/contradicting claims, or active problems. Do not link on shared words alone.
Use bundle-relative links for intra-packet references (`[Sources](Sources.md)`) and vault-relative or absolute paths for cross-bundle references.
common/pkm/research-vault/references/research-packet-template.md
+125 -31
View File
@@ -1,10 +1,27 @@
# Research Packet Template
# Research Packet Template (OKF v0.1)
Use inside `Research/<YYYY-MM-DD> <Topic>/` 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/<YYYY-MM-DD> <Topic>/
├── 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
└── <atomic-note>.md # Concept
```
### `index.md`
No frontmatter. Progressive-disclosure listing:
```markdown
# <Topic>
@@ -18,19 +35,19 @@ Use inside `Research/<YYYY-MM-DD> <Topic>/` 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/<YYYY-MM-DD> <Topic>/` 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: <Topic> - Sources
description: Compiled source list for <Topic>.
tags: [research, sources]
timestamp: <ISO 8601>
id: <topic-slug>-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: <Topic> - Synthesis
description: Compiled answer for <Topic> research.
tags: [research, synthesis]
timestamp: <ISO 8601>
id: <topic-slug>-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: <Topic> - Claims
description: Evidence-backed claims for <Topic> research.
tags: [research, claims]
timestamp: <ISO 8601>
id: <topic-slug>-claims
aliases: []
area: Research
project: ''
---
# Claims
## Claim: <single answerable claim>
@@ -96,6 +161,18 @@ Include source links, books, papers, docs, videos, examples, search terms, or re
### `Questions.md`
```markdown
---
type: Research Questions
title: <Topic> - Questions
description: Open and resolved questions for <Topic> research.
tags: [research, questions]
timestamp: <ISO 8601>
id: <topic-slug>-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: <Topic> - Conversation
description: Narrative summary of the research conversation for <Topic>.
tags: [research, conversation]
timestamp: <ISO 8601>
id: <topic-slug>-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 — <ingest | query | lint | promotion | correction>
- Input:
- Files read:
- Files changed:
- Claims added or revised:
- Links added:
- Open issues:
```
### `Glossaries.md`
```markdown
---
type: Research Glossary
title: <Topic> - Glossary
description: Term definitions for <Topic> research.
tags: [research, glossary]
timestamp: <ISO 8601>
id: <topic-slug>-glossary
aliases: []
area: Research
project: ''
---
# Glossaries
## <Term or Acronym>
@@ -167,12 +252,17 @@ Add every acronym, abbreviation, domain-specific phrase, specialized term, jargo
```markdown
---
type: Concept
title: <Concept Name>
description: <One-line summary of the concept>.
tags: [research, atomic-note, <topic-tag>]
timestamp: <ISO 8601>
id: <stable-id>
aliases: []
tags: [research, atomic-note]
area: <area>
project: [[<packet topic>]]
project: <packet topic>
---
# <Concept>
## Idea
@@ -182,7 +272,7 @@ project: [[<packet topic>]]
<Explain retrieval, decision, or learning value.>
## Evidence or source
- Claim: [[Claims#Claim <anchor or short title>]]
- Claim: [Claims](Claims.md)
- Source:
## Links
@@ -191,5 +281,9 @@ project: [[<packet topic>]]
- 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.