# Skill Taxonomy in AGENTS.md: Domain vs. Verb Skills Explained

> Discover the skill taxonomy in AGENTS.md. Learn to distinguish between domain and verb skills, understanding their categorization and architectural separation for better organization.

- Repository: [Jakub Krehel/skills](https://github.com/jakubkrehel/skills)
- Tags: deep-dive
- Published: 2026-09-12

---

**The repository defines a strict skill taxonomy that categorizes capabilities into domain (knowledge) skills prefixed with `better-` and verb (procedure) skills named by action, enforcing architectural separation through frontmatter flags and directory structure.**

The **skill taxonomy** implemented in `jakubkrehel/skills` creates a clear distinction between *what* a skill knows and *how* it acts. Defined primarily in **[AGENTS.md](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md)** (lines 15–68), this taxonomy governs how AI agents interact with design domains like typography, color, and layout. Every skill in the repository follows strict naming conventions and ownership rules that determine its invocation pattern and responsibilities.

## Understanding the Skill Taxonomy Categories

The taxonomy divides all capabilities into two fundamental categories with distinct architectural roles.

### Domain (Knowledge) Skills

**Domain skills** hold factual knowledge about specific design disciplines. They expose principles, rules, and best practices that other skills can reference during execution.

- **Naming convention**: Prefixed with `better-` (e.g., `better-typography`, `better-colors`, `better-layout`)
- **Invocation**: Model-invoked and can be referenced by verb skills
- **Purpose**: Provide encyclopedic knowledge about typography systems, color theory, accessibility standards, and UI patterns

### Verb (Procedure) Skills

**Verb skills** perform concrete actions against codebases or designs. They orchestrate workflows rather than store static knowledge.

- **Naming convention**: Named by the action performed (e.g., `interface-review`, `variant`, `break`, `explain-interface`)
- **Invocation**: User-invoked only; marked with `disable-model-invocation: true` to prevent automatic calling
- **Purpose**: Execute reviews, generate design variants, test component robustness, or explain interface structures

## Complete Skill Inventory in AGENTS.md

The "Rule ownership" table in **AGENTS.md** (starting at line 55) enumerates every skill and its specific responsibilities:

| Skill | Owns |
|------|------|
| `better-interface` | Review orchestration, severity escalation, remediation ordering, coverage, finding cap, final verdict |
| `interface-review` | Change-scope resolution, blast-radius calculation, finding classification, change-scoped report format |
| `variant` | Design-exploration axes, harness generation, trade-off table, promotion logic |
| `break` | Robustness-testing scenario definition, visual harness, render-and-observe rule, outcome classification |
| `explain-interface` | Interface scoping, layer search, evidence tiering, safe handling of fetched content |
| `better-accessibility` | Semantic HTML, keyboard focus, accessible names, form handling, assistive-technology requirements |
| `better-layout` | Spatial grouping, alignment, responsive structure, logical CSS properties, RTL behavior |
| `better-writing` | Source wording, terminology, voice, tone, label wording, empty-state copy |
| `better-typography` | Text rendering, font behavior, wrapping mechanics, punctuation, bidi handling |
| `better-colors` | Palette construction, token naming, color notation, gamut, contrast measurement, remediation |
| `better-ui` | Optional visual polish: surfaces, icons, motion aesthetics |

## How the Taxonomy Is Enforced

The repository implements three enforcement mechanisms to maintain taxonomy integrity across the codebase.

### Frontmatter Validation

Every skill file ([`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md)) contains a `name` field that must match its directory name. This ensures the taxonomy is physically reflected in the file system at `skills/<skill-name>/`.

### Invocation Rules in agents/openai.yaml

Verb skills are configured in `skills/<skill-name>/agents/openai.yaml` with strict flags to prevent automatic invocation:

- `disable-model-invocation: true`
- `policy.allow_implicit_invocation: false`

Domain skills omit these flags, allowing model-driven references from verb skills.

### Directory Layout

All skills live under `skills/<skill-name>/`, creating a predictable structure that mirrors the taxonomy classification. Domain skills cluster under `better-*` directories while verb skills use action-oriented names.

## Code Examples

### Domain Skill Frontmatter (better-typography)

```yaml
---
name: better-typography
description: Visual text rendering, font behavior, wrapping mechanics, punctuation and bidi handling
---

```

*The `name` matches the directory `skills/better-typography/` and follows the domain skill naming convention.*

### Verb Skill Frontmatter (interface-review)

```yaml
---
name: interface-review
description: Review a change-set and classify findings
disable-model-invocation: true
---

```

*The `disable-model-invocation` flag enforces the user-invoked nature of verb skills, preventing other agents from calling this skill automatically.*

### CLI Invocation of Verb Skills

```bash
npx skills add jakubkrehel/skills   # install the skill collection

skills interface-review <path-to-diff>

```

*The CLI uses the verb-skill name (`interface-review`) to initiate workflows, which then route to domain skills based on the taxonomy defined in AGENTS.md.*

## Summary

- The **skill taxonomy** in `jakubkrehel/skills` separates **domain skills** (prefixed with `better-`) from **verb skills** (action-named).
- **Domain skills** store knowledge about typography, color, layout, accessibility, and UI patterns.
- **Verb skills** execute procedures like `interface-review`, `variant` generation, and `break` testing.
- The taxonomy is enforced through **frontmatter** naming, **invocation flags** in [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml), and **directory structure**.
- **AGENTS.md** serves as the canonical reference for skill ownership and responsibilities (lines 15–68).

## Frequently Asked Questions

### What is the difference between domain and verb skills in the taxonomy?

Domain skills (`better-typography`, `better-colors`) contain static knowledge about design domains and can be referenced by other skills. Verb skills (`interface-review`, `break`) perform actions and are marked with `disable-model-invocation: true` to ensure they are only called directly by users, not by other AI agents.

### How does AGENTS.md define skill responsibilities?

AGENTS.md contains a "Rule ownership" table (starting at line 55) that maps each skill to its specific responsibilities. For example, `better-accessibility` owns "Semantic HTML, keyboard focus, accessible names," while `variant` owns "Design-exploration axes, harness generation, trade-off table."

### Where are the invocation rules configured for verb skills?

Invocation rules are stored in `skills/<skill-name>/agents/openai.yaml`. Verb skills include `disable-model-invocation: true` and `policy.allow_implicit_invocation: false` to prevent automatic invocation, while domain skills allow model-driven references.

### Can I add a new skill to the taxonomy?

New skills must follow the naming conventions defined in AGENTS.md: use the `better-` prefix for domain knowledge skills, or action-based names for verb skills. Each skill requires a [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) with matching frontmatter `name` and optional [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml) configuration depending on its invocation type.