# What Is the Authoring Contract for jakubkrehel/skills? > Discover the authoring contract for the jakubkrehel/skills repository. Learn how it ensures auto-discoverable, deterministically invocable, and machine-readable skills for automated agents like Claude Code. - Repository: [Jakub Krehel/skills](https://github.com/jakubkrehel/skills) - Tags: documentation - Published: 2026-09-12 --- **The authoring contract for jakubkrehel/skills is a strict set of structural, stylistic, and procedural rules defined in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md) that ensures every skill is auto-discoverable, deterministically invocable, and machine-readable by automated agents like Claude Code and Opencode.** The **jakubkrehel/skills** repository is a documentation-only collection of design-review "skills" consumed by automated agents. To guarantee consistent discovery and predictable behavior, every file must adhere to a rigorous **authoring contract** enforced through repository structure and validation rules. This contract ensures that user-invoked skills cannot accidentally trigger other user-invoked skills and that all prose remains future-proof as the repository evolves. ## Core Structural Requirements Every skill must follow a strict directory and file layout to enable auto-discovery without additional manifest changes. ### Directory and File Layout Each skill lives in `skills//` with a [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) entry point and optional supporting `.md` files. According to the source code layout documented in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md), this structure allows the `skills` CLI and other agents to discover capabilities automatically. ### Frontmatter Standards Every [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) must contain YAML frontmatter with two required fields: - `name`: Must match the directory name exactly (e.g., `better-interface` for `skills/better-interface/`) - `description`: A concise description that must appear verbatim in the top-level [`README.md`](https://github.com/jakubkrehel/skills/blob/main/README.md) For example, in [`skills/better-interface/SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/skills/better-interface/SKILL.md), the frontmatter appears as: ```markdown --- name: better-interface description: Provides guidelines for interface design reviews. --- ``` The description line in this frontmatter must match the corresponding line in [`README.md`](https://github.com/jakubkrehel/skills/blob/main/README.md) to maintain synchronization across the repository. ## Stylistic and Editorial Constraints The contract enforces specific prose standards to ensure machine readability and consistency across all skills. ### Heading and Formatting Rules According to the **Authoring conventions** section in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md), all headings must use: - **Sentence case** capitalization - No serial commas - No em-dashes - Avoidance of mid-sentence colons ### The 30-Word Sentence Limit Under the **Four checks after an edit** section in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md), no sentence may exceed 30 words (code spans count as one word). This constraint ensures clarity and prevents complex syntactic structures that could confuse automated parsing. ### Content Uniqueness and Pruning The contract mandates **one-statement-per-rule**: a rule may be expressed only once across the repository, and duplicates are removed. Additionally, editors must remove any statement that does not add a new instruction, fact, or number, prioritizing pruning over word count. ## Invocation Policy and Security The repository distinguishes between user-invoked and model-invoked skills through strict frontmatter and policy configurations to prevent accidental invocation chains. ### User-Invoked Skill Restrictions Four specific skills are designated as user-invoked: `interface-review`, `variant`, `break`, and `explain-interface`. These must include `disable-model-invocation: true` in their frontmatter: ```markdown --- name: variant description: Generates component variants. disable-model-invocation: true --- ``` Additionally, these skills must set `policy.allow_implicit_invocation: false` in [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml) to block accidental model invocation chains. ### Model-Invoked Skills All other skills in the repository are model-invoked only and do not require the `disable-model-invocation` flag, allowing agents to invoke them automatically during design review workflows. ## Content Specifications and Calibration Domain skills must include specific content sections that standardize how knowledge is presented and consumed. ### Calibration Lines Every skill must include 1–2 sentences stating how "hard to press" the rule is—distinguishing between exact quantitative values and design heuristics. These calibration lines appear immediately after the introductory paragraph: > **Calibration** – This rule applies only when the component is rendered at ≥ 1 rem font size. ### Rule Ownership and Cross-References Each domain rule lives in exactly one skill. The **Rule ownership** table in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md) tracks this mapping. Cross-skill references must use back-ticks with the skill name (e.g., `` `better-interface` ``) rather than relative links, ensuring stable semantics as files move. ### Review Reporting Format Domain skills expose a `## Reporting` section containing structured feedback templates. The `better-interface` skill provides the orchestration format in [`better-interface/review-format.md`](https://github.com/jakubkrehel/skills/blob/main/better-interface/review-format.md), which defines how findings, severity levels, and fixes should be tabulated across all skills. ## Version Control Requirements Any change under `skills/` must be accompanied by a version bump in [`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json). This requirement ensures that automated agents can detect when skill definitions have changed and invalidate cached interpretations accordingly. ## Practical Implementation Example Below is a minimal skeleton for a new domain skill (`better-example`) that satisfies the authoring contract: ```markdown --- name: better-example description: Provides guidelines for example-style components. --- # Better Example A short two-sentence opener that tells the user what the skill does. > **Calibration** – This rule applies only when the component is rendered at ≥ 1 rem font size. ## Example Rule **Use a neutral colour palette** – always start from the `gray-scale` token set. ## Reporting | Finding | Severity | Fix | |---------|----------|-----| | Non-neutral colour used | ❗️ | Replace with a token from `gray-scale`. | ``` This example demonstrates proper frontmatter, sentence-case headings, calibration placement, and the required reporting section. ## Summary - The **authoring contract** is defined primarily in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md) and governs every file in the `skills/` directory. - Skills must reside in `skills//` with matching frontmatter `name` fields and synchronized descriptions in [`README.md`](https://github.com/jakubkrehel/skills/blob/main/README.md). - **User-invoked skills** (`interface-review`, `variant`, `break`, `explain-interface`) require `disable-model-invocation: true` and `policy.allow_implicit_invocation: false` in [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml). - Content must follow **sentence-case** headings, **no serial commas**, and a strict **30-word sentence limit**. - Every skill needs **calibration lines** stating rule applicability and a `## Reporting` section for structured feedback. - Changes to skills require a **version bump** in [`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json). ## Frequently Asked Questions ### What happens if I forget to bump the version in plugin.json? Automated agents may cache stale skill definitions, leading to unpredictable behavior where old rules are applied or new rules are ignored. The version field in [`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json) acts as a cache invalidation mechanism; without incrementing it, the `skills` CLI and Claude Code may not detect your changes. ### How do I cross-reference rules between different skills? Use back-ticks with the exact skill name, such as `` `better-interface` ``, rather than relative file paths or links. This convention, documented in the **Rule ownership** table in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md), ensures that references remain valid even if files are reorganized within the repository structure. ### What is the difference between user-invoked and model-invoked skills? **User-invoked skills** (`interface-review`, `variant`, `break`, `explain-interface`) are triggered directly by human users and must include `disable-model-invocation: true` to prevent accidental agent loops. **Model-invoked skills** are called automatically by agents during design reviews and lack this restriction, allowing seamless integration into automated workflows. ### Where is the official authoring contract documented? The primary source is the **Authoring conventions** section in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md) at the repository root. For Claude-specific agent behavior, consult [`CLAUDE.md`](https://github.com/jakubkrehel/skills/blob/main/CLAUDE.md), which mirrors the contract with agent-specific implementation details. The **Rule ownership** table and **Four checks after an edit** section in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md) provide the definitive enforcement criteria.