skills/common/pkm/pkm-curation/SKILL.md

name, description

name	description
pkm-curation	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 follows the Open Knowledge Format (OKF) v0.1 conventions.

Goals

• Turn raw notes into reusable atomic notes.
• Keep new notes consistent with vault conventions.
• 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. 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.

Search

# Search by filename
fd --type f ".md" "path/to/obsidian-vault" | rg -i "keyword"

# Search by content
rg -l "keyword" "path/to/obsidian-vault" -g "*.md"

# Find backlinks to a note (markdown link form)
rg -l "Note Title" "path/to/obsidian-vault" -g "*.md"

# Find bundle index files
fd "index.md" "path/to/obsidian-vault"

Rules

• Prefer curation over reorganization.
• Do not move, rename, or delete many notes at once unless the user asks.
• Do not invent links based only on shared words.
• 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.
• 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

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.

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.

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.

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.

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.

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:

---
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
---

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/<packet>/, Projects/<project>/.

Non-bundle directories (Inbox/, Dailies/, Templates/, Clippings/) do not get index.md or log.md.

Linking Guidance

Add links only when they express one of these relationships:

• concept to broader concept
• source note to extracted idea
• project note to relevant knowledge note
• daily note to work done or ideas learned
• sibling concepts that genuinely inform one another

When linking, prefer existing notes over creating speculative new ones.

Extraction Guidance

Extract atomic notes when a note contains:

• multiple durable ideas
• a strong claim hidden in raw notes
• a reusable method, distinction, or definition
• a concept that should be linked from many places

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, 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 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. 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.

Curate an inbox batch

• process a small batch, usually 5-10 notes
• classify each note
• normalize metadata
• suggest which notes should stay raw, become source notes, or become atomic notes
• avoid large folder reshuffles unless the pattern is clear
• enumerate a small set of Inbox/ notes
• process them one at a time
• stop and summarize after each batch

Completion Criterion: Each note in the batch classified and normalized, with a summary returned after the batch.

Review recent notes

• inspect recently edited notes
• identify missing links and vague titles
• flag notes with mixed concerns
• suggest a small set of follow-up curation actions
• search by recent filenames or recent folders when file metadata is available
• keep edits conservative and return a review summary

Completion Criterion: Recently edited notes inspected, missing links and mixed concerns flagged, with a review summary returned.

Serendipity review

• choose a note from the vault
• summarize it briefly
• compare it to the user's current topic or active project
• suggest only high-confidence connections
• pick one note from a user-specified folder or from curated folders only
• avoid randomizing across obviously raw capture unless the user asks for that

Completion Criterion: One curated note chosen, briefly summarized, compared to active topic, with only high-confidence connections suggested.

Output Style

When responding to the user:

• state what kind of note you think it is
• summarize the curation changes you made or recommend
• list any extracted notes to create
• list meaningful links added or suggested
• mention any move or rename separately before doing it
• 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

If the vault structure is unclear, inspect folders and a few nearby notes before editing. If note conventions appear to conflict, follow the most local AGENTS.md instructions in scope. Don't guess at user preferences. When in doubt, ask the user before making big changes or suggesting speculative links.