tx skills

Generate and sync target-specific skill bundles for Claude Code and Codex

Purpose

tx skills manages the generated agent skill bundles that tx installs for Claude Code and Codex.

Use it when you need to:

• understand what tx init --claude or tx init --codex actually installs,
• generate install-ready bundles from the canonical tx help corpus,
• refresh skills in an existing project after upgrading tx,
• preserve local custom skills while updating tx-managed ones.

What tx init Installs

By default, onboarding is skills-first:

tx init --claude
tx init --codex
tx init --claude --codex

Running plain tx init opens onboarding prompts where you choose the exact tx skills to install for Claude and Codex. Passing --claude or --codex skips that prompt and installs the full default bundle for the selected runtime.

Default outputs:

• tx init --claude installs .claude/skills/**
• tx init --codex installs .codex/skills/** and .codex/rules/**
• top-level CLAUDE.md and AGENTS.md are not generated by default
• legacy compatibility files are optional, not the default path

This makes onboarding refreshable. The installed agent guidance lives in bundle directories that can be regenerated and synced later.

Generated And Bundled Skills

The installed bundle is a mix of:

• generated skills derived from the canonical tx command/help registry,
• bundled workflow skills that teach higher-level tx workflows.

Published bundled workflow skills include:

• decompose-spec
• design-doc
• overview-spec
• prd
• ralph-loop
• skills-sync
• task-spec-loop
• verify-invariants

That is why a fresh onboarding install can teach an agent how to decompose a design doc, refresh skills later, or run a Ralph loop without relying on one static top-level bootstrap file.

tx skills generate

Use generate when you want install-ready bundles on disk:

tx skills generate
tx skills generate --target claude
tx skills generate --target codex --json
tx skills generate --output-dir .tx/generated-skills --clean

Default output shape:

.tx/generated-skills/
  claude/.claude/skills/<skill-id>/
  codex/.codex/skills/<skill-id>/

Each target bundle includes a manifest.json describing the generated content.

tx skills sync

Use sync when a project already has tx-managed skills installed and you want to refresh them in place:

tx skills sync
tx skills sync --target claude
tx skills sync --target codex
tx skills sync --project-dir /absolute/path/to/project
tx skills sync --project-dir /absolute/path/to/project --json

Behavior:

• missing tx-managed files are added,
• changed tx-managed files are updated in place,
• unchanged files are left alone,
• unrelated custom skill directories are preserved.

That makes tx skills sync the normal maintenance path after upgrading tx or after changing shared skill templates in the canonical tx repo.

Target-Specific Rendering

The bundle content is not identical across onboarding targets.

tx renders from one canonical command/help source, but adapts the installed skills to the host surface. For example:

• Codex skills reference Codex-specific plan paths such as ~/.codex/plans/
• Claude skills reference Claude-specific plan paths such as ~/.claude/plans/
• Codex installs .codex/rules/** alongside the skill bundle

So when you need skills that are modifiable based on onboarding, the concrete behavior is: tx emits target-specific wrappers from a shared canonical source.

Related Workflow Skills

• tx decompose documents the task-graph surface used by the bundled decompose-spec skill.
• Ralph Loop documents the shell workflow used by the bundled ralph-loop skill.
• tx doc documents the PRD/design-doc structures used by the bundled spec-writing skills.