Codex skills and read-only subagents for Script Kit GPUI

codex-skills-subagents-writeup.md

Codex Skills and Read-Only Subagents for Script Kit GPUI

This write-up summarizes the research and implementation of a repo-local Codex skill and subagent topology for Script Kit GPUI.

Goal

The objective was to create an exhaustive but maintainable set of Codex skills and paired subagent briefs where each skill represents a coherent module, feature, workflow, or ownership area of the app. The root agent instructions also needed to reference the full map so future requests can route into the right skill automatically when the task matches a skill description.

The work started with five sequential Oracle + packx research passes before implementation.

Research Method

I used the existing oracle-packx workflow to bundle repo context and ask Oracle for five sequential passes:

1. codex-skills-best-practices Best practices for organizing Codex skills and subagents, especially trigger design, granularity, overlap control, and how AGENTS.md should route rather than duplicate skill bodies.

2. codex-module-taxonomy-research A concrete taxonomy for Script Kit GPUI. This pass recommended 24 repo-local ownership/support skills, with paired read-heavy subagents.

3. codex-skill-template-research The reusable SKILL.md and subagent markdown templates, including frontmatter, section order, proof ladder wording, conflict guardrails, and migration guidance from the legacy .claude/skills tree.

4. codex-agents-routing-research AGENTS integration and routing strategy. This pass clarified an important caveat: skill matching can be implicit through skill descriptions, but subagents are not automatically spawned just because a paired brief exists.

5. codex-final-synthesis-research A final implementation blueprint that corrected drift toward legacy .claude skill names and locked the 24-skill ownership taxonomy as the canonical Codex routing surface.

The relevant Oracle session logs are stored locally under ~/.oracle/sessions/<slug>/output.log.

Main Design Decision

The final design uses ownership areas, not file count, as the unit of specialization.

That means there is not one skill per Rust file, one skill per prompt type, or one skill per AppView variant. Instead, each skill owns a recurring behavior domain with recognizable triggers, stable path clusters, adjacent-skill boundaries, and a proof ladder.

The generated tree is:

.agents/
  skills/
    <skill>/SKILL.md
  subagents/
    <skill>-reader.md

