obsidian-document-ai-skills

name	obsidian-document-ai-skills
description	Document AI agent skills and hooks in the Obsidian vault with concept and implementation notes. Use when the user says "document this skill", "document this hook", "write up the skill", "add skill docs", "document skill to vault", "document hook to vault", or asks to create vault documentation for a skill or hook they've built or are building.

Document AI Skills & Hooks

You create structured documentation for AI agent skills and hooks in the user's Obsidian vault, following the concept/implementation pattern in 2a/ai-tooling/.

Skills are user-invocable prompt-driven workflows (e.g., /commit, /enrich-daily). Hooks are automatic scripts triggered by agent lifecycle events (e.g., PostToolUse validation).

Both use the same documentation pattern: one concept note (what & why) + implementation notes per agent (how). The ai-trigger_type frontmatter field distinguishes them: skill or hook.

Folder Structure

2a/ai-tooling/
├── ai-tooling.md              (MOC — index of all automations)
├── concepts/
│   └── cpt-<name>.md         (agent-agnostic: what & why)
└── tools/
    ├── claude/
    │   └── cc-<name>.md      (Claude Code implementation)
    └── opencode/
        └── oc-<name>.md      (opencode implementation)

File Naming

Prefix files with a slug indicating their type:

• cpt- — concept (agent-agnostic design)
• cc- — Claude Code implementation
• oc- — opencode implementation

This ensures files are distinct in fuzzy find and grep results without needing the full path.

Wikilinks

Always use bare wikilinks — no paths. Obsidian resolves by filename.

• Good: [[cc-enrich-daily]]
• Bad: [[2a/ai-tooling/claude/cc-enrich-daily]]

The prefixed filenames make bare links unambiguous.

Workflow

1. Gather details

Read the source files:

• Vault-local skills: .claude/skills/<name>/
• Global skills: ~/.claude/skills/<name>/
• Hooks: .claude/hooks/<script> + .claude/settings.json hook config
• opencode: the relevant config/prompt files

Ask the user to clarify anything not obvious from the source.

2. Create the concept note (cpt-<name>.md)

---
Created: <current datetime YYYY-MM-DDTHH:mm:ss>
status: active
Area: ai-tooling
ai-trigger_type: <skill | hook>
tags:
  - ai-tooling
  - ai-tooling/concept
fileClass:
Links:
  - "[[cc-<name>]]"
---
# <name>

<1-2 sentence description of what it does>

## Problem

<What gap does this fill? Why does it exist?>

## Data Sources

| Source | Signal | How |
|--------|--------|-----|
| ... | ... | ... |

## Output Format

<What does it produce? Where does it go?>

## Design Decisions

<Key architectural choices and their rationale. Use H3 subsections for each decision.>

## Implementations

- [[cc-<name>|Claude Code]] — <status>, uses `<path>`

Omit sections that don't apply (e.g., Data Sources for something that doesn't harvest data). Don't force the template — adapt it.

3. Create the implementation note (cc- or oc-<name>.md)

---
Created: <current datetime YYYY-MM-DDTHH:mm:ss>
status: active
Area: ai-tooling
tags:
  - ai-tooling
  - ai-tooling/claude   # or ai-tooling/opencode
fileClass:
Links:
  - "[[cpt-<name>]]"
---
# <name> — <Agent> Implementation

## Location

<File tree or paths of the source files>

## How It Works

<Numbered steps: what happens when it runs>

## Dependencies

<What does it need installed/available?>

## Changelog

- **YYYY-MM-DD**: <What changed and why>

4. Update the MOC

Add a row to the appropriate concern group in 2a/ai-tooling/ai-tooling.md:

| [[cpt-<name>\|<name>]] | <1-line description> | [[cc-<name>\|cc]] | — |

Concern groups: Vault Operations, Vault Synthesis, Dev Workflow, Guardrails, Meta.

Guidelines

• Read the source first — don't guess what a skill or hook does. Read the SKILL.md, scripts, settings.json hook config, etc.
• Synthesize — vault notes should explain what and why at a higher level than the source. Don't just copy.
• Cross-link — concept links to implementations, implementations link back to concept.
• One concept, multiple implementations — if the same automation exists in both Claude and opencode, they share one concept note.
• ai-trigger_type — set to skill or hook on concept notes. This is the only structural difference between the two.
• Changelog — track significant changes in implementation notes.