Create Repo Skill

---
name: create-repo-skill
description: "Creates a repo-specific operating Agent Skill for DisCo Researcher from a local repository by inspecting source files and an installed or auto-prepared, backend-aware Python package environment. Use when the user asks to create a skill for a repo, generate repo-specific skills, analyze a local Python package, or build a DisCo skill that may also be exported to compatible agents. If the user gives only a repo path, analyze the repository structure and native tests/examples first, confirm the extraction scope, then use prepare-repo-skill-env to create and verify the minimum CPU/GPU/backend environment set required by that scope. If the request says auto decide, agent-confirm the extraction scope; if it says auto import, import only after successful verification with no unresolved required-backend block."
metadata:
  disco-role: meta
---

# Create Repo Skill

## Purpose

Use this skill to create a high-quality, repo-specific operating Agent Skill for
DisCo Researcher. The managed DisCo copy is the primary runtime destination; a
user may separately export it to Claude Code, Codex, or another compatible
agent, but export is not required for DisCo to use it.

Repo/package guidance is intentionally treated as a high-reuse operating graph: a self-contained skill for a versioned public package can support the same repository across many checkouts, projects, and research tasks. Its approved live destination is therefore the managed repo collection at `~/.disco/agent/skills/repositories/repo-skills/<skill-id>/`, not the current project's `.agents/skills/`. This is a specialized managed deployment: the import must also rebuild the sibling `repo-skills-router` in the same locked transaction, so never send repo output through the generic operating-graph importer.

If the user does not provide a repository path, use the current working
directory as the target repository.

The user may delegate the manual decisions in this workflow. Treat phrases such
as `auto decide`, `agent decide`, `decide the scope yourself`, `auto import`,
`default import`, or `do not ask me to confirm scope/import` as an explicit
decision policy for this create run. The policy has two independent parts:

- `extractionScope: ask` by default, or `agent-decide` when the user delegates
  scope approval.
- `importAfterVerification: ask` by default, or `auto-import` when the user
  delegates the final import decision.

This policy only skips the routine scope approval and final import approval. It
does not authorize unsafe commands, broad dependency installation, mutation of a
user-provided environment that may break it, overwriting an existing skill, or
importing a skill that failed verification. `auto-import` also does not accept
an unavailable or unverified required backend. A required-backend block must be
resolved, removed by an explicitly narrowed extraction scope, or presented for
an informed manual acceptance after final verification.

The user may also provide a temporary Python environment where the package from
that repository has already been installed for inspection. If the user does not
provide that environment, do not stop and ask for one. Defer automatic
environment preparation until after repository structure analysis and either
user confirmation of the extraction scope or agent-confirmation under an
explicit `agent-decide` policy. Then use
`prepare-repo-skill-env` to create, install, and verify the minimum private
inspection environment set whose dependencies and backend variants cover the
confirmed directories, selected workflows, required native verification
candidates, and user requirements, and continue this workflow from the handoff.
The prepare-env skill should prefer Conda when available, use micromamba,
venv, or uv when appropriate, and execute environment creation, installation,
and verification as explicit terminal commands. If no suitable manager or
Python exists, it should make the required host-level runtime installation
visible and obtain authorization before performing it rather than invoking a
bundled bootstrap helper.

The user may also provide a preferred generated-skill output path, a preferred
review/test artifact output path, a preferred environment prefix for automatic
environment preparation, the installed package name, known troubleshooting
notes, and extra extraction requirements. If no output path is provided,
default to creating the generated skill under the repository's own `skills/`
directory. If that directory already exists, create a `disco/` subdirectory
inside it as the active skills root for DisCo-generated output.

The installed Python environment is required so the agent can inspect live APIs, function signatures, modules, imports, CLI entry points, and runtime behavior instead of relying only on source-code guesses. It can be provided by the user or prepared automatically via the prepare-env skill. Treat this environment as private research context. It must not appear in the generated repo skill.

## Reference Map

Read these references as the workflow reaches each stage:

