Reference · Codex-led setup

Install, configure, invoke

Install one folder, keep your preferences in one private file, check its structure, then ask for the skill by name.

Step 1Install the package folder

Installation needs Node.js 22.20+ (including npx) and Git. The profile setup wizard and validator also require Python 3.9+. Install for Codex in one command:

npx skills add jaredchu/agents-collab --skill agents-collab --global --agent codex

This uses Vercel’s Skills CLI. The --global flag installs to ~/.agents/skills/agents-collab, outside your projects. Running it again can replace existing skill files; the guarded manual copy below preserves them. Your profile at ~/.config/agents-collab/profile.json is separate and is not created or overwritten by this command.

Continue with profile setup; skip the manual copy blocks below. Installing the skill does not configure model access or enable automatic routing. Other lead assistants remain unvalidated.

Manual installation without Node.js

These ZIP and checkout routes need Python 3.9+.

Install only the skill package: the workflow files, the profile validator and setup wizard scripts, and its MIT LICENSE. Keep LICENSE with the folder when you copy or share it. A repository checkout keeps it in skills/agents-collab/; the website ZIP extracts to agents-collab/. The website, tests and notes are not part of the skill.

Codex’s documented user skills location is described in OpenAI’s Build skills documentation. Check it for your version. Choose one source below, then run the shared install block in the same shell.

From the website ZIP

Save agents-collab-skill.zip, then run this from the folder containing it. It extracts into a fresh system temporary directory. The archive is reproducible; compare its SHA-256 hash with the ZIP entry in SHA256SUMS. The ZIP includes the MIT LICENSE notice.

collab_unpack="$(mktemp -d)"
python3 -m zipfile -e agents-collab-skill.zip "$collab_unpack"
collab_source="$collab_unpack/agents-collab"

From a repository checkout

If you have a checkout instead, run this from its root. Use this source block instead of the ZIP block:

collab_source="skills/agents-collab"

Copy the selected package

Continue in the same shell, where collab_source is set. The block below uses ~/.agents/skills and preserves an existing installation, including a symlink:

collab_skills_root="$HOME/.agents/skills"
if [ ! -f "$collab_source/SKILL.md" ]; then
  echo "Choose a package source first; nothing was copied" >&2
elif [ -e "$collab_skills_root/agents-collab" ] || [ -L "$collab_skills_root/agents-collab" ]; then
  echo "agents-collab already installed; compare before replacing" >&2
else
  mkdir -p "$collab_skills_root"
  cp -R "$collab_source" "$collab_skills_root/agents-collab"
fi

The delegated-writer example is available separately as writer-review.profile.example.json. Save it for the next step if you want that example.

Check the skills catalog after installing. Codex detects skill changes automatically; if the skill does not appear, restart the host or try a fresh session. Seeing it in the catalog confirms discovery, not that it will be picked automatically.

Step 2Create or keep a profile

The profile holds personal choices: models, transports, reasoning requests, routing, review recipes, time targets and a private records root. It lives outside every project at ~/.config/agents-collab/profile.json.

Interactive setup (recommended)

After installing or updating the skill, with Python 3.9+, run the wizard. Adjust the path if you installed the skill elsewhere:

python3 ~/.agents/skills/agents-collab/scripts/setup_profile.py

• The lead stays your current session (host, current, inherit); the wizard cannot switch its model or reasoning.
• Choose the current lead or a delegated writer for substantial work; a delegate needs an exact model ID and a transport, codex-native or claude-cli.
• Add zero or more independent reviewers with the same details.
• Pick inherit, a common named level or a custom lowercase level per delegate. Levels are requests; the wizard cannot check that a model or interface supports them.
• With reviewers, consequential work can request one reviewer from the pool by default. With several, a named recipe lists them all; it runs only when you name it.
• Choose a profile label and a private records root (default ~/.local/state/agents-collab).