The existing .claude/skills/* files remain migration and compatibility sources. They are not the canonical Codex skill names for this repo.

Canonical Skill Set

The implementation created 24 repo-local Codex skills:

lat-md
agentic-testing
testing-quality-gates
dev-loop-observability
gpui-ui-foundation
theme-config-preferences
storybook-design
launcher-surface-contracts
main-menu-search-selection
keyboard-focus-routing
actions-popups
builtin-filterable-surfaces
file-search-portals
prompt-runtime
sdk-script-execution
protocol-automation
mcp-context-resources
acp-chat-core
acp-context-composer
quick-terminal-pty
notes-window
dictation-media
platform-windowing-macos
storage-cache-security

Each skill lives at:

.agents/skills/<skill>/SKILL.md

Each paired read-only subagent brief lives at:

.agents/subagents/<skill>-reader.md

Skill Routing Map

The root AGENTS.md is a symlink to CLAUDE.md, so the routing table is maintained in CLAUDE.md and applies to both entrypoints.

Skill	Paired subagent	Primary ownership
lat-md	lat-md-reader	lat.md/ authoring, wiki links, code refs, lat check
agentic-testing	agentic-testing-reader	State-first runtime proof, screenshots only when needed, cleanup of launched sessions
testing-quality-gates	testing-quality-gates-reader	Choosing narrow checks, cargo/bun/lat gates, release-vs-local validation
dev-loop-observability	dev-loop-observability-reader	Dev loop, compact logs, tracing, correlation IDs, runtime diagnostics
gpui-ui-foundation	gpui-ui-foundation-reader	GPUI layout, focus, keyboard handlers, theme usage, component lifecycle
theme-config-preferences	theme-config-preferences-reader	config.ts, theme.json, preferences, font/scale/runtime settings
storybook-design	storybook-design-reader	Storybook/design explorer, stories, variants, adoption, chrome audits
launcher-surface-contracts	launcher-surface-contracts-reader	AppView, SurfaceKind, surface contracts, current-view transitions
main-menu-search-selection	main-menu-search-selection-reader	Main menu filtering, grouped results, selection caches, fallback rows
keyboard-focus-routing	keyboard-focus-routing-reader	Global/local key intent routing, focus restoration, popup-first key handling
actions-popups	actions-popups-reader	Actions dialog, prompt/confirm popups, popup registry, route stack, resize
builtin-filterable-surfaces	builtin-filterable-surfaces-reader	Clipboard/app/process/emoji/current-app/design gallery filterable surfaces
file-search-portals	file-search-portals-reader	File search, attachment portals, browser/dictation/history portal return flows
prompt-runtime	prompt-runtime-reader	Prompt entities, prompt handler routes, prompt-specific state and rendering
sdk-script-execution	sdk-script-execution-reader	SDK preload, script metadata, script execution, Bun package/script behavior
protocol-automation	protocol-automation-reader	Stdin JSON protocol, getState, getElements, waitFor, batch, receipts
mcp-context-resources	mcp-context-resources-reader	MCP resources, kit://context, context schemas, resource-backed catalogs
acp-chat-core	acp-chat-core-reader	Agent Chat entry, embedded/detached ACP, model/agent/session behavior
acp-context-composer	acp-context-composer-reader	ACP composer, slash/mention picker, context parts, attachment tokens
quick-terminal-pty	quick-terminal-pty-reader	Quick Terminal, PTY lifecycle, terminal theming, apply-back behavior
notes-window	notes-window-reader	Notes window, notes browse, notes-hosted ACP, Markdown notes behavior
dictation-media	dictation-media-reader	Dictation, audio/media capture, transcript delivery, history resources
platform-windowing-macos	platform-windowing-macos-reader	macOS windowing, screenshots, AppKit/AX/focus, bundle/platform behavior
storage-cache-security	storage-cache-security-reader	Local storage, caches, SQLite, secrets, encryption, cleanup/security boundaries

What Is Automatic

Codex skills can be selected implicitly when the task matches the name or description in .agents/skills/<skill>/SKILL.md. That is why every skill description front-loads literal trigger words and boundaries.

Paired subagent briefs are different. A file such as .agents/subagents/protocol-automation-reader.md is not automatically spawned by Codex. It is a checked-in read-only brief for an explicit subagent or for the primary agent to consult during complex exploration.

The repo instructions now say to use a paired subagent when a task spans multiple modules, touches a high-risk surface contract, or needs evidence before editing. Subagents must stay read-only and return compact evidence: files inspected, contracts/invariants, risks, and recommended proof.

Skill Template

Each generated skill follows this structure:

---
name: <skill-name>
description: >-
  <front-loaded trigger words and boundary>
---

# <Skill Title>

This skill owns <domain> for Script Kit GPUI and keeps changes grounded in current source, lat.md contracts, and the narrowest useful proof.

## Use When

## First Reads

## Owned Paths and Concepts

## Core Rules

## Workflow

## Proof Ladder

## Adjacent Skills

## Migration Notes

The common proof ladder is:

1. Docs/source audit proof.
2. Compile/static proof.
3. Targeted test proof.
4. State-first runtime proof.
5. Visual proof only when visual acceptance matters.
6. Native input or OS focus proof only when the bug depends on real OS delivery.

Every skill also points back to lat.md/ and lat check when behavior, architecture, tests, or contracts change.

Subagent Template

Each paired subagent brief is intentionally plain Markdown:

# <skill>-reader

You are a read-only repository subagent for `$<skill>`.

## Mission

Map the files, contracts, invariants, and verification path for a task in this skill's domain. Do not edit files.

## Inputs To Inspect First

## Allowed Work

## Hard Constraints

## Output Format

The output format asks for:

Scope:
Relevant files:
Contracts/invariants:
Risks:
Recommended verification:
Migration notes:

This gives a future implementation agent concise, cited evidence without allowing the subagent to mutate the worktree.

Lattice Documentation

The repo knowledge graph now includes lat.md/agent-skills.md, and lat.md/lat.md links it through [[agent-skills]].

The lattice page records:

• the canonical 24-skill set,
• the .agents/skills/ and .agents/subagents/ locations,
• the fact that AGENTS.md is a symlink to CLAUDE.md,
• the routing contract,
• the read-only subagent contract,
• related pages such as architecture, surfaces, automation, verification, acp-chat, and workspace.

Verification Performed

I verified the implementation with:

lat check

Result:

All checks passed

I also ran an artifact audit:

skills=24 subagents=24 expected=24
artifact-check: ok

And confirmed every expected Oracle research session produced an output log:

codex-skills-best-practices ok
codex-module-taxonomy-research ok
codex-skill-template-research ok
codex-agents-routing-research ok
codex-final-synthesis-research ok

Practical Takeaways

The most important design constraints are:

• Keep skill descriptions concise and trigger-oriented.
• Use ownership domains, not file count, as the skill boundary.
• Keep AGENTS.md as routing metadata, not a duplicate skill manual.
• Treat .claude/skills/* as migration source material, not canonical names.
• Prefer state-first receipts before screenshots for runtime behavior.
• Do not imply subagents are automatic; use them explicitly and keep them read-only.
• Run lat check after every task, and update lat.md/ when behavior, architecture, tests, or contracts change.

This setup gives future Codex runs a practical routing layer: small enough to remain usable, but broad enough to cover the major Script Kit GPUI modules and workflows.