Move reusable skill workflow prose into structured config

[shiny-code-bot]

Summary

Skills currently mix durable, machine-actionable workflow facts with prose instructions. As skill-owned command policy lands, preserve the broader follow-up: move reusable command/workflow declarations out of prose into structured skill frontmatter where Every Code can render, validate, and enforce them consistently.

Finish Line

Skill-owned command/workflow facts are structured in YAML and prose only retains judgment, sequencing, and exceptions.

Current Status

State: Active
Next action: Continue the skill audit beyond policy.command_policies: classify remaining prose into structured commands/actions/resources/workflow defaults, valuable prose, or stale duplicate.
Blocked by: None
Waiting for: Nothing
Last verified: 2026-05-30 after command-policy infrastructure, overlap handling, and wrapped-shell matching fixes merged via #237, #246, and #249.

Notes:

• Add generic skill-owned command policies #236 is no longer a blocker; the generic command-policy support landed.
• This plan is not done yet because the broader acceptance criteria still include a full bundled-skill audit, structured helper command/action/resource surfaces, renderer/loader tests for those fields, and removal of duplicated prose once generated guidance covers it.

Proposed Structured Surfaces

• policy.command_policies: command matchers, actions, preferred alternatives, override behavior, owner skill attribution.
• commands or actions: named helper invocations a model can call directly, with argv templates, required args, cwd behavior, and short purpose text.
• resources: bundled scripts, references, templates, and assets that are intended to be loaded or executed, with relative paths resolved from SKILL.md.
• workflow_defaults: durable non-prose defaults such as preferred GitHub helper, PR body template, validation command, or closeout helper when a skill owns a workflow.
• render: optional concise model-facing summaries generated from structured data; avoid copying raw YAML into context.

Migration Principles

• YAML is authoritative for mechanical facts the runtime or renderer can use.
• Prose is kept when it explains why, when to choose alternatives, edge cases, or human judgment.
• Avoid duplication: if generated guidance from config says “use script X for command Y,” remove prose that says the same thing unless it adds nuance.
• Manual-only skills may still declare runtime command policies; manual-only controls implicit invocation, not guardrail availability.
• Keep safety rules that are universal/destructive in core config/runtime unless there is a separate trust model for skill-provided policy.

Candidate Audit Targets

• GitHub skill: PR create/comment/check/merge/supersede/close helpers and issue planning helpers.
• GitHub plan skill: durable issue helper commands, plan section update helpers, closeout helper expectations.
• Work closeout skill: cleanup/check/status helper commands and GitHub relationship sweeps.
• Test TUI skill: harness commands, expected env/config, screenshot/control helpers.
• Skill creator/installer: bundled scripts and templates, argument shapes, validation commands.

Acceptance Criteria

• A full skill audit produces a migration table: convert to YAML, keep prose, delete duplicate, or needs new schema.
• All bundled skills with helper scripts expose them as structured commands/actions.
• Command-policy guidance rendered to the model comes from YAML, not duplicated prose.
• Skill loader tests cover structured fields and relative path resolution.
• At least one migration PR removes duplicated prose after generated guidance covers it.

Validation

• Loader tests for each new structured field.
• Renderer tests proving generated guidance is concise and not duplicated.
• Skill audit fixture or snapshot showing all bundled skills classified.
• ./build-fast.sh for implementation PRs touching the Rust workspace.

Relationships

• Blocked by: Add generic skill-owned command policies #236 generic skill-owned command policy support.
• Follow-up after: command-policy infrastructure can render and enforce structured skill command data.

[shiny-code-bot]

Related follow-up opened: #244 tracks deterministic overlap handling for skill command policies. Keep #235 migrations conservative until that lands: avoid duplicate broad/specialized policies for the same raw command unless the specialized skill adds materially different guidance.

[shiny-code-bot]

Update: cbusillo/codex-skills#196 merged the next structured-config migration slice for github-plan.

What changed:

• Added command policies for raw planning issue indexes/searches, raw gh project commands, and planning GraphQL mutations.
• Preferred actions route to ../github/scripts/gh-plan.py commands (index, search, project-list, project-add, project-set, link).
• Kept planning judgment in prose and avoided duplicating the existing github skill policies for gh issue create/edit/close and PR operations.

Validation:

• uv run skill-creator/scripts/quick_validate.py github-plan
• uv run skill-creator/scripts/validate-skill-repo.py
• git diff --check
• Exec harness smoke using real repo-local github-plan and github skills: code exec --json against a fake Responses endpoint blocked raw gh search issues "roadmap label:plan", returned gh-plan.py search guidance, emitted no exec_command_begin, and completed the run.

Related follow-up: #244 tracks deterministic overlap handling for multiple matching skill command policies before we migrate broader or potentially overlapping command surfaces.

[shiny-code-bot]

[codex] Progress update after PR #254:

• Added structured resources, commands, and workflow_defaults parsing to skill frontmatter.
• Added concise model-facing rendering from those structured fields for implicitly available skills.
• Added loader/render tests, including relative path resolution, undeclared command resource validation, and manual-only suppression.
• Migrated the bundled plan skill helper invocations into YAML and removed the duplicated prose script block.
• Validated with ./build-fast.sh before merge.

Remaining work for this issue:

• Run the full bundled-skill audit and classify each reusable helper/workflow fact as YAML, prose, duplicate, or needing new schema.
• Migrate more bundled skills with helper scripts beyond plan.
• Decide whether actions should be an alias/new surface or whether commands remains the canonical schema.
• Add any needed schema support for richer workflow defaults, render controls, cwd behavior, or command-policy references to structured commands.
• Remove more duplicated prose once generated guidance covers it.