It uses advisory example time targets, supported-control and existing-authorized-access; edit the file to change them. It validates the result, previews it with the target path and writes only after you confirm, with mode 0600. It asks for no credentials and calls no model or service. --dry-run previews without writing, --output PATH writes elsewhere and --replace allows replacing an existing profile after confirmation. Without it an existing profile is kept; a symlink or nonregular target is never followed or replaced. A generated profile is structurally valid, not proof of model access, supported effort, permissions or records isolation.

Manual templates

To write the profile by hand instead, for the writer/reviewer example first save writer-review.profile.example.json. This separate download works after either CLI or manual installation.

Keep an existing profile. Copy a template only if none exists. Run this from the folder where you saved the example file (in a repository checkout it is docs/examples/):

mkdir -p ~/.config/agents-collab
if [ -e ~/.config/agents-collab/profile.json ] || [ -L ~/.config/agents-collab/profile.json ]; then
  echo "profile exists; leaving it unchanged" >&2
else
  cp writer-review.profile.example.json ~/.config/agents-collab/profile.json
  chmod 600 ~/.config/agents-collab/profile.json
fi

This template has a delegated writer and one reviewer for consequential work. Its two model fields are angle-bracket placeholders that fail validation on purpose until you replace them with exact model identifiers you actually have access to. The package also ships a solo template, examples/profile.example.json, that is valid as shipped.

{
  "version": 1,
  "name": "writer-plus-review-example",
  "agents": {
    "lead": {"model": "current", "transport": "host", "reasoning": "inherit"},
    "writer": {"model": "<writer-model-id>", "transport": "claude-cli", "reasoning": "inherit"},
    "reviewer": {"model": "<reviewer-model-id>", "transport": "codex-native", "reasoning": "inherit"}
  },
  "routing": {"small_writer": "current-session", "substantial_writer": "writer"},
  "review": {
    "on_consequential_work": "single",
    "candidates": ["reviewer"],
    "prefer_different_model": true,
    "recipes": {},
    "max_followup_rounds": 1
  },
  "effort_check": "supported-control",
  "access": "existing-authorized-access",
  "bounds": {"enforcement": "advisory", "writer_minutes": 30, "reviewer_minutes": 10, "review_output_words": 800},
  "records_root": "~/.local/state/agents-collab"
}

Step 3Validate the structure

Profile validation requires Python 3.9+, with either installation method.

python3 ~/.agents/skills/agents-collab/scripts/validate_profile.py ~/.config/agents-collab/profile.json

The setup wizard runs these checks before saving; rerun the validator after any hand edit. A pass is structural only. The validator never checks that a model exists, that you can access it, that a reasoning level is supported, permissions, or where records resolve. Diagnostics name fields without echoing values.

Step 4Invoke it

A three-case public diagnostic followed the configured routes after explicit invocation without model names. Ordinary prompts missed both required collaboration routes. Use the skill name explicitly; installing it does not establish dependable implicit activation.

Explicit invocation is the reliable path:

Use $agents-collab to implement the export change, with independent review before I merge.

Use $agents-collab with the "pair" recipe to review docs/proposal.md. Do not edit it.

Automatic selection depends on the skill’s description and on how your host picks skills. It is not an always-on hook, and the trials did not establish reliable unprompted routing. Small solo work normally stays with the lead and creates no records.

Step 5Native settings stay separate

Your host’s own configuration sets the lead model, its reasoning level and subagent defaults. The profile only tells the skill what to request and check for delegated work. Using the skill never requires changing global configuration or bypassing permissions.

In practiceWhat happens in a run

1. The lead reads project instructions and the profile, and validates the profile.
2. It classifies the task. Small work stays solo unless review is required.
3. Before delegating, it confirms model, access and controls, recording requested settings separately from what the interface accepted.
4. Reviewers get a neutral packet and the same frozen artifact, not the writer’s conversation.
5. The writer handles findings. Rounds stop at the cap; unresolved material issues are reported, not waived.
6. Private records go under records_root; the project receives durable outcomes.

If a required model, effort or access path is unavailable, the lead says so instead of silently substituting another model or paid access.

Why it is shaped this way What the trials showed