- [references/input-output-and-structure.md](references/input-output-and-structure.md): input collection, canonical skill ids, output path resolution, default runtime skill and `skills/tests/` artifact locations, generated skill tree, and content placement rules.
- [references/repository-evidence.md](references/repository-evidence.md): how to discover source roots, docs, examples, scripts, tests, configs, existing repo-local skills, extraction evidence maps, backend-classified native test/example candidates, and the backend verification plan before extracting skills.
- `../prepare-repo-skill-env/SKILL.md`: backend-aware environment preparation after repository structure analysis, including minimal dependency selection for the confirmed extraction scope, required-backend readiness, and existing-environment mutation safeguards.
- `../workflow-authoring/SKILL.md`: the canonical workflow script, structured args, prepared-environment, coverage, and recovery contract. Read it completely before the first `workflow` call in coordinated generation.
- [references/installed-package-inspection.md](references/installed-package-inspection.md): read-only inspection of the user-provided or automatically prepared installed package environment and how to avoid leaking local environment details.
- [references/planning-and-writing.md](references/planning-and-writing.md): sub-skill boundaries, coverage/depth matrix, dynamic workflow generation, whole-skill integration gates, target file tree planning, generated `SKILL.md` frontmatter, references, scripts, and anti-patterns.
- [../verify-repo-skill/scripts/resolve_repo_license.mjs](../verify-repo-skill/scripts/resolve_repo_license.mjs): resolves one GitHub `license.spdx_id` for the exact source commit and emits the required `NO_LICENSE` fallback/report.
- `../verify-repo-skill/SKILL.md`: final assertion-backed usability test case generation, content-level self-refine, native repo test/example verification, static verification, final coverage report, review package, handoff, and import readiness after this skill has created and integrated the runtime repo skill.

## Required Workflow

Use the agent's available todo or task-list mechanism for this workflow so the
user can see the current phase, especially during repository analysis,
environment preparation, sub-skill generation, review, and handoff to
verification. If the current agent has no todo tool, maintain a visible
checklist in the conversation.

1. User request analysis:
   Read [references/input-output-and-structure.md](references/input-output-and-structure.md). Identify the repository path, Python inspection environment if provided, preferred conda prefix if provided, skill output directory, review/test artifact directory, extra extraction requirements, delegated decision policy (`extractionScope` and `importAfterVerification`), and any other information that can affect extraction. Use the current working directory when the repo path is omitted. Resolve the canonical skill id, active skills root, generated skill directory, artifact directory, and private default inspection prefix before writing files. If the user did not provide a usable Python inspection environment, do not prepare it yet; record the default prefix under `$DISCO_CODING_AGENT_DIR/envs/<chosen-skill-id>-inspection` when that variable is set, otherwise under `~/.disco/agent/envs/<chosen-skill-id>-inspection`, and defer installation until after repository structure analysis confirms which directories will be used.
2. Repository structure analysis:
   Read [references/repository-evidence.md](references/repository-evidence.md). Inspect the repository tree, package metadata, source roots, docs, examples, scripts, tests, configs, and existing repo-local skills. Build a concise extraction evidence map that names directories to include and directories to exclude from later extraction context. Also build a native test/example candidate map from repo-owned examples, tests, notebooks, CLI snippets, fixtures, and smoke scripts. Classify each candidate by workflow, safety, backend requirement (`cpu`, `cuda`, `rocm`, `mps`, accelerator-specific, or `any`), backend criticality (`required`, `optional`, or `alternative`), CPU substitution (`full`, `partial`, or `none`), dependency variant, hardware prerequisites, and verification expectation. After the extraction scope is confirmed, derive a backend verification plan for included workflows: required/optional backend coverage, minimum environment set, hardware probes, preparation smoke checks, final native cases, and the blocking consequence of unavailable required hardware. Separately build a source script inventory for repo-owned `scripts/`, `tools/`, `bin/`, example scripts, and workflow helpers, classifying each useful script as copy, adapt, wrap, reference-only, or exclude with a concrete reason. Do not run native tests/examples in this phase. If `extractionScope` is `ask`, ask the user whether the directory scope and backend plan are reasonable before continuing and incorporate any correction. If `extractionScope` is `agent-decide`, do not stop for routine approval; mark both as agent-confirmed, briefly report include/exclude and backend decisions to the user, record the decision mode and rationale under the review/test artifact directory's `reports/integration/` subtree when practical, and continue.
