AGENT SKILL

setup-pstack

Configure which models pstack uses per role and at what reasoning budget. Detects your available models and writes an always-loaded block in ~/.codex/AGENTS.md that overrides the skill defaults. Use for $pstack:setup-pstack, "configure pstack models", "pstack budget", or changing pstack's model choices.

License 许可
MIT
最近更新
2026-10-17
Stars
★ 0
Forks
0

01 前言 Front Matter

name
setup-pstack
description
Configure which models pstack uses per role and at what reasoning budget. Detects your available models and writes an always-loaded block in ~/.codex/AGENTS.md that overrides the skill defaults. Use for $pstack:setup-pstack, "configure pstack models", "pstack budget", or changing pstack's model choices.

03 SKILL.md 正文

Setup pstack

Write the pstack-models block in ~/.codex/AGENTS.md, an always-loaded block that sets pstack's model per role.

Steps

1. Detect available models

Run codex debug models and keep every entry whose visibility is list. Each supported effort in its supported_reasoning_levels makes one detected slug, <slug>-<effort>. That is the dependable source.

codex debug models | python3 -c 'import json,sys
for m in json.load(sys.stdin)["models"]:
    if m.get("visibility") == "list":
        for l in m["supported_reasoning_levels"]: print(m["slug"] + "-" + l["effort"])'

If command -v claude succeeds, also detect the cross-vendor entries claude:<alias>-<effort> for the aliases opus, sonnet, haiku, and fable and the efforts low, medium, high, xhigh, and max. They run through the local claude CLI and are valid in any role. Confirm each chosen claude: entry once with a one-turn probe, claude -p --model <alias> --effort <effort> "reply OK", because command -v claude does not show which efforts a model supports. If the probe fails, drop the entry. If you cannot detect any, ask the user to paste the slugs they have access to. Never write a real slug you have not confirmed is available. The aliases inherit-parent and auto are always valid even though they are not detected slugs.

2. Load current state

The default role-to-model mapping is the block shape shown in step 5 below. If ~/.codex/AGENTS.md (or AGENTS.override.md in the same directory, when it exists) already holds the pstack-models block, read it and treat its # budget line and its role values as the current choices. Otherwise start from those defaults. A line whose role is not in step 5, such as how critics, is from a retired role. Drop it.

3. Budget, map, and confirm

(a) Ask for a budget. Prefer request_user_input over free text. Use it when your tool list has it, else ask in plain text with the same labels. Offer these four options with these exact labels, and name the current budget when the block records one. With no block, say that large matches the skill defaults.

  • unlimited — max reasoning
  • large — xhigh reasoning
  • medium — high reasoning
  • small — medium reasoning

(b) Apply it. Build the working table from the skill defaults, and on a re-run keep any role you changed by family, list, or alias (inherit-parent, auto). unlimited, large, medium, and small set the effort token of every real slug, panel entries included, to max, xhigh, high, or medium. The effort token is the last - token, on the ladder max > xhigh > high > medium > low. If the result is not a detected slug, use the same family's detected slug with the highest effort at or below the target, else mark the role as needing a choice. inherit-parent and auto do not change. So unlimited turns gpt-6-astra-xhigh into gpt-6-astra-max. Codex also offers ultra above max on gpt-6-astra and the sol models, but no budget sets it, so unlimited stays max and ultra is an opt-in per role in step (c). large keeps both defaults. small turns them into gpt-6-astra-medium and gpt-6.1-sol-medium. A claude: entry follows the same ladder.

(c) Show the roles and confirm. Show every role with its model, marking any real slug not in the detected set as needing a choice. Also list each line step 2 dropped. Ask whether to accept as-is or change specific roles, offering the detected models plus inherit-parent and auto (both mean: this role runs on the parent chat model, whatever model the thread runs on) as the options. Offer ultra as an opt-in for any role on a model that lists it. Prefer request_user_input over free text, as in (a). For panel roles (arena runners, architect runners, interrogate reviewers) the value is a list, and one subagent runs per entry, alias entries included, so the list length sets the count. A detected claude: entry can join a panel list, arena cross-judge pool included, and gives that panel a second vendor. Without the claude CLI every default panel is two OpenAI models, so say so when the user cares about model diversity. arena cross-judge pool is also a list, but Arena selects one value from it whose model family differs from the parent's when possible. swarm workers is the default model for every worker unless a race or comparison assigns another model per arm.

4. Validate

Every real slug written must be in the detected set. inherit-parent and auto always pass. A claude: entry passes only when its probe from step 1 succeeded. If a chosen real slug is not available, stop and ask again.

5. Write the block

Write the block between <!-- pstack-models:begin --> and <!-- pstack-models:end --> in ~/.codex/AGENTS.md, with a # budget line with the chosen label and its target effort, and one line per role, using the same labels poteto-mode uses. Codex loads ~/.codex/AGENTS.md into every new thread, so the block applies everywhere. Replace the text between the markers when they exist, append the block when they don't, create the file when it is missing, and never touch anything outside the markers, so re-runs stay idempotent. Shape:

