cc-os/plugins/os-vault/skills/design-template/SKILL.md

description
Design SecondBrain note-type templates and create new note types — the repeatable 4-step template-design process and the full new-type-creation lifecycle

Use this skill when designing or revising the structure of SecondBrain note types — either designing a template for an existing type or introducing a brand-new type to the vault.

These templates govern notes that are injected into AI context mid-task, repeatedly, across every project, indefinitely. Every section is a recurring token tax. The governing rule for every decision in this skill:

The burden of proof is on inclusion. A section exists only if you can name a consumer who acts differently because it's there.

This is the injection-economics filter. A section earns its place only if it pays for the tokens it costs when injected. Sections that fail the filter are removed, not commented out.

Routing — pick the workflow

Decide by context:

• Template design — you have a note type (existing or just-defined) and need to design or revise its template. → Use the 4-step template-design process below.
• New-type creation — the vault needs a type that doesn't exist yet. → Use the new-type-creation lifecycle below, which delegates to the template-design process for the template itself.

If unsure: if the type already exists in vault-conventions.md, you're doing template design. If you're recognizing a gap and proposing a new type, you're doing new-type creation.

Template design — the 4-step process

Run this for any note-type template, new or revised.

1. Model the consumers

Write down who reads this type and the one action each takes. Grab or construct one exemplar — N=1, even synthetic, is enough; the process does not require a corpus.

2. Extract the minimal body shape

Name 2–4 body sections, ordered action-first → why/when → caveats-last. For each candidate section, write one line:

[consumer] acts differently because this section is here.

No line = cut the section. This is the injection-economics filter in practice. Add a subtype variant only if a real variant needs a genuinely different core shape.

3. Draft the fillable skeleton

Assemble:

• the fixed frontmatter block (per the authoritative schema in vault-conventions.md),
• an H1,
• each section as a header with a one-line inline instruction (what goes here + target density),
• an abbreviated filled example showing the target density.

4. Dogfood and cut

Fill the template with the exemplar. Cut any empty or padded section; tighten any ambiguous instruction; re-fill. Done when the exemplar fills the template with no empty sections and no padding. This step catches paper-good/practice-ignored structure before it ships.

New-type creation lifecycle

Adding a new type to the vault. Delegates to the template-design process above for the template itself.

1. Recognize the trigger. What signals a type gap? The SessionEnd catch-all surfacing something that doesn't fit an existing type; repeated in-session workarounds for the same structural problem; N≥3 real instances exist that share structure.
2. Collect N≥3 real examples (or construct synthetic ones).
3. Define the question frame the type answers (the one-line "When I encounter X, what do I need?" question).
4. Follow the template-design process above to produce the template.
5. Add the type definition to vault-conventions.md.
6. Create the template file in _templates/.
7. Author the first 2–3 notes using the template.
8. Dogfood critique — the template already bakes this in via Step 4 of the design process.
9. Refine based on findings.

Key design decisions

These are baked into the process above; keep them in mind when applying it.

• Frontmatter and body serve different consumers. Frontmatter (summary + tags) serves the scanning human and the recall AI. The body serves only two consumers: the injected AI mid-task and the executing human. Both want the actionable core up front; they differ only in how far they read. One artifact, progressive disclosure, different stopping points.
• One shared spine, three type-specific body shapes. Every template follows the same spine: frontmatter → H1 → actionable core → why/when → caveats. The three types (convention, reference, howto) differ only in their body shape on top of that spine.
• Subtypes are body variants, never separate templates. A subtype is a variant within a template's body, not its own template file. Add one only when a real variant needs a genuinely different core shape.

Anti-patterns

The process must guard against these. Each is something the template-design steps actively prevent:

• Section inflation — adding sections "for completeness." Every section must pass the injection-economics filter (Step 2). If no consumer acts differently, cut it.
• Vague headers — ## Notes, ## Details, and similar. A header must name what it holds.
• Body duplicating frontmatter — the body must not restate summary or tags. Frontmatter serves the scanning human and recall AI; the body serves the injected AI and executing human.
• Paper-good / practice-ignored structure — a template that looks clean but doesn't fill cleanly. Caught by the dogfood step (Step 4).
• Convention stated without its boundary — a convention note that gives the rule but not where it stops applying (the exceptions / anti-patterns).
• Smuggling project narrative — episodic, project-specific story content belongs in memsearch, not SecondBrain. Templates should make this hard to do.