3. License resolution:
   After the canonical GitHub repository identity and exact source commit for this
   run are known, resolve the repository license once before sub-skill generation:

   ```bash
   node ../verify-repo-skill/scripts/resolve_repo_license.mjs \
     --repository <owner/repository> \
     --source-commit <40-hex-source-commit> \
     --json > <artifact-root>/reports/license-resolution.json
   ```

   Use the returned `value` for every root and sub-skill `SKILL.md`. A successful
   non-empty `license.spdx_id` is authoritative, including `NOASSERTION`; missing
   `gh`, authentication or API failures, 404, unparseable or missing values become
   `license: NO_LICENSE`. Record repository, source commit, status, value, reason,
   and updated file count under `reports/`; do not include raw API responses or
   credentials in runtime files. `NO_LICENSE` is a warning, not a legal
   conclusion, and does not by itself block verification or import.
4. Environment preparation:
   Read and use `../prepare-repo-skill-env/SKILL.md`. Prepare or verify the Python inspection environment only after the repository structure analysis and backend verification plan are confirmed. Pass the included/excluded directories, package metadata, backend-classified native candidate map, backend verification plan, and user extraction requirements into the install plan. Install the minimum environment set that satisfies every required backend for selected capabilities, not merely the smallest CPU-importable set. Usually one GPU-capable environment can cover CPU checks; use separate prefixes only when dependency variants conflict or an independent CPU fallback claim also requires verification. Do not install optional backend packages for excluded or unselected workflows. If the user provided an existing environment and verification shows that reinstalling, upgrading, or repairing packages may mutate or break it, ask before modifying that environment. If modification is not allowed, create a new private prefix when permitted. Continue automatically only from an `ok` handoff. If a required backend is unavailable, either narrow the extraction scope with user approval, stop with a failed handoff, or continue drafting only after the user explicitly accepts a `partial` handoff; carry that block forward and disable auto-import.
5. Sub-skill structure generation:
   Read [references/installed-package-inspection.md](references/installed-package-inspection.md) and [references/planning-and-writing.md](references/planning-and-writing.md). Use repository evidence plus installed-package inspection to plan only the sub-skill structure first: canonical sub-skill ids, responsibilities, boundaries, evidence sources, target files, expected references/scripts, source-script imports or adaptations owned by each sub-skill, troubleshooting references and failure modes each sub-skill must cover, native test/example candidates relevant to each sub-skill, cross-references, and review rubrics. The main agent owns this structure and should optimize it for future usability, not for mirroring source folders mechanically. Do not write the detailed sub-skill content in this phase. Keep the planned overall generated skill shape compatible with this skill's existing root `SKILL.md`, `references/`, `scripts/`, and `sub-skills/` structure.
6. Coordinated skill generation:
   Before the first `workflow` call, read `../workflow-authoring/SKILL.md` completely. When running in DisCo, use the built-in `workflow` tool to coordinate generation. Keep the JavaScript `script` short and put complete, Markdown-rich sub-skill briefs in structured `args.jobs` or `args.briefs`; never paste those briefs into a template literal in the script. Each planned sub-skill id must appear in the relevant phase and in each `agent()` call's `subSkill` option, making progress visible while subagents write and revise sub-skills. In other agents, use the same process with whatever task, subagent, or manual sequencing tools are available. Each subagent prompt must include a complete scope-specific brief from the structure plan: target sub-skill id, exact `sub-skills/<id>/` output subtree, frontmatter name requirement, responsibility, included and excluded capabilities, evidence files to inspect, installed-package facts to verify, required references/scripts, source scripts to copy/adapt/wrap or explicitly exclude, troubleshooting failure modes to cover, links to create, related native test/example candidates, and the acceptance rubric. Do not delegate with a short generic request. The workflow should generate sub-skills in parallel when possible, with one or more subagents extracting each planned sub-skill from its assigned evidence. Use the successful prepare-env handoff's canonical `workflowEnvironment` object as `args.environment`: it must contain the verified absolute `executable`, the distribution `package`, the exact `version`, and optional `cwd`; every lane must pass `environment: args.environment` to `agent()` so the runtime asserts it before session startup. Do not pass the private report fields `pythonExecutable`, `expectedDistribution`, or `expectedVersion` as the authored `agent()` contract, and never fall back to ambient Python. Each drafting or revision subagent must write its assigned runtime files directly under the final generated skill subtree, including `SKILL.md`, bundled `references/`, and bundled `scripts/` as applicable. Do not design the workflow so subagents return full sub-skill Markdown, scripts, or JSON drafts for the main agent to write into the skill directory later. Return one row per lane with its stable id, `ok`, `result`, and `error`, then return top-level `complete`, `missing`, and `errors`; `results.length` is not a success count. The main agent reviews and evaluates the files the subagent wrote against repo-specific rubrics, sends concrete feedback back to the relevant subagent or revision pass when a sub-skill is thin, inaccurate, poorly routed, not self-contained, incorrectly named, missing useful bundled script imports/adaptations, or missing troubleshooting coverage, and repeats until each sub-skill passes review. If any lane fails, do not silently integrate the successful subset: preserve the original jobs and stable IDs, start a recovery workflow containing only current `missing` IDs, set `recoveryOfRunId` and `recoveryRound`, and stop only with an explicit complete result or a reported no-progress/safety-cap condition. Each subagent or revision pass should hand back only its covered capabilities, files created or updated, evidence used, related native test/example candidates, source scripts imported/adapted/excluded with reasons, troubleshooting coverage, checks performed, intentional omissions, and uncertainties for integration notes under the review/test artifact directory.