<!-- pstack-models:begin -->
# pstack model configuration. One line per role. Delete a line to fall back to the skill default.
# `inherit-parent` or `auto` as a value: the role runs on the parent chat model (omit `model` and `reasoning_effort`). Alias entries in a panel list still count toward its fan-out.
# budget: large (xhigh)
feature, refactoring: gpt-6.1-sol-xhigh
bug-fix: gpt-6.1-sol-xhigh
perf-issue: gpt-6.1-sol-xhigh
hillclimb: gpt-6.1-sol-xhigh
judgment and prose: gpt-6-astra-xhigh
hardest tasks: gpt-6-astra-xhigh
how explorer: gpt-6.1-sol-xhigh
how explainer: gpt-6-astra-xhigh
why investigators: gpt-6.1-sol-xhigh
why synthesizer: gpt-6-astra-xhigh
reflect tooling: gpt-6.1-sol-xhigh
reflect judgment, divergent, synthesizer: gpt-6-astra-xhigh
arena runners: gpt-6-astra-xhigh, gpt-6.1-sol-xhigh
arena cross-judge pool: gpt-6-astra-xhigh, gpt-6.1-sol-xhigh
swarm workers: gpt-6.1-sol-xhigh
architect runners: gpt-6-astra-xhigh, gpt-6.1-sol-xhigh
interrogate reviewers: gpt-6-astra-xhigh, gpt-6.1-sol-xhigh
<!-- pstack-models:end -->

With the block saved to a file, this replaces or appends it in place. It exits with a message unless the block file starts with the begin marker and ends with the end marker, and unless the target has at most one begin marker with its end marker after it. Markers match only at line start. If AGENTS.override.md exists in the Codex home, Codex loads it instead of AGENTS.md, so the updater tells the user and writes the block there. The write is atomic.

python3 - "${CODEX_HOME:-$HOME/.codex}" <block-file> <<'PY'
import os, re, sys, tempfile
BEGIN, END = "<!-- pstack-models:begin -->", "<!-- pstack-models:end -->"
home, block = sys.argv[1], open(sys.argv[2]).read().strip() + "\n"
if not (block.startswith(BEGIN) and block.rstrip("\n").endswith(END)):
    sys.exit("The block file must start with the begin marker and end with the end marker.")
path = os.path.join(home, "AGENTS.md")
override = os.path.join(home, "AGENTS.override.md")
if os.path.exists(override):
    print("Codex loads " + override + " instead of AGENTS.md, so the block goes there.")
    path = override
text = open(path).read() if os.path.exists(path) else ""
begins = list(re.finditer("^" + re.escape(BEGIN) + r"[ \t]*$", text, re.M))
ends = list(re.finditer("^" + re.escape(END) + r"[ \t]*$\n?", text, re.M))
if len(begins) > 1:
    sys.exit("The file has more than one begin marker. Fix it by hand, then rerun.")
if ends and not begins:
    sys.exit("The file has an end marker without a begin marker. Fix it by hand, then rerun.")
if begins:
    after = [e for e in ends if e.start() > begins[0].start()]
    if not after or len(ends) > 1:
        sys.exit("The begin marker needs exactly one matching end marker after it. Fix it by hand, then rerun.")
    text = text[:begins[0].start()] + block + text[after[0].end():]
else:
    text = text.rstrip("\n") + "\n\n" + block if text.strip() else block
os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
fd, tmp = tempfile.mkstemp(dir=os.path.dirname(os.path.abspath(path)), prefix=".pstack-")
with os.fdopen(fd, "w") as f:
    f.write(text)
    f.flush()
    os.fsync(f.fileno())
if os.path.exists(path):
    os.chmod(tmp, os.stat(path).st_mode & 0o7777)
os.replace(tmp, path)
PY

Then install pstack's agent roles. Codex plugins cannot register roles, so copy them from this plugin with mkdir -p "${CODEX_HOME:-$HOME/.codex}/agents" && cp ../../agents/poteto-agent.toml ../../agents/comment-sicko.toml "${CODEX_HOME:-$HOME/.codex}/agents/", with both source paths resolved from this file's directory. This overwrites only pstack's own two role files.

6. Confirm

Tell the user the block was written and the poteto-agent and comment-sicko roles were installed, and that both apply to new threads. Re-running this skill updates them. For big fan-outs ($pstack:swarm, $pstack:arena, the Orchestrate playbook), add that Codex runs at most [agents] max_threads threads at once, 6 by default, and that [agents] max_depth caps how deep subagents can nest if Codex refuses a nested spawn. Both live in ~/.codex/config.toml.

7. Offer a verification skill (optional)

Check whether the project has a way to drive the real app for proof (a verify-* skill, or an existing harness). If not, offer once: "want a project-local verification skill, so agents can drive the app the way a user does and prove changes work? I can generate one with $pstack:create-verification-skill." On yes, invoke $pstack:create-verification-skill (resolves wherever pstack is installed: workspace, user, or plugin). On no, move on without pushing.

04 同仓库更多 Skills