📦 SKILL.md

A SKILL.md is an agent-side instruction sheet. OMP indexes its frontmatter description, matches it against the live query, and injects the body into the prompt context on demand. Write it for a reader who has zero prior context and a tool budget.

1. 🧬 Anatomy

A skill is one folder under the cognitive filesystem (e.g. skills/<name>/SKILL.md) plus any assets it references. The file has four load-bearing layers:

Layer	Purpose	Failure if missing
Frontmatter	name + description drive discovery and injection matching.	Skill never triggers.
Activation	An explicit when-to-use line so the agent self-selects correctly.	Triggers on the wrong queries or not at all.
Reference body	Dense, copy-pasteable rules, tables, and templates.	Agent guesses; output drifts.
Validation	Checklists / anti-patterns the agent verifies before delivery.	No quality gate; silent regressions.

2. 🔑 Frontmatter

Only two keys are load-bearing. Keep description keyword-rich — it is the retrieval surface.

---
name: canvas-gen
description: >
  canvas-gen (JSON Canvas Generation for Quartz 5/Obsidian): Generates valid,
  visually stunning .canvas files following JSON Canvas Spec 1.0 with layout
  patterns, validation, and visual feedback loops.
globs: ["**/*.canvas"] # optional: auto-attach on matching paths
alwaysApply: false # optional: false = inject only on match
---

• 🎯 name — kebab-case, matches the folder name.
• 🎯 description — start with <name> (<Title>): then a one-sentence capability summary packed with trigger keywords.
• 🧷 globs / alwaysApply — optional auto-attach controls; omit for pure query-matched skills.

3. 🧱 Skeleton

Annotated template — strip the # comments when authoring.

---
name: my-skill
description: >
  my-skill (Human Title): one-line capability statement with searchable keywords.
---
 
# 🛠️ MY-SKILL: HUMAN TITLE
 
> **Core Directive:** the single non-negotiable outcome this skill guarantees.
 
## Activation
 
Trigger when: <explicit, comma-separated situations the agent should match>.
 
---
 
## <Topic> Reference
 
# Dense tables / type refs / config snippets. No prose padding.
 
| Field | Required | Values |
| :---- | :------- | :----- |
| ...   | ...      | ...    |
 
## Hard Rules
 
# MUST / NEVER constraints, grouped by sub-topic. This is the spine.
 
## Generation Template
 
# A runnable snippet (python/ts/yaml) the agent can copy and adapt.
 
## Validation Checklist
 
- [ ] <objective, checkable invariant>
- [ ] <second invariant>
 
## Anti-Patterns
 
| ❌ Don't         | ✅ Do Instead  |
| :--------------- | :------------- |
| <common mistake> | <correct move> |

4. 📐 Conventions

• 📦 One concern per skill. A skill that does two things matches poorly and injects noise.
• 🧊 Density over prose. Tables, checklists, and anti-pattern grids beat paragraphs — the agent scans, it doesn’t read.
• 🔁 Make rules checkable. Every Hard Rule should map to a Validation Checklist item the agent can self-verify.
• 🧪 Ship a template. A copy-pasteable skeleton (see canvas-gen’s generation template) removes ambiguity faster than any explanation.
• 🚫 Anti-patterns are mandatory. The ❌ Don't / ✅ Do grid prevents the most expensive failures.
• 📎 Reference real examples. Embed a condensed canonical artifact so the agent has a concrete shape to imitate.

5. 🔗 Related

• 🤖 AGENTS.md anatomy — repo-scoped instruction files.
• 🔤 Ecosystem lingo — Skill, Rule, Profile defined.
• 📄 llms.txt — site-wide LLM export.