7. Whole-skill integration and coverage reconciliation:
   After all sub-skills pass main-agent review, the main agent writes the outer `SKILL.md`, repo-level `references/`, and repo-level `scripts/`, then performs a dedicated whole-skill integration pass before verification. Reconcile the subagent outputs into one coverage/depth matrix, one native test/example candidate map, one backend verification plan, one source script import map, one troubleshooting coverage map, and one long-tail gap register under the review/test artifact directory's `reports/integration/` subtree. Recheck backend criticality whenever integration adds, removes, or changes a capability; if the minimum environment set is no longer sufficient, return to `prepare-repo-skill-env` before final native verification. Check root routing, sub-skill boundaries, cross-references, terminology, duplicate content, bundled reference/script ownership, source-repo dependency leaks, whether useful repo scripts were copied/adapted/wrapped into the appropriate root or sub-skill `scripts/` location, whether primary workflows have actionable troubleshooting guidance, and whether every user-facing repo capability has an owner or an explicit gap. Also plan one or two integrated difficult usability cases that exercise multiple sub-skills or root-plus-sub-skill routing; prefer adapting real repo tests/examples from the native candidate map, and create synthetic cases only when repo evidence has no suitable integrated candidate. If integration finds a thin, inconsistent, or missing area, send it back to the responsible subagent or run a focused revision pass before proceeding.
8. Routing decision preparation:
   After the whole skill graph is integrated and before handing it to
   `verify-repo-skill`, classify the original repository against the exact
   fixed taxonomy using the repository checkout as the primary evidence source
   and the generated skill only as navigation context. Assign zero or more
   exact area -> family paths; every assignment needs its own rationale and at
   least one non-generated repository evidence item. Reject keyword-only,
   dependency-only, optional-integration, example-only, and context-collision
   matches. If no exact family is supported, record `unclassified` with a
   bounded reason rather than inventing a weak assignment. Interrupted or
   inaccessible inspection is `blocked` or `failed`, not a guess. Write
   `skills/disco/routing_decision/classification.json` and
   `skills/disco/routing_decision/evidence.md` outside the runtime skill graph,
   then write the candidate minimal v2
   `references/repo-routing-metadata.json` from the same decision. Do not put
   evidence, rationale, confidence, source checkout paths, or scenario fields
   in the runtime JSON; `verify-repo-skill` remains the final authority and may
   repair or reject the candidate before import.
9. Content-level self-refine and usability verification:
   After the runtime skill directory, root `SKILL.md`, sub-skills, bundled references, bundled scripts, repo provenance, coverage/depth matrix, integration notes, long-tail gap register, backend verification plan, native test/example candidate map, and subagent review notes are complete, use `../verify-repo-skill/SKILL.md` for the final assertion-backed usability test cases, content-level self-refine, native repo test/example verification, static verification, final coverage report, review package, and import-readiness handoff. Pass it the generated skill directory, artifact directory, repo evidence summary, sub-skill plan, review rubrics, integration artifacts, environment-preparation handoff, backend verification plan, native candidate map, delegated `importAfterVerification` policy, and any user verification focus. Do not generate usability test cases or verification reports directly in this skill.

