| name | tag-system |
| description | Documents the deterministic tag-driven skill/hook routing system. Tags on tasks and units determine which skills and hooks are loaded at each pipeline phase — no conditional text needed. Use to understand how tags work, what tags exist, and how to tag tasks. |
| tags | ["design"] |
Tag System
Overview
The tag system replaces static "if this unit touches UI" conditional text in prompt hooks with deterministic tag matching. Every task and unit carries tags that describe what kind of work it is. Every skill and hook declares which tags it applies to. The tag resolver matches them at runtime — only relevant guidance reaches the agent.
Without tags:
Hook says: "If this unit touches UI, do X. If backend, ignore."
(Agent must read and follow conditional logic — fragile)
With tags:
Unit has tags: [ui, form]
Hook has tags: [ui]
Resolver: tags match → hook loaded. Backend units never see it.
(Pure deterministic matching — no conditionals)
Core Tag Taxonomy
These are the standard tags recognized by the system. Projects can add their own.
| Tag | When to Use | Skills It Activates |
|---|
ui | Components, screens, forms, any user-facing surface | ui-design, ux-pattern-audit |
frontend | Frontend code (JS/TS/CSS/HTML) | ui-design |
backend | Server-side logic, APIs, services | — (universal skills apply) |
api | API endpoints, contracts, serialization | — |
db | Database schemas, queries, migrations | — |
data | Data processing, transforms, ETL | — |
auth | Authentication, authorization, permissions | security-and-hardening |
security | Security hardening, vulnerability fixes | security-and-hardening |
config | Configuration, environment, setup | — |
docs | Documentation, ADRs, guides | documentation-and-adrs |
infra | Infrastructure, CI/CD, git, deployment | git-workflow-and-versioning, ci-cd-and-automation |
test | Test infrastructure, fixtures, test tooling | test-driven-development |
migration | Data/schema migrations | — |
cli | CLI tools, scripts, automation | — |
design | UX design artifacts, wireframes, patterns | ux-pattern-audit |
Universal skills (no tags — always loaded): spec-driven-development, spec-review-and-quality, planning-and-task-breakdown, code-review-and-quality, code-simplification, incremental-implementation, debugging-and-error-recovery, orchestrator
How to Tag Tasks
In tasks.md, annotate each task with its tags:
## Task [1]: Login form UI (tags: ui, auth)
## Task [2]: Token validation API (tags: backend, api, security)
## Task [3]: User table migration (tags: db, migration)
## Task [4]: Setup CI pipeline (tags: infra)
If a task has no explicit tags, the system infers them from the file paths in its "Files likely touched" section, using project-specific tag→path mappings from solo.yaml (pipeline section).
Tagging Guidelines
- Be specific — a task that touches both UI and backend should list both:
(tags: ui, backend)
- Don't over-tag —
(tags: ui, frontend) is redundant since ui implies frontend. Pick the most descriptive.
- Default for unspecified — if unsure, omit tags. The unit will still get universal skills.
- Per-project tags — projects can define custom tags in
solo.yaml (pipeline section) → tags.categories
How Skills Declare Tags
Each SKILL.md has a tags field in its YAML frontmatter:
---
name: ui-design
description: Guides UI design...
tags: [ui, frontend]
---
- tags — the kinds of units this skill is relevant for
- No tags field — the skill is universal (always loaded, like methodology skills)
- Tag
[all] — treated the same as no tags (universal)
How Hooks Declare Tags
Each .prompt.md hook file has a tags field in its YAML frontmatter:
---
tags: [ui]
---
## Content here — only injected when unit has `ui` tag
How the Tag Resolver Works
The solo-tags CLI (solo/tags.py) uses simple set logic:
- SKILL.md with no
tags field → always returned (universal)
- SKILL.md with
tags: [ui, frontend] → only returned when the unit has BOTH ui AND frontend tags
- Hook with no
tags field → always injected (universal)
- Hook with
tags: [ui] → only injected when the unit has ui tag
- Multiple matches → all matching skills/hooks are returned (union)
- No matches → only universal skills/hooks are returned
Tag Inference from File Paths
When a unit has code deliverables (file paths) but no explicit tags, classifyTags() infers tags from path prefixes:
{
"tags": {
"categories": {
"ui": { "paths": ["apps/portal/", "apps/web/"] },
"backend": { "paths": ["packages/", "apps/api/"] },
"db": { "paths": ["migrations/", "prisma/"] }
}
}
}
A unit delivering apps/portal/src/SearchPage.tsx would auto-infer ui tag.
Unit-to-Unit Flow
1. PROPOSE: Tasks created with tags (or inferred from paths)
2. SHIP-PLAN: Tags inherited from covered tasks + code file paths
3. SHIP-CODE: Per unit, resolver loads matching skills + hooks
If a unit covers tasks ["1", "3"], where task 1 has tags [ui, auth] and task 3 has [backend], the unit's tags are the union: [ui, auth, backend].
Custom Project Tags
Projects can extend the tag taxonomy in solo.yaml (pipeline section):
{
"tags": {
"categories": {
"billing": { "paths": ["apps/billing/"] },
"ml": { "paths": ["packages/ml/"] }
}
}
}
Then create a SKILL.md for the custom skill with tags: [billing] and place it in the project's .claude/skills/ directory. The resolver will discover and match it automatically.
