# How to Promote a New Domain Rule Without Breaking Ownership in jakubkrehel/skills > Learn how to promote new domain rules in jakubkrehel/skills without breaking ownership. Follow simple steps to maintain the one-owner-per-rule contract and ensure smooth updates. - Repository: [Jakub Krehel/skills](https://github.com/jakubkrehel/skills) - Tags: best-practices - Published: 2026-09-12 --- **To promote a new domain rule without breaking ownership in the `jakubkrehel/skills` repository, you must add the rule to exactly one `better-*` domain skill's [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) file while referencing it from verb skills using back-ticked skill names, preserving the strict one-owner-per-rule contract documented in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md).** The `jakubkrehel/skills` repository organizes knowledge into **domain skills** (the `better-*` set) and **verb skills** (procedural tools such as `interface-review`, `variant`, `break`, and `explain-interface`). Every domain rule must belong to exactly one domain skill, and any verb skill that references that rule must treat the domain skill as the canonical owner. When you promote a new domain rule without breaking ownership, you maintain this architectural boundary and prevent rule duplication across the codebase. ## Understand the Ownership Model The repository enforces ownership through the **Rule ownership** table in [[`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md)](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md#rule-ownership). This table defines which **domain skill** owns which domain rule, ensuring that knowledge lives in exactly one location. **Domain skills** (e.g., `better-accessibility`, `better-colors`) contain prescriptive principles, exact CSS values, and ARIA patterns. **Verb skills** (e.g., `interface-review`) act as procedural interfaces that link to these rules rather than copying them. When a verb skill needs to reference a domain rule, it uses the owning skill's name in back-ticks (e.g., `` `better-accessibility` ``) to maintain the ownership chain. ## Step-by-Step Workflow to Promote a New Domain Rule Follow this exact workflow to add a rule while preserving ownership invariants. ### Identify the Correct Domain Skill Choose the `better-*` skill whose scope matches the rule's subject matter. For example, accessibility guidelines belong to `better-accessibility`, while color system rules belong to `better-colors`. The **Rule ownership** table in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md) makes these mappings explicit and serves as the source of truth for which skill owns which conceptual domain. ### Add the Rule to the Owner's SKILL.md Insert a single, prescriptive principle under a clear, sentence-case heading inside `skills//SKILL.md`. Include exact values (CSS hex codes, ARIA patterns, keyboard shortcuts) rather than vague guidance. Do **not** duplicate this rule in any other skill file. Other skills should link to this canonical location instead of copying text. ### Update the Skill Metadata and Reporting Ensure the front-matter `name` and `description` fields in the [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) file stay synchronized with the entry in [`README.md`](https://github.com/jakubkrehel/skills/blob/main/README.md). If the new rule impacts how the skill reports findings, modify the `## Reporting` section of the same [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) file to reflect the new evaluation criteria or output format. ### Reference the Rule from Verb Skills In any verb skill that needs to apply the new rule (such as `interface-review` or `break`), add a reference that points to the owning domain skill by its name using back-ticks. For example, cite `` `better-accessibility` `` when discussing keyboard navigation requirements. This creates a clear ownership chain without duplicating rule content. ### Validate Your Changes After modifying any skill files, run the Claude-plugin validation commands to verify repository invariants: ```bash claude plugin validate . claude plugin validate .claude-plugin/plugin.json ``` These commands guarantee that the ownership contracts remain intact and that no rule violations have been introduced. ## Practical Code Examples ### Adding a Domain Rule to better-accessibility Add the new rule as a principle under a descriptive heading inside [`skills/better-accessibility/SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/skills/better-accessibility/SKILL.md): ```markdown --- name: better-accessibility description: Helps your project comply with accessibility standards and best practices. --- # Accessibility ... (existing content) ## Keyboard-only navigation **Rule:** All interactive components must be reachable via the `Tab` key and activate with `Enter` or `Space`. *Do not rely on mouse-only hover states.* ``` ### Linking from interface-review Reference the canonical rule from a verb skill without duplicating its content: ```markdown --- name: interface-review description: Reviews your work across multiple categories. --- # Interface Review ... (existing content) When checking keyboard navigation, see the rule defined in `better-accessibility` (`Keyboard-only navigation`). ``` ### Updating AGENTS.md for New Domain Skills Only modify the **Rule ownership** table when introducing an entirely new domain skill category: ```markdown | Skill | Owns | |---------------------|------| | `better-newskill` | New domain rule for XYZ | ``` ## Critical Files for Ownership Management Understanding these file paths ensures you modify the correct components when promoting domain rules: - **[`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md)** — Central guide containing the **Rule ownership** table, skill shapes, and naming conventions. - **`skills//SKILL.md`** (e.g., [`skills/better-accessibility/SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/skills/better-accessibility/SKILL.md)) — Home of the new domain rule; contains front-matter, principles, and reporting sections. - **`skills//SKILL.md`** (e.g., [`skills/interface-review/SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/skills/interface-review/SKILL.md)) — Holds references to domain rules via back-ticked skill names. - **[`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json)** and **[`.claude-plugin/marketplace.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/marketplace.json)** — Manifest files requiring validation after ownership changes. - **[`opencode.json`](https://github.com/jakubkrehel/skills/blob/main/opencode.json)** — Registers the `skills/` path for the Opencode loader; verify integrity when restructuring skill directories. - **[`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml)** — Stores per-skill invocation policy; must remain consistent with front-matter `disable-model-invocation` flags. ## Summary - **Domain rules** must live in exactly one `better-*` domain skill's [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) file to satisfy the one-owner-per-rule contract. - **Verb skills** reference domain rules by back-ticked skill names (e.g., `` `better-accessibility` ``) rather than copying rule text. - **Never duplicate** rule content across multiple skills; always link to the canonical owner. - **Validate** all changes using `claude plugin validate .` to ensure ownership invariants remain intact. - Update **[`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md)** only when introducing entirely new domain skill categories, not when adding rules to existing skills. ## Frequently Asked Questions ### What happens if I accidentally duplicate a rule across multiple skills? Duplicating a rule breaks the ownership contract and creates maintenance conflicts when rules diverge. The validation scripts (`claude plugin validate`) should detect invariant violations, but manual duplication also fragments the knowledge base and violates the architectural principle that domain skills own knowledge while verb skills own procedures. ### How do I decide whether to add a rule to a domain skill or a verb skill? Add prescriptive principles (exact values, standards, patterns) to **domain skills** (`better-*`). Add procedural logic, workflows, and cross-references to **verb skills** (`interface-review`, `break`). If the content describes *what* standard to follow, it belongs in a domain skill. If it describes *how* to check or apply standards, it belongs in a verb skill that references the domain owner. ### What validation errors indicate broken ownership? The `claude plugin validate` command will fail if manifests reference non-existent skills, if [`plugin.json`](https://github.com/jakubkrehel/skills/blob/main/plugin.json) contains schema violations, or if the Opencode loader detects path mismatches in [`opencode.json`](https://github.com/jakubkrehel/skills/blob/main/opencode.json). While the validator may not catch every semantic ownership violation, it ensures structural integrity required for the ownership model to function correctly. ### Can I modify a rule owned by a different domain skill? No. You must treat the domain skill as the canonical owner. If you need to extend or alter a rule, submit changes to the owning skill's [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) file (e.g., [`skills/better-accessibility/SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/skills/better-accessibility/SKILL.md)). Verb skills and other domain skills must reference the owner by name using back-ticks rather than copying or modifying the rule text.