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

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 (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) 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)

---
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)

---
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

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, 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 with matching frontmatter name and optional agents/openai.yaml configuration depending on its invocation type.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}