Skill Orchestrator v1.0

English is the canonical instruction language in this file. For the complete Simplified Chinese guide, read references/zh-CN.md. 本技能提供完整中英双语支持；简体中文指南见该文件。

Use the machine-local inventory snapshot instead of rescanning skill directories for every task. Apply runtime policy, contract corrections, and explicit user feedback without mutating the inventory, then build the smallest skill set that covers a staged execution plan.

Use the stable unified CLI for new automation:

python scripts/skillctl.py --version
python scripts/skillctl.py help
python scripts/skillctl.py --lang zh-CN help

Direct script commands remain supported for compatibility.

See references/cli.md for stable commands and exit-code guarantees.

Inventory workflow

1. Run the inventory command. On first use it scans configured roots and creates a snapshot; later calls read only that snapshot:

   python scripts/skillctl.py inventory --format markdown

2. Treat the snapshot as the routing source of truth. Default first-use discovery uses adapters for Codex, Agents, Claude, Cursor, and Kiro. Generic/custom roots are opt-in. Missing directories are ignored; whole disks are never scanned.

3. For a reusable machine-readable catalog, write JSON outside the skill directory or to a task workspace:

   python scripts/skillctl.py inventory --format json --output <workspace>/skill-inventory.json

4. Each cached skill includes an inferred contract covering input/output formats, operations, live-control capabilities, side effects, evidence, and inference confidence.
5. When the user asks for a summary, group active skills by category. Report shadowed and byte-identical copies separately instead of presenting them as independent choices.

6. Inspect snapshot status without scanning:

   python scripts/skillctl.py inventory --cache-info

7. Inspect supported discovery adapters without scanning:

   python scripts/skillctl.py inventory --list-adapters

See references/adapters.md for default locations, custom roots, and adapter selection.

Routing workflow

1. Parse the request into:
   • intended deliverable;
   • input artifacts or services;
   • domain;
   • required operations;
   • constraints such as format, venue, fidelity, deployment target, or live application state.

2. Rank candidates from the cached snapshot:

   python scripts/skillctl.py route --task "<user request>" --top 8

3. Review the emitted task contract, hard exclusions, warnings, capability matches, and route confidence. Filter already-cached candidates by platform when required; this does not scan:

   python scripts/skillctl.py route --platform codex --task "<user request>"

   Ask for a counterfactual explanation when a plausible skill was not selected:

   python scripts/skillctl.py route --task "<user request>" --why-not <skill-id>

4. Inspect the highest-scoring candidates. Read the complete SKILL.md for every skill that may be selected before taking task actions.
5. Choose the smallest effective set:
   • select one primary skill that owns the final deliverable;
   • add a supporting skill only when it contributes a required capability absent from the primary;
   • normally use no more than three skills;
   • exceed three only for a genuine multi-stage pipeline with distinct artifacts.
6. State the selected skills and order before using them. Then follow each selected skill faithfully.

The ranking script is a candidate generator, not the final authority. Capability contracts are inferred from metadata and may be incomplete. Validate candidates against the exact trigger conditions in their frontmatter. Route only active instances unless the user asks to compare duplicate or shadowed variants.

Constraint and confidence rules

• Treat explicitly requested live Excel, Chrome, in-app browser, Figma-node, and Vercel capabilities as hard constraints for the primary skill.
• Treat declared incompatible output formats as hard primary-skill exclusions.
• Treat missing or uncertain metadata as a warning and score penalty, not an automatic exclusion.
• Preserve an explicitly named skill even when its inferred contract is incomplete; surface the mismatch as a warning during final judgment.
• Use confidence as a decision aid: high may proceed, medium requires reading close candidates, and low should trigger a short clarification only when the choice materially changes the result.
• Report exclusion reasons when a plausible candidate fails a hard constraint.

See references/capability-schema.md for the inferred skill and task contracts.

Runtime policy and correction workflow

Initialize persistent local configuration once:

python scripts/skillctl.py init-config

This creates ~/.codex/config/skill-orchestrator/policy.json and overrides.json only when absent. Later routes and plans load them automatically.

• Use policy filters to allow or deny platforms, sources, categories, skills, or side effects.
• Use policy biases to express stable local preferences without hard-coding router rules.
• Use confidence thresholds and planning.max_skills to control escalation and plan size.
• Use contract overrides to add or remove formats, operations, capabilities, or side effects when inference is inaccurate.
• Set enabled: false only to hide a skill from routing; it does not uninstall or edit the skill.
• Keep all runtime corrections outside the inventory cache so a route can be reproduced from the cache plus its named configuration.

Pass alternate files with --policy and --overrides. See references/runtime-configuration.md for schemas and examples.

Explicit feedback workflow

Record a confirmed route outcome only after the user accepts or rejects a recommendation:

python scripts/skillctl.py feedback --task "<request>" --accepted <skill-id>
python scripts/skillctl.py feedback --task "<request>" --rejected <skill-id> --accepted <better-skill-id>

Feedback stores a SHA-256 task fingerprint and normalized context key, not the raw request. Matching future contexts receive a bounded score adjustment. Use --no-feedback for a baseline decision or --feedback-file for an isolated profile. Never infer acceptance merely because a skill was executed. See references/feedback-schema.md.

