How to Promote a New Domain Rule Without Breaking Ownership in jakubkrehel/skills

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 file while referencing it from verb skills using back-ticked skill names, preserving the strict one-owner-per-rule contract documented in 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#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 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/<domain-skill>/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 file stay synchronized with the entry in README.md. If the new rule impacts how the skill reports findings, modify the ## Reporting section of the same 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:

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:

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

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

| 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 — Central guide containing the Rule ownership table, skill shapes, and naming conventions.
• skills/<domain-skill>/SKILL.md (e.g., skills/better-accessibility/SKILL.md) — Home of the new domain rule; contains front-matter, principles, and reporting sections.
• skills/<verb-skill>/SKILL.md (e.g., skills/interface-review/SKILL.md) — Holds references to domain rules via back-ticked skill names.
• .claude-plugin/plugin.json and .claude-plugin/marketplace.json — Manifest files requiring validation after ownership changes.
• opencode.json — Registers the skills/ path for the Opencode loader; verify integrity when restructuring skill directories.
• 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 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 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 contains schema violations, or if the Opencode loader detects path mismatches in 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 file (e.g., 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.

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