Rigwright

Rigwright authors and evaluates small, single-purpose skills for AI coding agents: the reusable instruction files that Claude Code and Codex load to handle one kind of task well. In practice, skill files sprawl into catch-all documents where no one can tell whether an edit helped, and each platform needs the same skill re-packaged by hand in its own format. Rigwright gives every skill one measurable outcome and its own eval set (test prompts with expected behavior), then generates the packaging for each platform from a single neutral source, validated against both platforms' native schemas.

Getting started

• Prerequisites: Python 3.12 or newer.
• Install: pip install rigwright. The CLI is published on PyPI as rigwright. See Install for the run-from-clone alternative that needs no install at all.
• Check it works: from a clone of this repository, run rigwright gate. It runs the full offline gate (contract, build, package, determinism, fixtures, and evals) and prints offline gate PASS: 8/8 commands.

Create your own skill

The installed CLI can create and validate a neutral skill in a workspace outside the Rigwright repository. It refuses to overwrite an existing skill directory and does not install, activate, or promote the result:

rigwright init-skill --workspace ../my-rigwright-skills --id changelog-check --description "Check a changelog for one required release heading." --outcome "Report whether the required heading exists."
rigwright validate-workspace --workspace ../my-rigwright-skills

The first command creates rigwright-workspace.json, src/skills/changelog-check/skill.json, and its four-case evals/evals.json. The second command applies the neutral skill, lifecycle, and eval contracts to every skill it discovers; it does not require or hardcode Rigwright's seven vendor leaves. Edit the scaffold's generated triggers, instructions, and cases to match the real workflow before treating it as a candidate. Adapter building remains a repository workflow.

One skill, end to end

Every skill is one neutral JSON record. Here is rigwright-author-skill, the skill that authors other skills (trimmed):

// src/skills/rigwright-author-skill/skill.json
{
  "id": "rigwright-author-skill",
  "intent": "Create or improve one atomic neutral skill source.",
  "outcome": "Produce one contract-valid skill, its eval set, and requested thin surface adapters.",
  "non_goals": ["Create a plugin container", "Run promotion evaluation", "Install or activate a skill", /* … */],
  "instructions": [
    "Confirm the reusable intent, realistic positive triggers, near misses, bounded inputs, and one independently measurable outcome.",
    "Record a no-skill or prior-version baseline before final prose and define at least three positive eval cases plus one realistic near miss.",
    // …
  ],
  "eval_path": "evals/evals.json"
}

One command builds all seven records into platform-native packages:

$ python -B tools/build_adapters.py --mode candidate-sandbox --output-root artifacts/build
adapter build candidate-sandbox: 7 included, 0 excluded

For Claude Code, that generates a plugin manifest plus one SKILL.md per skill (trimmed):

<!-- artifacts/build/claude-code/rigwright/skills/rigwright-author-skill/SKILL.md -->
---
name: rigwright-author-skill
description: "Authors or improves one atomic neutral skill and emits requested Claude Code or Codex adapters. Use when a user asks to create, refactor, tighten, or add evals to a skill without installing or activating it."
---

# Rigwright Author Skill

Create or improve one atomic neutral skill source.

## Procedure

1. Confirm the reusable intent, realistic positive triggers, near misses, bounded inputs, and one independently measurable outcome.
2. Record a no-skill or prior-version baseline before final prose and define at least three positive eval cases plus one realistic near miss.
   …

This is a generated `claude-code` adapter. Edit the neutral `src/skills/rigwright-author-skill/skill.json` source instead of this file.

The Codex package carries the same skill body under Codex's own manifest layout, plus the UI metadata Codex keeps in a separate file:

# artifacts/build/codex/rigwright/skills/rigwright-author-skill/agents/openai.yaml
interface:
  display_name: "Rigwright Author Skill"
  short_description: "Use Rigwright Author Skill workflow"
  default_prompt: "Use $rigwright-author-skill for this bounded proposal task."
policy:
  allow_implicit_invocation: false

Each skill ships its own eval set (prompts that must trigger it and realistic near misses that must not), and one command rebuilds both adapter modes and replays them all:

$ python -B tools/run_evals.py
offline evals passed: 59 assertions, 7 near misses, 6 fixed tasks

All output above is from a real run on this tree.

The seven skills

Each skill is deliberately narrow: anything beyond its one outcome (installing, activating, promoting) is out of scope by contract, and the validator enforces those boundaries. The per-skill boundary lists are in STATUS.md.

How it works

flowchart LR
  A["Neutral sources<br>src/skills/*/skill.json"] --> B["Adapter builder<br>tools/build_adapters.py"]
  B --> C["Claude Code package"]
  B --> D["Codex package"]
  C --> E["Validators<br>127 contract + 224 package checks"]
  D --> E
  E --> F["Eval report<br>59 assertions"]

The neutral record is the single source of truth; generated files say so and point back to it. Builds are deterministic: rebuilding produces byte-identical trees and archives, and tools/verify_determinism.py proves it. Beyond Rigwright's own validators, a manual CI job runs each platform's native validator (claude plugin validate and the Codex plugin validator) against the generated packages.

Install

The CLI is on PyPI as rigwright and needs Python 3.12+:

pip install rigwright

Run the complete offline gate from a clone of this repository with rigwright gate, or with no install at all:

$ python tools/run_all.py
offline gate PASS: 8/8 commands

The eight commands and their current one-line results:

source fingerprint skipped: no config/sources.json
contract validation passed: 127 checks, 7 leaves, 32 eval cases
adapter build normal: 0 included, 7 excluded
adapter build candidate-sandbox: 7 included, 0 excluded
package validation passed: 224 checks
determinism passed: 2 surface packages
runtime fixtures passed: 6 tasks, 4 conditions, 3 replicates
offline evals passed: 59 assertions, 7 near misses, 6 fixed tasks

Evidence is written under artifacts/ (untracked). See Validation for the cache-free assessment pattern.

Status: source version 0.2.0 is prepared for review while PyPI still carries the historical 0.1.0 CLI package. The seven skills remain proposals, and nothing in this repository installs or activates them; full current state in STATUS.md.

Safety and limitations

• Generated packages under artifacts/ are offline evaluation evidence, not installations. Which skill version is live is decided outside this repository, by the owner's separate lifecycle registry (see STATUS.md).
• Open problem: producing Codex plugin manifests that pass Codex's native validator for a dual-surface plugin. Rigwright's own generated Codex package passes the captured validators, but that is candidate-local evidence and does not settle the general case. See Conflicts and open problems.
• The offline gates prove deterministic contract and fixture coverage; they are not adoption, production, or model-quality claims. An internal blinded runtime evaluation was run on both platforms; it does not authorize promotion.
• Original material is MIT licensed under Rahul Krishna. Captured third-party material retains its original terms and is not relicensed; see third-party notices.
• No dedicated public security contact exists yet; report privately through the GitLab project rather than a public issue. See Security policy.

Project documents

• Status
• Architecture
• Configuration
• Validation
• Privacy and retained evidence
• Release readiness
• Contributing
• Roadmap
• Changelog

Rigwright is authored by Rahul Krishna and distributed under the MIT License.