Multi-skill planning workflow

Use the planner when the request contains distinct stages, such as research plus writing, Figma implementation plus browser verification, data analysis plus publication figure creation, or source extraction plus artifact generation.

python scripts/skillctl.py plan --task "<user request>" --max-skills 3

Use --platform <name> to plan from one or more cached platforms without rebuilding the inventory.

The planner must:

1. Use constraint-aware routing to select the final-deliverable owner.
2. Decompose the task into source, research, analysis, production, and verification stages only when those stages are required.
3. Let the primary skill own every stage it can fully cover.
4. Add supporting skills greedily only for remaining uncovered stages.
5. Keep the default set at three skills or fewer.
6. Emit stage dependencies, input artifacts, output artifacts, matched capabilities, role assignments, confidence, and capability gaps.
7. Read the complete SKILL.md for every selected skill before execution and refine the generated plan when a skill's real instructions contradict an inferred contract.

Do not add a support skill merely because it ranks highly. It must own at least one stage or be explicitly requested by the user. See references/planning-schema.md.

Selection rules

Apply these rules in order:

1. An explicitly named skill wins if it is installed and applicable.
2. Prefer an artifact-specific skill over a broad suite for a narrow request, such as pdf, spreadsheets, or presentations.
3. Prefer a suite/router when the request spans a full workflow, such as research-to-paper or graduation-project delivery.
4. Prefer a live-control skill when the user refers to an already open application or authenticated browser state.
5. Prefer a creation skill for new artifacts and a review/polish skill for critique or revision.
6. Do not select two near-duplicate skills unless their instructions cover distinct stages.
7. Do not invoke a skill merely because its name shares a generic word with the prompt.
8. If no candidate has a convincing trigger match, proceed without a specialized skill and say so briefly.

See references/taxonomy.md for category definitions and references/orchestration-patterns.md for common multi-skill sequences.

Conflict resolution

When candidates overlap:

• Compare their frontmatter descriptions against the requested deliverable, not just the topic.
• Give priority to the skill whose required input and promised output match most exactly.
• Use the broader skill only as the primary router when it explicitly coordinates the narrower skill.
• Avoid chaining multiple polishers by default. Select the one matching language, venue, and requested editing depth.
• Avoid combining multiple literature search skills unless the task explicitly requires database diversity or citation verification.
• Preserve user choice when they explicitly request a particular skill, unless it is unavailable or cannot handle the input.

Multi-skill execution contract

Before execution, define a short handoff contract:

Primary: <skill> — owns <final deliverable>
Support: <skill> — produces <specific intermediate artifact>
Order: <support step> -> <primary step> -> <verification step>

Pass concrete artifacts between stages. Do not ask each skill to redo discovery, extraction, or formatting already completed by another stage.

Snapshot and refresh behavior

Never rescan automatically after the first valid snapshot is created. New installs, removals, edits, and plugin changes remain invisible until the user explicitly asks to refresh.

Refresh only with:

python scripts/skillctl.py inventory --refresh

Or refresh and route in one command:

python scripts/skillctl.py route --refresh --task "<user request>"

Or refresh and build a multi-skill plan:

python scripts/skillctl.py plan --refresh --task "<user request>"

If the user names a skill missing from the snapshot, report that the snapshot may be stale and offer an explicit refresh; do not silently scan. An unreadable or schema-incompatible snapshot may be rebuilt because it cannot be used.

Discovery configuration changes such as --adapter, --root, or --project-root require --refresh when a valid cache already exists. Platform filtering does not.

The snapshot is stored at ~/.codex/cache/skill-orchestrator/inventory-v7.json. On first v1.0 use, a compatible v0.6 snapshot is migrated without reading skill directories; the old snapshot remains untouched. Policy, overrides, feedback, diagnostics, and packaging never trigger an inventory refresh. See references/cache-schema.md.

Benchmark and regression workflow

Run the built-in routing and planning benchmark after changing taxonomy, contracts, scoring, discovery, or planning logic:

python scripts/skillctl.py benchmark

The benchmark reports Top-1 accuracy, required-skill recall, forbidden-selection violations, plan-stage coverage, excess-skill rate, pass/fail/skip counts, and a non-zero exit code on evaluated failures. Use --strict-missing when missing expected skills must fail CI, --allow-failures during tuning, and --format json for automation.

Benchmark cases are declarative JSONL and must describe externally observable routing expectations rather than internal score values. See references/benchmarking.md.

Health and release workflow

Run read-only health checks before relying on a route or publishing a release:

python scripts/skillctl.py doctor --deep --benchmark --strict

--deep compares cached fingerprints with current SKILL.md files but never refreshes the cache. --benchmark runs the shared deterministic suite. Resolve every error and strict warning before packaging.

Build a deterministic MIT-licensed release archive:

python scripts/skillctl.py package --output <workspace>/skill-orchestrator-v1.0.0.zip

The package contains only required skill resources, excludes caches and bytecode, normalizes ZIP timestamps, and embeds RELEASE-MANIFEST.json with per-file SHA-256 hashes. See references/release-packaging.md.

Never edit, delete, or reinstall discovered skills during inventory or routing unless the user explicitly asks.