Installation

Installation#

Canonical Skills#

The source of truth for skills is llm_workflow/skills/<skill-id>/:

llm_workflow/
  skills/
    review-tests/
      skill.yml
      instructions.md

The installer generates platform-specific artifacts for Codex, Claude Code, OpenCode, and Grok from this canonical source.

Generated Platform Artifacts#

Each generated artifact contains the canonical skill instructions plus a platform orchestration adapter.

  • full means the platform can run the intended workflow natively.

  • degraded means the artifact is installable but includes explicit fallback guidance.

  • unsupported skills are skipped for that platform.

Multi-persona skills use this hierarchy:

  1. Full platform-native team orchestration when available.

  2. Platform-native subagents when available.

  3. Sequential single-agent fallback, where each persona runs in the current session and its markdown output is recorded before continuing.

Default input files are rendered per platform:

  • Claude Code: .claude/<skill>.md

  • Codex: .codex/<skill>.md

  • OpenCode: .opencode/<skill>.md

  • Grok: .grok/<skill>.md

Migrated skills also check the legacy .claude/<skill>.md path after the platform default.

Compatibility Matrix#

Skill

Claude Code

Codex

OpenCode

Grok

Notes

code-review-response

full

full

full

full

Standalone, no external dependencies

complexity

full

full

full

full

Needs radon (Python) and/or gocyclo (Go); does not auto-install

review-tests

full

full

full

full

Standalone, no external dependencies

cprompt

full

full

full

full

Writes prompt file, prints prompt, and attempts clipboard copy

thermo-nuclear

full

full

full

full

Strict single-agent maintainability review; writes report artefact

debate

full

degraded

degraded

degraded

External model routing falls back only after user confirmation

council

full

degraded

degraded

degraded

Multi-persona review with sequential fallback

pre-mortem

full

degraded

degraded

degraded

Failure-focused multi-persona review

shred-it

full

degraded

degraded

degraded

Research-backed adversarial idea review

team-review-tests

full

degraded

degraded

degraded

Test-quality multi-persona review

team-review-impl

full

degraded

degraded

degraded

Spec-driven implementation review

Legacy Manual Installation#

Claude Code Installation#

Prerequisites#

  • Claude Code CLI installed and configured

  • Git (for cloning the repository)

Skill-specific prerequisites:

  • HydraMCP or another model router enables external-model debate personas. If unavailable, the generated skill asks before continuing as a within-model debate.

  • Agent teams enable full Claude multi-persona orchestration for council, pre-mortem, shred-it, team-review-tests, and team-review-impl. If unavailable, generated artifacts describe the sequential fallback.

  • complexity needs radon for Python and/or gocyclo for Go. The skill reports missing tools and does not auto-install them.

Installation Steps#

  1. Clone the repository

    git clone https://github.com/yourusername/llm-workflow.git
cd llm-workflow

  2. Register the local marketplace

    Add the marketplace to your Claude Code settings. Edit ~/.claude/settings.json and add:

    {
  "enabledPlugins": {
    "wf@wf-marketplace": true
  },
  "extraKnownMarketplaces": {
    "wf-marketplace": {
      "source": {
        "source": "directory",
        "path": "/path/to/llm-workflow/plugin"
      }
    }
  }
}

    Replace /path/to/llm-workflow with the actual path where you cloned the repository.

  3. Verify installation

    Restart Claude Code. The wf skills should now be available. You can verify by invoking a skill directly:

    /wf:code-review-response
/wf:debate

Agent Teams Setup#

The council and pre-mortem skills require Claude Code’s experimental agent teams feature. This allows multiple Claude agent instances to work as a team, each with their own independent context window.

Warning

Agent teams is experimental. The API may change without notice in future Claude Code updates. If these skills break after an update, check the agent teams documentation for API changes.

Enabling Agent Teams#

Agent teams are disabled by default. Enable them by adding the environment variable to your Claude Code settings.

Edit ~/.claude/settings.json and add the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

This merges with any existing settings. A full settings.json with plugin and agent teams enabled looks like:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "enabledPlugins": {
    "wf@wf-marketplace": true
  },
  "extraKnownMarketplaces": {
    "wf-marketplace": {
      "source": {
        "source": "directory",
        "path": "/path/to/llm-workflow/plugin"
      }
    }
  }
}

Alternatively, you can set the environment variable in your shell profile (~/.bashrc, ~/.zshrc, etc.):

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

The settings.json approach is recommended because it ensures agent teams are consistently available across all Claude Code sessions.

Verifying Agent Teams#

After enabling, restart Claude Code and run:

/wf:council

If agent teams are properly enabled, the skill will proceed to parse input. If not, you will see an error indicating that agent teams tools are unavailable.

Display Modes#

Agent teams support different display modes for teammate output. Configure via settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or use the --teammate-mode flag when starting Claude Code:

  • auto (default) — uses split panes in tmux/iTerm2, in-process otherwise

  • in-process — all teammates run in your main terminal

  • tmux — forces split-pane mode (requires tmux or iTerm2)

Note

Split-pane mode is not supported in VS Code terminal, Windows Terminal, or Ghostty. Use in-process mode in those environments.

Agent Teams Caveats#

Be aware of the following limitations when using the council, pre-mortem, and team-review-tests skills:

