---
name: learn-skill
description: |
  Build and evolve domain skills inside Codex using isolated subagents, file-based handoffs, live web research, and persistent memory. Use when the user wants Codex to learn a bounded professional workflow, distill it into a reusable skill package, and iteratively improve it through closed-book evaluation without writing a custom orchestrator.
---

# learn.skill

`learn.skill` is a no-code orchestration skill for Codex. It builds and evolves domain skills through isolated subagents, persistent files, live research bundles, and repeatable evaluation loops.

## Primary goal

Convert a bounded domain goal into a reusable skill package that can:

- operate at general-practitioner level for the chosen domain
- pass structured evaluation without the main agent participating in execution or judging
- retain long-lived memory across runs and across future scenarios
- separate live research evidence from closed-book execution inputs

The current scenarios are:

- `scenarios/public-opinion/` for Chinese public-opinion risk analysis
- `scenarios/finance-rumor/` for listed-company rumor verification

## Non-negotiable rules

1. The main agent is an orchestrator-observer only.
2. The main agent must not answer evaluation cases, generate gold answers, or score cases.
3. All subagents default to `fork_context=false`.
4. Communication happens through files only. Subagents do not directly message each other.
5. Agent depth is capped at two levels: orchestrator -> subagent -> grandchild.
6. `ExecutorAgent` receives only `skill_package/` plus one `case_pack.json`.
7. `JudgeAgent` receives only the current case, the executor result, and the minimum rubric/gold needed for scoring.
8. `final_hidden` failures return aggregate results and failure classes only. Do not expose gold details to repair loops.
9. Live research stores only `URL + metadata + structured short excerpts + access timestamp + tier`; do not persist long page bodies.
10. Every run must append durable records to scenario and global memory before the thread ends.
11. `demo runs` are strictly off the training path unless the user explicitly promotes them into research backlog.

## Repository map

- `memory/`: global persistent memory and evolution logs
- `references/`: orchestration rules, source confidence policy, prompt contracts, schema reference
- `templates/`: canonical starter payloads for contracts and outputs
- `runs/demo-<id>/`: ad hoc demo runs that do not enter training or memory by default
- `scenarios/<name>/`: one scenario pack with its own memory, corpus, eval sets, skill package, and run history

## Execution protocol

### 1. Prepare the scenario

For a new learning request:

1. Read `memory/global-memory.md`
2. Read the target scenario's `scenario.yaml` and `memory.md`
3. Read `references/workflow.md`
4. Create or refresh the next run directory under `scenarios/<name>/runs/<run_id>/`
5. Write a `manifest.json` that declares:
   - run id
   - scenario
   - stage
   - files visible to each agent
   - hidden-set restrictions
   - whether the run is `bootstrap_seed`, `live_corpus`, or `demo_only`

### 2. Spawn isolated agents

Use these role boundaries:

- `SpecAgent`: outputs `task_contract.json`
- `ResearchAgent`: populates `corpus/` and source index; may spawn grandchildren for source streams
- `DistillAgent`: updates `skill_package/`
- `CaseBuilderAgent`: updates eval case packs and judge bundles
- `ExecutorAgent`: runs closed-book on one case at a time
- `JudgeAgent`: writes score and repair reports
- `RepairAgent`: revises the skill package from allowed failure summaries only

Only `ResearchAgent` may spawn grandchildren in the main learning flow.

### 3. Preserve state aggressively

For each run, write:

- `runs/<run_id>/manifest.json`
- `runs/<run_id>/traces/*.jsonl`
- `runs/<run_id>/outputs/*.json`
- `runs/<run_id>/summaries/*.md`

Update:

- `memory/global-evolution.jsonl`
- `scenarios/<name>/evolution.jsonl`
- `memory/global-memory.md` when a rule generalizes across scenarios
- `scenarios/<name>/memory.md` when a rule generalizes across runs inside one scenario

### 4. Respect dataset tiers

- `train`: usable for learning and rule shaping
- `dev`: usable for automated iteration
- `canary_hidden`: usable for automated blind checks, but only failure summaries may flow into repair
- `final_hidden`: stage gate only; only aggregate outcomes may flow into repair

If `final_hidden` fails twice in a row, log a process-level defect in `memory/global-evolution.jsonl`.

### 5. Respect live research and demo boundaries

- Live research artifacts belong under `scenarios/<name>/corpus/raw-index/` and `scenarios/<name>/corpus/research-bundles/`.
- `CaseBuilderAgent` consumes research bundles, not webpages directly.
- `demo runs` belong under `runs/demo-<id>/` and must not modify `corpus/`, `eval/`, `memory.md`, `global-memory.md`, or any evolution log unless the user explicitly requests promotion.

## What to read next

- Read `references/workflow.md` for stage-by-stage behavior.
- Read `references/source-rating.md` before any research run.
- Read `references/prompt-contracts.md` before spawning agents.
- Read `references/schemas.md` before editing contracts, research artifacts, eval files, or memory logs.

## Scenario loading

The root skill does not contain domain rules. Domain behavior lives in scenario packs and scenario-specific `skill_package/` directories.