TRIZ for Code Agents

An evidence-first Agent Skill for resolving software engineering contradictions without settling too early for a midpoint compromise.

The same skill package targets Codex, Claude Code, Cursor, and OpenCode. It follows the open Agent Skills format and keeps product-specific metadata in thin plugin manifests.

Status: version 0.1 is an evaluated prototype. The method and harness are implemented; any reported quality result must name the model, harness, cases, and sample size.

What it does

The skill helps an agent:

• decide whether TRIZ is appropriate;
• inspect code and evidence before ideation;
• state technical and physical contradictions causally;
• search for separation in time, structure, condition, or scale;
• reuse resources already present in the system;
• turn inventive principles into concrete software mechanisms;
• select a reversible experiment and verify both sides of the conflict;
• skip TRIZ when debugging, measurement, or a known pattern is more direct.

It does not implement full ARIZ-85C, the 76 standard solutions, or a canonical 39 x 39 contradiction matrix.

Install

The universal skills CLI can install the skill into one or several agents:

npx skills add snow-ghost/triz --skill triz

Choose Codex, Claude Code, Cursor, or OpenCode in the interactive prompt. A targeted install can specify agents:

npx skills add snow-ghost/triz --skill triz \
  -a codex -a claude-code -a cursor -a opencode

Review third-party installer behavior before granting access. Manual installation copies the complete skills/triz directory:

Agent	Project location	User location
Codex	.agents/skills/triz	~/.agents/skills/triz
Claude Code	.claude/skills/triz	~/.claude/skills/triz
Cursor	.cursor/skills/triz	~/.cursor/skills/triz
OpenCode	.opencode/skills/triz or .agents/skills/triz	~/.config/opencode/skills/triz or ~/.agents/skills/triz

Claude Code can also load this checkout as a plugin:

claude --plugin-dir .

The plugin invocation is /triz:triz. A standalone installation uses /triz. In Codex, invoke the standalone skill as $triz. Cursor and OpenCode expose it as triz in their skill or slash-command interfaces.

Use

Explicit invocation:

Use $triz to redesign this cache so offline hit rate improves without exceeding the device memory ceiling.

Implicit invocation:

Our full CI suite preserves compliance coverage but takes 40 minutes.
Developers need useful feedback in 5 minutes. Find a design that preserves both.

Boundary example:

This handler panics when an optional field is missing. Fix it and add a regression test.

The last task should use ordinary debugging. The skill's gate must decline TRIZ without adding a visible method trace.

Repository layout

skills/triz/
  SKILL.md
  agents/openai.yaml
  references/
.codex-plugin/plugin.json
.claude-plugin/plugin.json
.cursor-plugin/plugin.json
evals/
tests/
docs/

The canonical implementation lives only in skills/triz. Plugin manifests point to that directory.

Validate

Run the dependency-free repository tests:

python3 -m unittest discover -s tests -v
python3 evals/run_eval.py --dry-run

Additional local checks used for version 0.1:

• Agent Skill validator: passed;
• Codex plugin validator: passed;
• claude plugin validate .: passed;
• opencode debug skill: discovered and loaded the complete skill;
• native Claude Skill paired generation: passed structurally and produced judgeable outputs.

Cursor behavioral testing requires an authenticated Cursor account and was not run in the development environment. Codex's read-only behavioral run exposed a host bwrap failure; unsafe sandbox bypass was deliberately not used.

Evaluate

Generate evaluation prompts without model calls:

python3 evals/run_eval.py --dry-run

Run three paired baseline/TRIZ smoke cases with Codex:

python3 evals/run_eval.py \
  --case autocomplete-latency-quality \
  --case ci-speed-coverage \
  --case routine-nil-bug \
  -- codex exec --sandbox read-only --skip-git-repo-check -

Then blind and score the conditions:

python3 evals/build_blind_pairs.py evals/runs/RUN_ID
cp evals/runs/RUN_ID/blind/judgments-template.json \
  evals/runs/RUN_ID/blind/judgments.json
# Fill judgments.json without opening key.json.
python3 evals/score_judgments.py evals/runs/RUN_ID/blind

The runner uses isolated temporary workspaces. The TRIZ condition installs the local skill into one selected platform path; the baseline condition does not. Use a clean agent profile for stronger isolation from globally installed skills.

The first native five-pair Claude run was mixed: the judge preferred TRIZ on 3/5 pairs and found zero critical errors versus three for baseline, but TRIZ's mean adjusted score was 1.6 points lower because of visible framework narration. After targeted changes, a three-pair regression smoke preferred TRIZ 3/3 with a +1.67 mean delta and no framework-theater penalties. Those three cases were selected after tuning, so they do not establish a general lift.

See the evaluation report, evaluation guide, held-out benchmark protocol, research report, and implementation plan.

Design rationale

The design responds to two findings:

• curated Agent Skills can help, while overly comprehensive skills can hurt because of context and conflicting guidance;
• an earlier public TRIZ eval lost to baseline when framework terminology displaced calculations and concrete engineering detail.

This skill therefore keeps the main workflow compact, loads references conditionally, penalizes framework theater, and treats a standard pattern as a valid result when it resolves the verified mechanism. For implicit use, it returns a direct engineering answer rather than a visible TRIZ worksheet.

License

MIT. See LICENSE.