Cost and performance:

  • Each judge runs as a separate Claude agent instance with its own context window. A 3-judge council costs ~6 agent turns; a 4-judge pre-mortem costs ~12 agent turns; a 3-judge team-review-tests costs ~9 agent turns.

  • Token usage is significantly higher than the debate skill, which uses a single host session with ask_model calls.

  • Use these skills for important decisions, not routine reviews.

Session constraints:

  • One team per session — Claude Code supports a single agent team per session. Do not run council, pre-mortem, or team-review-tests while another team is active.

  • No nested teams — teammates cannot spawn their own teams.

  • No session resumption — /resume and /rewind do not restore in-process teammates. If the session is interrupted, you must re-run the skill.

Known issues:

  • Delegate mode is broken — when the lead delegates to teammates, permission restrictions propagate and prevent teammates from working. The council and pre-mortem skills work around this by having the lead coordinate directly without using delegate mode.

  • Task status lag — teammates sometimes fail to mark tasks complete, which can cause the lead to wait unnecessarily.

  • Slow shutdown — teammates finish current work before shutting down. Team cleanup may take a few seconds.

Permissions:

  • All teammates start with the lead’s permission mode. Individual teammate permissions can be changed after spawning but not at spawn time.

  • If the lead runs with --dangerously-skip-permissions, all teammates do too.

Updating#

To update to the latest version:

cd /path/to/llm-workflow
git pull origin master

The plugin will automatically pick up the updated skill definitions.

Uninstalling#

To remove the plugin, edit ~/.claude/settings.json and:

  1. Remove the "wf@wf-marketplace": true entry from enabledPlugins

  2. Remove the "wf-marketplace" entry from extraKnownMarketplaces

  3. Optionally remove the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var if no longer needed

Then restart Claude Code.

Grok Installation#

The installer generates Grok skills for every full or degraded skill in the compatibility matrix and installs them under ~/.grok/skills/.

Multi-persona degraded skills prefer Grok spawn_subagent and otherwise run persona turns sequentially in the current session. Context embedding does not require smart_read; platforms without that tool use native read-and-summarise.

Prerequisites#

  • Grok Build CLI available for verification (optional for install)

  • Write access to ~/.grok/skills/

Install#

llm-workflow install grok
llm-workflow doctor grok

This builds build/grok/skills/<skill-id>/SKILL.md and symlinks each installable skill into ~/.grok/skills/. Use --copy for snapshot installs.

Invocation#

Restart or open a Grok session after installing. Skills appear as slash commands named after the skill id:

/review-tests
/council
/cprompt

Grok also supports automatic invocation from the skill description and when-to-use metadata.

Default input files#

Multi-input skills look for:

  1. An explicit path provided by the user

  2. .grok/<skill>.md in the repository root

  3. Legacy .claude/<skill>.md

Codex coexistence#

Codex installs into ~/.agents/skills/. Grok also scans that directory. If the same skill names exist in both places, prefer the Grok adapter under ~/.grok/skills/ for Grok sessions, or remove Codex copies with:

llm-workflow clean codex

Uninstall#

llm-workflow clean grok

Codex Installation#

The installer generates Codex skills for every full or degraded skill in the compatibility matrix. Multi-persona degraded skills use subagents when the runtime exposes them and otherwise run persona turns sequentially in the current session.

Prerequisites#

  • Codex CLI installed and configured

  • Git (for cloning the repository)

Installation Methods#

Codex scans for skills in several locations. Choose the scope that fits your workflow:

Scope

Location

Use case

Repo

$REPO_ROOT/.agents/skills/

Shared with collaborators via version control

User

$HOME/.agents/skills/

Personal skills available in all projects

Codex home

$HOME/.codex/skills/

Installed via $skill-installer

Option B: Copy into a repository#

Copy the skill directories into a specific repo so collaborators get them automatically:

# From your target repository root
mkdir -p .agents/skills

cp -r /path/to/llm-workflow/plugin/skills/code-review-response \
      .agents/skills/code-review-response
cp -r /path/to/llm-workflow/plugin/skills/review-tests \
      .agents/skills/review-tests

Option C: Copy to Codex home#

Copy directly into the Codex skills directory:

cp -r /path/to/llm-workflow/plugin/skills/code-review-response \
      ~/.codex/skills/code-review-response
cp -r /path/to/llm-workflow/plugin/skills/review-tests \
      ~/.codex/skills/review-tests

Verifying Codex Installation#

Restart Codex after installing. The skills should appear when you invoke them with the $ prefix:

$code-review-response
$review-tests

Codex also supports implicit triggering — describing a task that matches the skill’s description will activate it automatically.

Disabling a Codex Skill#

To disable a skill without removing it, add an entry to ~/.codex/config.toml:

[[skills.config]]
path = "/home/you/.agents/skills/review-tests/SKILL.md"
enabled = false

Updating Codex Skills#

  • Symlink installs update automatically when you git pull the repository.

  • Copied installs must be re-copied after pulling updates.

Uninstalling Codex Skills#

Remove the skill directory from whichever location you installed to:

# User skills
rm -rf ~/.agents/skills/code-review-response
rm -rf ~/.agents/skills/review-tests

# Or Codex home
rm -rf ~/.codex/skills/code-review-response
rm -rf ~/.codex/skills/review-tests

Then restart Codex.

Contents