Why use it: You want to add a repo to the 1,000 set, or update a skill that is stale compared to upstream.
What it produces: A runtime skill tree under skills/repositories/repo-skills/<skill-id>/, a regenerated router, an updated catalog, and a PR that declares full provenance.
1. Required files of a new skill
skills/repositories/repo-skills/<skill-id>/
├── SKILL.md ← bắt buộc
├── references/repo-provenance.md ← bắt buộc
├── references/repo-routing-metadata.json ← bắt buộc (v2)
├── sub-skills/ ← khi upstream có nhiều vùng workflow lớn
└── scripts/ ← script validate/preflight nhỏ, nếu giúp skill an toàn hơn
repo-routing-metadata.json v2 keeps only the minimum: canonical identifier owner/repository, skill ID, taxonomy hash, routing status, and exact assignment. The classification rationale and full evidence live OUTSIDE the runtime tree — in the routing-decision artifact or the handoff directory skills/disco/routing_decision/ of the repo.
Separation: test cases, review notes, generation reports do not live in the runtime skill directory, unless they are genuinely runtime guidance.
2. How to generate: use Creator, don't write by hand
disco --creator -p "/skill:create-repo-skill Create and verify a repository skill for /absolute/path/to/repo."
Then let verify-repo-skill gate it. Classification is a separate step after verify, checked against the fixed taxonomy.
When no family matches exactly → record unclassified unclassified ask the user whether to import. To bring it in, propose a taxonomy extension and wait for approval before changing the canonical taxonomy. Classification being interrupted or unreachable is blocked/failed — not guessing a route at random.
3. Rebuild router (don't hand-edit the generated Markdown)
node cli/packages/coding-agent/src/disco/skills/verify-repo-skill/scripts/update_repo_skills_router.mjs \
--library-root skills/repositories
Flags (read from parseArgs in the script itself):
| Flag | Meaning |
|---|---|
--library-root <dir> |
Directory containing the pair repo-skills/ + repo-skills-router/. Use this when building in a checkout |
--agent-dir <dir> |
Agent root; auto-appends skills/repositories. Do not use together with --library-root |
--template-dir <dir> |
Template directory |
--include-skill <ids> |
Filter the skill set (repeatable or comma-separated) |
--output-router-dir <dir> |
Write the router elsewhere |
--routing-entry <path> |
Add a routing entry |
--router-visibility <v> |
Router visibility |
--timeout <n> |
Lock timeout |
-h, --help |
Print help then exit 0 |
Output on success:
updated <router-dir>: <n> skills, <n> assignments, <n> areas, <n> families
Exit code:
| Situation | Exit |
|---|---|
| Success | 0 |
RouterError: wrong arguments, using both --agent-dir and --library-root, --already-locked without DISCO_IMPORT_LOCK_PATH |
2 |
| Other unexpected error | 1 |
Pass --agent-dir and the script re-runs itself under the lock (unless DISCO_IMPORT_LOCK_PATH is already set) — that is correct behavior, don't think it's hung.
The number must match the current actual: 1000 repositories, 2209 assignment, 20 area, 178 family (countable: wc -l references/index/repositories.jsonl = 1000, assignments.jsonl = 2209, repository-index.jsonl = 1000).
4. Update the public catalog
docs/imported-repo-skills.md
The catalog must match repo-routing-metadata.json and repo-provenance.md. docs/repository-catalog.md (673KB) is a shared data page — if you change it, keep the count, grouping, path, and localized summary section in the Chinese README in sync.
5. Quick on-the-spot checks
# cú pháp Python của mọi script trong skill
find skills/repositories/repo-skills/<skill-id> -type f -name '*.py' -print0 \
| xargs -0 -r python -m py_compile
# liệt kê toàn bộ file để soi cây trước khi mở PR
find skills/repositories/repo-skills/<skill-id> -type f | sort
# docs không được chứa tab
python - <<'PY'
from pathlib import Path
for p in sorted(Path('docs').glob('*.md')):
if '\t' in p.read_text():
print(f'tab: {p}')
PY
6. Refresh an existing skill
disco --creator -p "/skill:refresh-repo-skill Refresh the existing repo skill at /path/to/skill against /path/to/upstream-repository. Preserve correct workflows, update stale guidance, run verification, and prepare a contribution-ready result."
Only after the refresh is done is it considered complete when all 4 groups below are in sync:
- Runtime tree — update every affected public file, not just the
SKILL.mdroot. - Provenance —
references/repo-provenance.mdreflects the current repo state. - License metadata — resolve the license once for the canonical upstream repo at the exact source commit:
gh api "repos/<owner>/<repo>/license?ref=<source-commit>" --jq '.license.spdx_id // empty' - Routing & catalog — compare the new capability scope against the old routing baseline; the review artifact stays outside the runtime skill tree.
Rules for improving an existing skill:
- Stick to evidence: source, upstream docs, examples, or inspected package behavior;
- Keep guidance that is still correct;
- Update provenance when the source commit / package version / evidence set changes;
- Update routing metadata when coverage or selection guidance changes;
- Scripts must be deterministic and safe: avoid downloading, training, starting servers, or file-deletion operations unless there is an explicit gate.
7. Mandatory PR requirements
Every PR that adds/modifies a generated skill repo must declare:
- Upstream repo URL + source commit or tag;
- Model and provider used to generate the skill;
- Reasoning/thinking level (
low/medium/highor the provider's equivalent); - Whether the skill was generated by DisCo, copied from a workflow skill, or edited by hand;
- Verify command / review steps that were run;
- Known gaps, skipped checks, missing credentials, environment limitations;
- Confirmation that
skills/repositories/repo-skills-router/was updated when routing changed.
If using multiple models or multiple rounds, list each model with its role (generation / review / refinement / verification).
8. Final checklist
- Links in README/docs point to files that actually exist
- EN and zh docs updated together when a pair exists
- Runtime skill changes come with provenance + source evidence
- Router and catalog are consistent with skill changes
- PR declares model, provider, reasoning level, verify steps
- Touched scripts have been syntax-checked or verified another way
- The final summary clearly states what was verified and what was not
9. Pitfalls
- Do not manually edit the Markdown the router generates. Edit the generator then rerun
update_repo_skills_router.mjs. - Do not push the routing metadata repo through the general importer graph — the repo graph has its own dedicated import path.
- Do not guess the route.
unclassified/blocked/failedis a valid result; a wrong route is more harmful than no route. - Each skill's license is the final word, not the repo's Apache-2.0. Record it correctly in the metadata
SKILL.md.