## Non-Negotiables

- Do not create generated skill content that depends on the original repository checkout remaining available. Copy, distill, adapt, or wrap source repo material into the generated skill's own `references/` or `scripts/`.
- Do not leave runtime instructions or Markdown links that point to source repo scripts, examples, docs, notebooks, tools, configs, or absolute checkout paths. If a source repo script is needed for future use, create a bundled replacement under the generated skill's `scripts/` or nearest `sub-skills/.../scripts/` directory and link that bundled path.
- Do not replace a useful, safe, repo-maintained script with prose-only Markdown when it can reasonably be copied, adapted, or wrapped as a bundled skill script. If a script is excluded from bundling, record a concrete reason such as unsafe side effects, external credentials, excessive size, generated/vendor status, or irrelevance to the selected workflows.
- Do not leak the user's local Python executable, activation command, virtualenv or conda name, machine-specific paths, local checkout path, or `pip show` installation location into generated public skill files.
- Do not stop solely because the user omitted a Python inspection environment. After repository structure analysis and either user confirmation or explicit agent-confirmation of the extraction scope, use `prepare-repo-skill-env` to prepare one automatically, then continue this workflow from its verified handoff.
- Do not prepare a new inspection environment before repository structure analysis has identified and confirmed the directories that will drive skill extraction, unless the user explicitly asks to prepare an environment as a standalone task.
- Do not install broad extras, all optional dependency groups, dev requirements, or backend packages when only a smaller set is needed for the confirmed extraction scope and user requirements.
- Do not equate "minimum environment" with CPU-only. Satisfy every required
  backend in the confirmed scope, and do not use a CPU import as proof of a
  GPU/accelerator capability when `CPU substitute` is `partial` or `none`.
- Do not silently discard a required native candidate because its hardware is
  unavailable. Narrow the scope, stop, or carry an explicitly accepted partial
  verification block into the final report.
- Do not let `auto-import` bypass an unresolved required-backend block. Require
  an informed manual import decision after final verification if the user
  chooses to accept that limitation.
- Do not mutate a user-provided existing environment to repair or reinstall packages without asking when that change may break the user's environment. If the user declines, use a new private inspection environment instead.
- Do not overwrite or merge into an existing skill directory unless the user explicitly asks to update that exact skill.
- Do not treat `skills/tests/` as an existing skill directory. It is the review/test artifact area.
- Do not write `evals/`, verification reports, human-review notes, publication checklists, prompt samples, staleness audits, usability test cases, or other check-only artifacts inside the generated repo skill directory. Those are owned by `verify-repo-skill` and belong under the configured review/test artifact directory, defaulting to `<repository-path>/skills/tests/<chosen-skill-id>/`, with concrete cases in `test-cases/` and reports or review documents in `reports/`.
- Do not run the original repository's native examples, tests, notebooks, or scripts as final ground-truth checks until all sub-skills have been generated, reviewed, and integrated into one coherent runtime skill. Before that point, discover and classify native candidates only.
- Prefer verified package facts over guesses. Use docs, examples, and tests for intent; use source code and installed-package inspection to confirm API and runtime claims.
- Every generated repo skill must include `references/repo-provenance.md` with the source commit, branch or tag when available, dirty state, package version, and relative evidence paths so future agents can detect staleness.
- Every generated repo skill must resolve one repository-level license after the canonical GitHub identity and exact source commit are known. Write that same non-empty single-line value as top-level `license` in the root and every sub-skill `SKILL.md`; preserve GitHub's `NOASSERTION` value when returned, use `NO_LICENSE` only when the GitHub CLI result is unavailable, and report the repository, commit, status, and reason to the user when a fallback is used.
- Every generated repo skill must include a minimal v2
  `references/repo-routing-metadata.json` containing only `schema_version`,
  canonical `owner/repository` `repo_id`, `skill_id`, the current taxonomy hash,
  `routing_status`, exact `area`/`family` assignments, and an
  `unclassified_reason` only for an unclassified result. Do not put evidence,
  rationale, confidence, source checkout paths, or scenario fields in this
  runtime JSON. The detailed decision belongs in the external
  `skills/disco/routing_decision/` artifact and is validated by
  `verify-repo-skill` before import.
