What Is the Authoring Contract for jakubkrehel/skills?

The authoring contract for jakubkrehel/skills is a strict set of structural, stylistic, and procedural rules defined in 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/<skill-name>/ with a SKILL.md entry point and optional supporting .md files. According to the source code layout documented in AGENTS.md, this structure allows the skills CLI and other agents to discover capabilities automatically.

Frontmatter Standards

Every 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

For example, in skills/better-interface/SKILL.md, the frontmatter appears as:

---
name: better-interface
description: Provides guidelines for interface design reviews.
---

The description line in this frontmatter must match the corresponding line in 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, 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, 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:

---
name: variant
description: Generates component variants.
disable-model-invocation: true
---

Additionally, these skills must set policy.allow_implicit_invocation: false in 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 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, 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. 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:

---
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 and governs every file in the skills/ directory.

• Skills must reside in skills/<skill-name>/ with matching frontmatter name fields and synchronized descriptions in 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.

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

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 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, 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 at the repository root. For Claude-specific agent behavior, consult 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 provide the definitive enforcement criteria.

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