obstagger

Warning

TEST ON A VAULT COPY FIRST. This skill writes frontmatter directly to notes in the vault it's pointed at, including destructive-in-effect tag/taxonomy changes across an entire folder tree in batch mode. Point it at a copy of your vault before running it against the real thing. Use at your own discretion. --yolo raises the stakes further — it overwrites existing frontmatter values without asking, so test it especially carefully before pointing it at a real vault.

A Claude Code skill that automatically fills out YAML frontmatter in Obsidian notes. Given a single note or a folder, it analyzes note content and assigns taxonomy fields (context, type, subtype, subsubtype) and tags based on a living schema file inside the vault. The skill manages and maintains that schema over time — proposing and adding new taxonomy entries and tags as it encounters content that doesn't fit.

Highlights

• Works with any vault — asks which vault (and schema filename) to use, remembering the last one as the default for next time
• Schema-driven — every tagging decision is guided by the vault's own living taxonomy file, not hardcoded rules
• Self-extending — proposes and writes new taxonomy entries and tags to the schema when it encounters content that doesn't fit
• Schema bootstrapping — --updatetags builds a schema from scratch by analyzing a vault's existing notes, or proposes additions to an existing one
• Non-destructive — never silently overwrites existing frontmatter values; asks for confirmation before changing a field that's already set (unless --yolo is passed)
• Single note or batch — processes one file or an entire folder tree recursively

Installation

From the mackayi marketplace (recommended)

/plugin marketplace add keithmackay/mackayi
/plugin install obstagger@mackayi

Claude Code

cp -r /path/to/obstagger/skill/ ~/.claude/skills/obstagger/

Or symlink:

ln -s /path/to/obstagger/skill/ ~/.claude/skills/obstagger

Then invoke with: /obstagger

Codex

Place the plugin directory where Codex can find it, then add an entry to your marketplace:

~/.agents/plugins/marketplace.json (create if absent):

{
  "name": "personal",
  "interface": { "displayName": "Personal Plugins" },
  "plugins": [
    {
      "name": "obstagger",
      "source": { "source": "local", "path": "/path/to/obstagger/skill/" },
      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
      "category": "Productivity"
    }
  ]
}

Antigravity

Global install (all workspaces):

cp -r /path/to/obstagger/skill/ ~/.gemini/antigravity/skills/obstagger/

Workspace install (current project only):

cp -r /path/to/obstagger/skill/ .agents/skills/obstagger/

The root SKILL.md has no Claude Code-specific metadata, so it is used as-is — no separate Antigravity variant is needed.

Skills are auto-discovered. You can also mention the skill by name to force activation.

Gemini CLI

Gemini CLI installs extensions directly from GitHub:

gemini extensions install https://github.com/keithmackay/obstagger

To update:

gemini extensions update obstagger

The skill is auto-discovered from GEMINI.md after installation.

Requirements: Claude Code CLI (or Codex/Antigravity/Gemini CLI) installed and configured.

Compatibility

Feature	Claude Code	Codex	Antigravity	Gemini CLI
Core skill	✅	✅	✅	✅
Sub-documents (references/)	✅	✅	✅	✅

No Claude Code-specific frontmatter (metadata, retrieval, tags) or subagent dispatch is used by this skill, so there are no platform gaps to document — it ports cleanly to all four platforms.

Legend: ✅ Supported · ❌ Not supported

References

• Claude Code Skills: https://code.claude.com/docs/en/skills
• Claude Code Complete Guide (PDF): https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
• Codex Plugins: https://developers.openai.com/codex/plugins/build
• Antigravity Skills: https://antigravity.google/docs/skills
• Gemini CLI Extensions: https://github.com/google-gemini/gemini-cli/blob/main/docs/extension.md
• Agent Skills open standard: https://agentskills.io/home

Usage

Every run starts by asking which vault (and schema filename) to use, defaulting to whatever was used last time — stored in state.json next to the skill.

Tag a single Obsidian note:

/obstagger /path/to/note.md

Tag all notes in a folder (recursive):

/obstagger /path/to/folder/

Build a new schema from a vault's existing notes, or propose additions to one that already exists:

/obstagger --updatetags

Print usage and take no other action:

/obstagger --help

Print installed version and check for updates, take no other action:

/obstagger --version

Tag a note or folder without being asked to confirm overwrites of existing frontmatter values:

/obstagger --yolo /path/to/note.md
/obstagger --yolo /path/to/folder/

The tagging flow will:

• Fill in missing YAML frontmatter fields (context, type, subtype, subsubtype, tags, created, and interpreter if your schema calls for it)
• Preserve all existing frontmatter — never silently overwrites values
• Ask for confirmation before changing any field that already has a value, unless --yolo is passed, in which case it overwrites immediately and logs the change in the end-of-run report
• Skip notes where content is too ambiguous to tag confidently
• Propose and add new taxonomy entries to the schema when needed
• Report a full summary at the end of every run

Schema management

Each vault keeps its own taxonomy schema — context.md by default, but any filename you choose — living inside that vault. skill/context.example.md is a format reference (per-context tables, a Known Tags section), not a schema to adopt as-is. Normal tagging runs extend the schema automatically as they go; --updatetags (full procedure in skill/references/updatetags.md) is for building one from nothing or catching it up in bulk, and always asks for approval before writing since it can propose many changes at once.

Contributing

Pull requests are welcome — fork the repo, make your change, and open a PR describing what it does and why.

Changelog

See CHANGELOG.md for release history.

License

MIT License — see LICENSE file.