- Every generated root and sub-skill `SKILL.md` frontmatter must double-quote
  `description`, declare `metadata.disco-role: operating`, and include
  `disable-model-invocation: true` so imported repo skills are available only
  in Researcher mode and are routed through `repo-skills-router` in compatible
  targets instead of all appearing in the model-visible skill list. The
  `repo-skills-router` skill itself is also `operating`. Canonical and exported
  routers remain model-visible, while DisCo's live router preserves the user's
  `disco repo-skills router enable|disable` policy. Codex exports add the required `agents/openai.yaml` policy during
  `import-repo-skills-to-agent`; do not add Codex-specific files to the source
  repo skill during creation.
- Every generated package repo skill should include troubleshooting guidance for install/import, optional dependencies, data/config validation, CLI/API misuse, and workflow-specific failure modes when those surfaces exist. Put cross-cutting package issues in root `references/troubleshooting.md` and workflow-specific failures in the nearest sub-skill `references/troubleshooting.md`.
- Every generated sub-skill directory basename, `SKILL.md` frontmatter `name`, workflow `subSkill` option, coverage/depth matrix output location, and usability target id must use the same canonical lowercase-hyphen sub-skill id. Do not add the repo name to sub-skill ids unless it is truly needed to disambiguate two sibling sub-skills, because the root skill already names the repository.
- Keep generated root and sub-skill `SKILL.md` files router-like. Move API tables, workflow depth, CLI catalogs, model lists, data schemas, long examples, and troubleshooting matrices into the nearest bundled `references/`.
- After verification, follow `verify-repo-skill`'s locked import protocol: use `ask_user_question` when import approval is still set to `ask`; when the user explicitly delegated `auto-import`, import without asking again only after successful verification with no partial handoff or unresolved `BLOCKED_REQUIRED_BACKEND`. In both cases, run `verify-repo-skill/scripts/import_repo_skill.mjs` with the verified runtime skill directory and its external routing handoff. That helper stages and recursively validates the runtime tree, installs it under `~/.disco/agent/skills/repositories/repo-skills/<skill-id>/`, rebuilds the sibling live DisCo `repo-skills-router` under the global lock, and restores the previous skill, repository index, and router if the transaction fails. Pass `--overwrite` only after approval to replace that exact existing repo skill. Do not hand-edit router Markdown or manually combine a copy command with the router updater. Do not synchronize into other agent tools during this workflow; use `import-repo-skills-to-agent` only when the user explicitly asks to export DisCo's managed skill library.
- Do not reinterpret repo-to-skills output as ordinary project-scoped output merely because construction ran inside one checkout. Its self-contained, versioned package contract is the evidence for high reuse; if a candidate is actually bound to private project state and cannot satisfy that contract, it is not import-ready for this repo library.

## Output Summary

By the end, the user should have:

- A generated self-contained repo skill directory containing `SKILL.md`, `references/repo-provenance.md`, `references/repo-routing-metadata.json`, and when useful, `sub-skills/`, additional `references/`, and `scripts/`.
- A unified review/test artifact directory path, defaulting to `<repository-path>/skills/tests/<chosen-skill-id>/`, with `test-cases/` for concrete usability/native-backed/synthetic case directories and `reports/` for integration notes, coverage/depth matrix, native test/example candidate maps, evals, verification reports, final reports, and human-review artifacts.
- A backend-classified native candidate map and backend verification plan that
  determine the minimum CPU/GPU/accelerator environment set.
- A private `ok`, explicitly accepted `partial`, or `failed`
  environment-preparation handoff when the Python inspection environment had
  to be created automatically.
- A handoff to `verify-repo-skill` that distinguishes public skill content, artifact location, repo evidence used, generated sub-skills, integration artifacts, coverage/depth matrix, native test/example candidates, long-tail gaps, and review rubrics.
- After `verify-repo-skill` completes and import is approved by the user or safely authorized by `auto-import` with no required-backend block, a DisCo user import under `~/.disco/agent/skills/repositories/repo-skills/<skill-id>/` plus an updated sibling live `repo-skills-router` entry that DisCo Researcher can use in a new session without any cross-agent export.