# Organizing Notes

> Keeps a markdown knowledge base consistent - frontmatter on every note, controlled tags, links between related notes and entities. Use whenever creating or editing notes in a knowledge base, and when asked to clean up, normalize, or reorganize notes. Reads the knowledge base's conventions.md as the authority.

- Skill: `sawyer-middeleer/organizing-notes` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sawyer-middeleer/organizing-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sawyer-middeleer/organizing-notes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Sawyer-Middeleer (https://skillmd.com/u/sawyer-middeleer)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/sawyer-middeleer/organizing-notes

---


# Organizing Notes

Three consistency passes — frontmatter, tags, links — applied whenever a note is touched. The knowledge base's `conventions.md` is the authority; read it first. If none exists, offer `/second-brain:setting-up-knowledge-base` before proceeding.

## Frontmatter

On every note whose **content or frontmatter** you change:

1. **Frontmatter exists** — block starts `---` on line 1; add if missing
2. **`type:` matches the note's role** — per the conventions enum
3. **Keys are canonical** — migrate drifted forms (`date_created` → `created`, `last_updated` → `modified`, etc.)
4. **`modified:` bumped to today** — when you changed content or frontmatter. A pure move or rename does **not** bump `modified` (the content is unchanged); don't rewrite timestamps across files you're only relocating.

Rules: dates absolute `YYYY-MM-DD`; `tags:` always a YAML list; `snake_case` keys; don't invent metadata you can't derive.

## Tags

Tags are a controlled vocabulary — reuse before inventing.

1. Read the note's existing tags and the conventions' taxonomy
2. Apply matching namespaced tags (`area/...`, `status/...`)
3. Introduce a new tag only when ALL hold: no existing tag fits, the concept will recur across notes, and someone would actually query it
4. Never tag entities — `client/acme` is wrong; a link to the `acme` hub is right
5. Never tag what folder + title already say

## Links

Connections compound. When touching a note, look for missed link opportunities:

**Entity mentions** — first mention of any person, org, tool, or project that has a hub page gets linked (`[[Name]]` or `[Name](path)` per the conventions' link style). Don't over-link: once per note plus where prose demands it.

**Note-to-note** — when a note discusses a topic, decision, or event that lives in another note, link the other note. Search for candidates before assuming none exist.

**Hub creation** — an entity appearing in **≥3 notes** without a hub gets one: a short page (1–2 sentences of real content, not a bare stub) in the hubs folder, with the entity's obvious aliases. Then backfill links in the mentioning notes so the hub is immediately connected.

**Never link:** inside code blocks, URLs, or file paths; ambiguous names (two different "Davids" — skip rather than guess); generic capitalized words; inside existing links.

Bias conservative: a missed marginal link is cheaper than a wrong one.

## Batch cleanups

Asked to "clean up" or "normalize" the whole base:

1. **Safety pre-flight** — confirm the base is under version control with a clean working tree (`git status`), or take a backup, before any bulk write. A batch frontmatter pass is hard to undo by hand; a clean checkpoint makes it one command.
2. **Exclude off-limits paths** — always skip `.obsidian/`, `.git/`, `.trash/`, archive folders, and `templates/` (template placeholders break when frontmatter is injected), plus anything the conventions' Off-limits section names. These defaults hold even if the conventions file is silent.
3. **Inventory first** — report drifted frontmatter, orphan tags, unlinked entity mentions as counts before changing anything
4. **Confirm scope** with the user, then fix mechanically
5. **Summarize** — files touched, by which pass, what was excluded and why