tag-taxonomy

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

.agents/skills/claude-history-ingest

.agents/skills/code-understand

.agents/skills/codex-history-ingest

.agents/skills/copilot-history-ingest

.agents/skills/cross-linker

Audit 0.4.1 · source sha 8bcf57f68146 · 31 Oct 2026Report an issue or request a re-scan

• Publisherar9av GitHub userOwner of the repository this skill is read from
• Source folderar9av/obsidian-wiki/.skills/tag-taxonomyThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict8bcf57f68146A new audit runs when the source changes
• Repository statusNot archivedLast push 4 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Apply and maintain the wiki's controlled tag vocabulary. Use for choosing, normalizing, auditing, or extending tags when creating or updating wiki pages; consult the taxonomy before assigning tags.

---
name: tag-taxonomy
description: >
  Apply and maintain the wiki's controlled tag vocabulary. Use for choosing, normalizing, auditing, or extending tags when creating or updating wiki pages; consult the taxonomy before assigning tags.
---

# Tag Taxonomy — Controlled Vocabulary for Wiki Tags

You are enforcing consistent tagging across the wiki by normalizing tags to a controlled vocabulary.

## Before You Start

1. **Resolve config** — follow the Config Resolution Protocol in `llm-wiki/SKILL.md` (inline `@name` override → walk up CWD for `.env` → global config → prompt setup). This gives `OBSIDIAN_VAULT_PATH`
2. Read `$OBSIDIAN_VAULT_PATH/_meta/taxonomy.md` — this is the canonical tag list
3. Read `index.md` to understand the wiki's scope

## The Taxonomy File

The canonical tag vocabulary lives at `$OBSIDIAN_VAULT_PATH/_meta/taxonomy.md`. It defines:

- **Canonical tags** — the tags that should be used
- **Aliases** — common alternatives that should be mapped to the canonical form
- **Rules** — max 5 tags per page, lowercase/hyphenated, prefer broad over narrow
- **Migration guide** — specific renames for known inconsistencies

**Always read this file before tagging.** It's the source of truth.

## Reserved System Tags

`visibility/` is a reserved tag group with special rules. These tags are **not** domain or type tags and are managed separately from the taxonomy vocabulary:

| Tag | Purpose |
|---|---|
| `visibility/public` | Explicitly public — shown in all modes (same as no tag) |
| `visibility/internal` | Team-only — excluded in filtered query/export mode |
| `visibility/pii` | Sensitive data — excluded in filtered query/export mode |

**Rules for `visibility/` tags:**
- They do **not** count toward the 5-tag limit
- Only one `visibility/` tag per page
- Omit entirely when content is clearly public — no tag needed
- Never add `visibility/internal` just because content is technical; use it only for genuinely team-restricted knowledge
- When running a tag audit, report `visibility/` tag usage separately — do not flag them as unknown or non-canonical

When normalizing tags, leave `visibility/` tags untouched — they are not subject to alias mapping.

## Mode 1: Tag Audit

When the user wants to see the current state of tags:

### Step 1: Scan all pages

```
Glob: $VAULT_PATH/**/*.md (excluding _archives/, .obsidian/, _meta/)
Extract: tags field from YAML frontmatter
```

### Step 2: Build a tag frequency table

For each tag found, count how many pages use it. Flag:

- **Unknown tags** — not in the taxonomy's canonical list
- **Alias tags** — using an alias instead of the canonical form (e.g., `nextjs` instead of `react`)
- **Over-tagged pages** — pages with more than 5 tags
- **Untagged pages** — pages with no tags or empty tags field

### Step 3: Report

```markdown
## Tag Audit Report

### Summary

- Total unique tags: 47
- Canonical tags used: 32
- Non-canonical tags found: 15
- Pages over tag limit (5): 3
- Untagged pages: 2

### Non-Canonical Tags Found

| Current Tag | → Canonical | Pages Affected |
| ----------- | ----------- | -------------- |
| `nextjs`    | `react`     | 4              |
| `next-js`   | `react`     | 2              |
| `robotics`  | `ml`        | 1              |
| `windows98` | `retro`     | 3              |

### Unknown Tags (not in taxonomy)

| Tag          | Pages | Recommendation                   |
| ------------ | ----- | -------------------------------- |
| `flutter`    | 1     | Add to taxonomy under Frameworks |
| `kubernetes` | 2     | Add to taxonomy under DevOps     |

### Over-Tagged Pages

| Page                   | Tag Count | Tags                 |
| ---------------------- | --------- | -------------------- |
| `entities/jane-doe.md` | 8         | ai, ml, founder, ... |
```

## Mode 2: Tag Normalization

When the user wants to fix the tags:

### Step 1: Run audit (above)

### Step 2: Apply fixes

For each page with non-canonical tags:

1. Read the page
2. Replace alias tags with their canonical form from the taxonomy
3. If page has > 5 tags, suggest which to drop (keep the most specific/relevant ones)
4. Write the updated frontmatter

**Example:**

```yaml
# Before
tags: [nextjs, ai, ml-engineer, windows98, creative-coding, game, 8-bit, portfolio]

# After
tags: [react, ai, ml, retro, generative-art]
```

### Step 3: Handle unknowns

For tags that aren't in the taxonomy and aren't aliases:

- If the tag is used on 2+ pages, suggest adding it to the taxonomy
- If the tag is used on 1 page, suggest replacing it with the closest canonical tag
- Ask the user before making changes to unknown tags

### Step 4: Update taxonomy

If new canonical tags were agreed upon, append them to `_meta/taxonomy.md` in the correct section.

## Mode 3: Tagging a New Page

When you're creating a wiki page and need to choose tags:

1. Read `_meta/taxonomy.md`
2. Select up to 5 tags that best describe the page:
   - 1-2 **domain tags** (what subject area)
   - 1 **type tag** (what kind of thing)
   - 0-1 **project tags** (if project-specific)
   - 0-1 additional descriptive tags
3. Use only canonical tags — never aliases
4. If no existing tag fits, check if it's worth adding to the taxonomy

## Mode 4: Adding a New Tag

When the user wants to add a tag to the vocabulary:

1. Check if an existing tag already covers the concept (suggest it if so)
2. If genuinely new, determine which section it belongs in (Domain, Type, Project)
3. Add it to `_meta/taxonomy.md` with:
   - The canonical tag name
   - What it's used for
   - Any aliases to redirect

## After Any Tag Operation

One locked call updates the log, the index (tags appear in index entries), and the hot cache:

```bash
# audit
obsidian-wiki memory sync TAG_AUDIT \
  tags_normalized=<N> unknown_tags=<M> pages_modified=<P> \
  --takeaways "Tag audit: normalized 14 tags across 28 pages; 2 new canonical tags added."

# normalization
obsidian-wiki memory sync TAG_NORMALIZE \
  tags_renamed=<N> pages_modified=<M> new

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/ar9av/obsidian-wiki
git -C obsidian-wiki checkout 8bcf57f68146

Works in

1. 2026-10-31
   !CAUTION B 89 / 100

   first audit · source 8bcf57f68146

Questions about tag-taxonomy

• github.com/ar9av/obsidian-wiki/tree/main/.skills/tag-taxonomy — the audited source at commit 8bcf57f68146 and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology