Create Paper Skills

Create Paper Skills

Purpose

Use this skill as the DisCo entry point for paper-to-skill construction in Creator mode. It wraps the Paper2Skills Distiller workflow in the same peer role that create-repo-skill plays for repository/package construction: collect the input contract, route to the correct workflow skills, validate artifacts, run at least a meaningful recovery smoke experiment when allowed, and produce reusable module-level skills.

Prefer a filled TOML config over free-form prompt fields. The reusable template is bundled at assets/distiller-run-config-template.toml; a longer reusable agent prompt is bundled at assets/standard-distiller-run-prompt.md.

Distillation Anchor And Stages

Treat the paper, and any explicitly permitted implementation evidence, as the source anchor z for task-agnostic distillation. If the user instead starts from a concrete recovery or replication task, record the task anchor as tau = (q, D, E, g) and classify the run as task-oriented. Do not invent a task tuple for a paper-only request.

Organize the run as the same four stages used by distill-ml-knowledge:

1. Scope the capabilities Q from paper understanding and module planning, including non-goals and verification targets.
2. Ground Q in paper evidence X, with source/version provenance, implementation-evidence boundaries, exclusions, and assumptions.
3. Construct candidate module graph G_tilde, including module boundaries, references, scripts, links, and recovery interfaces.
4. Verify the candidate into accepted graph G and construction record R through module validation, executable recovery, analysis, refinement, final validation, deployment review, and handoff. A paper-only run uses representative recovery/operating checks; it does not claim a task-level outcome that was not part of the anchor.

Workflow Classification

• When the primary knowledge source is a software repository or package, use create-repo-skill instead.
• When the primary knowledge source is a paper, use this skill and then load paper-skills-distiller.
• If the user provides both a paper and an implementation repository, treat the repository as pre-recovery evidence only. Recovery must not read it.
• If the workflow classification is ambiguous and both repository and paper flows are plausible, ask one concise clarification before starting.

Required Input Contract

Before source downloads, environment setup, or recovery, identify these fields from the prompt or config. Ask only for values that cannot be inferred safely:

• config_path: preferred path to a filled TOML config.
• workspace_root: workspace that will contain distillation and generated-skill outputs.
• paper_source: local PDF/text path, direct PDF URL, arXiv URL/id, or paper title.
• paper_slug: stable snake_case id for this paper/version.
• original_repo_source: local repo path, Git URL, none, or unknown.
• source_acquisition: whether remote paper/repo sources may be downloaded/cloned and whether title top hits may be selected automatically.
• repo_discovery_mode: ask, auto, or disabled when original_repo_source is unknown. Default is ask.
• generated_skills_root: output root for generated module skills.
• attempt_dir or permission to use the default distillation directory: <workspace_root>/<paper_slug>/distillation.
• recovery_target: dataset, split, metric, target value, and whether the agent should propose the fastest faithful target first.
• recovery_mode: hard or soft; default is hard.
• runtime_constraints: model path, environment path, GPU ids, network/API setup, and environment mutation rules.
• iteration_budget: maximum refine cycles after the first recovery. Default is 10; the user may set any non-negative integer.
• language_preference: language for final user summaries. Generated skill artifacts stay in English.

If no config_path is supplied, create or request one based on assets/distiller-run-config-template.toml when the run is more than a quick one-off. For batch work, require a TOML config with one [[runs]] entry per paper.

Clarification Triggers

Ask before proceeding when:

• The paper title or URL resolves to multiple plausible papers.
• original_repo_source is unknown, repo_discovery_mode is ask, and the next step would search for an implementation repo.
• Repo discovery returns multiple plausible candidates or the selected top candidate is not clearly tied to the paper.
• The recovery target is unspecified and the next step would launch an expensive recovery; read the paper first, propose the fastest faithful target, and ask for confirmation.
• Recovery mode is omitted and the user request implies reduced/proxy success might be acceptable; otherwise default to hard.
• Runtime setup might mutate a shared conda/virtualenv environment.
• The distillation directory already exists and repairing/resuming could overwrite evidence.

Required Workflow

Use the agent's todo/task-list mechanism for visibility. If workflow or subagent facilities are available, use them only where they help parallelize module skill generation or review; ordinary sequential Distiller stages do not require workflow orchestration.

1. Load this skill and, for detailed rules, load ../paper-skills-distiller/SKILL.md.
2. Validate the user input. If config_path exists, run:

bashCopy code
python <skills_root>/paper-skills-distiller/scripts/read_run_config.py \
  <config_path> \
  --output <workspace_root>/distiller_run_config.normalized.json

For one run in a batch, also write a selected normalized run JSON with --slug <paper_slug> --run-only.

3. Resolve remote or title-based sources before distillation initialization. Prefer ../paper-skills-distiller/scripts/resolve_sources.py for local paths, direct URLs, arXiv ids/URLs, arXiv title search, Git repo URLs, and bounded GitHub repo discovery when repo_discovery_mode=auto. Record acquisition evidence, candidates, selected URLs, clone commands, and blockers.
4. Initialize the distillation directory with ../paper-skills-distiller/scripts/init_run.py, preserving iteration_budget, recovery_mode, generated_skills_root, resolved paper_path, optional resolved original_repo_path, and selected normalized run config.
5. Load ../plan-paper-skill-modules/SKILL.md. Extract/read the paper, create paper_profile.md, module_plan.json, and no more than five module documents under modules/.
6. Validate modularization with ../plan-paper-skill-modules/scripts/validate_module_plan.py. Do not perform heavyweight model, package, dataset, or GPU probing before this succeeds.
7. Load ../create-paper-module-skill/SKILL.md. Convert each module document into a generated skill under generated_skills_root.
8. Validate every generated module skill with ../create-paper-module-skill/scripts/validate_skill_tree.py --run-tests and save a JSON log under generated_skills_validation/.
9. Load ../prepare-paper-recovery-env/SKILL.md. Create environment/runtime_handoff.json and environment/logs/command_log.json from bounded runtime probes and active setup. When packages, model cache, datasets, or benchmark files are missing, use the prepare-env isolated environment/data acquisition path before deciding the stage is blocked.
10. Load ../recover-paper-result/SKILL.md. Run the strongest feasible fast recovery experiment allowed by recovery_mode and runtime_constraints, using only allowed recovery sources. The recovery must exercise generated skills and save executable command evidence.
11. Run the recovery experiment validator and save recovery/experiment_validation.json.
12. Load ../analyze-paper-recovery/SKILL.md. Write analysis/analysis_report.json and analysis/feedback.md.
13. If analysis returns refine, update the relevant module docs, generated skills, tests, runtime handoff usage, and recovery harness, then rerun validation, recovery, and analysis until accepted or the configured iteration_budget is exhausted.
14. Run the final Distiller artifact validator and save final_validation.json.
15. Write the organized final report with ../paper-skills-distiller/scripts/write_final_report.py, then validate the reported stage. Final reports belong under <attempt_dir>/reports/final/, not in the generated skill directory or a top-level Distiller directory.
16. If the run is accepted and the generated operating graph passes final validation, assess the graph's reuse as a separate deployment decision. Select project scope at <project-dir>/.agents/skills/ when the modules are tied to this task, project layout, private data, evaluator, benchmark instance, or runtime; also select project when cross-project reuse remains uncertain. Select managed scope at ~/.disco/agent/skills/ only when the complete module graph is self-contained, source/version/provenance backed, independent of transient run state, verified on representative uses, and expected to apply across projects or research tasks. Use the Creator session's working directory as <project-dir> unless the user explicitly selected another project. Keep all module skills in one scope.
17. Present the reusability rationale, exact generated graph revision, selected scope, all destination paths, entry skill, final validation evidence, unresolved limits, collisions, and shadowing impact. Ask for approval of that exact import. Any overwrite requires separate approval.
18. After approval, resolve distill-ml-knowledge from the visible skill registry and run its scripts/import_operating_skill_graph.mjs once with every generated module skill root. Use --scope project --project-dir <project-dir> or --scope managed --agent-dir ~/.disco/agent as approved. Do not copy distillation, recovery, analysis, test, or report artifacts.
19. Write researcher-handoff.md under the distillation directory with the task, paper source/version, reuse rationale, selected scope, exact imported paths, module skill ids, graph entry point, recovery and validation evidence, and unresolved limits. Suggest /researcher only after import, or clearly state that the skills remain staged when the user declines it.

Recovery Discipline

• hard mode must not accept proxy, toy, reduced, fallback, cache-only, or smaller-model recovery as success.
• soft mode may accept reduced/proxy recovery only when it is explicit, justified, executable, mechanism-checked, and validator-approved.
• Recovery must not read the original implementation repo. Use the paper, module docs, generated module skills, runtime handoff, datasets, and general public package documentation only.
• Do not report blocked merely because the active Python lacks packages (torch, transformers, vllm, nltk, etc.), because no local model cache exists, or because a dataset is absent locally. First run the allowed preparation steps: create/reuse an isolated environment under $DISCO_CODING_AGENT_DIR/envs/ or ~/.disco/agent/envs/, install the smallest required packages with timeouts, attempt permitted bounded model or dataset acquisition, and ask for missing credentials/permissions when they are truly required.
• If a user permits temporary simplification for this run, still create at least one data item, run at least one real training/inference/evaluation command when the paper task involves runtime behavior, and save the trace.
• Do not mark a run complete based on hand-written JSON artifacts alone. The primary recovery result must come from an executable command log.

Output Contract

By the end, the user should have:

• A normalized run config or explicit record of prompt-derived fields.
• One distillation directory with the Distiller artifact contract.
• English module-level generated skills under generated_skills_root.
• Validation logs for module plan, generated skills, recovery experiment, and final distillation contract.
• reports/final/final_report.md and reports/final/final_report.json, alongside any verification or generated-skill review reports under reports/.
• An operating-graph reusability decision, approved project/managed import result when requested, and researcher-handoff.md with exact live paths.
• A final summary in the requested language explaining accepted status, blockers, recovery evidence, generated skill paths, and remaining gaps.