Refresh Repo Skill

Refresh Repo Skill

Purpose

Use this skill when an existing repo-specific Agent Skill should continue describing the same repository, but the repository itself has changed since the skill was created or last maintained.

Typical requests include:

• Refresh an old skill after new commits, releases, branches, APIs, CLIs, config formats, examples, or dependencies changed.
• Audit a skill for stale claims against the current repository code.
• Update copied references, scripts, workflows, troubleshooting, or usability cases that no longer match the repo.
• Rebuild the skill's repository evidence without discarding the skill's useful identity, routing, or prior coverage.

This workflow is different from extend-repo-skill: use extend-repo-skill when the user asks to add a new capability or deeper coverage to a working skill. Use this skill when repository drift is the main reason the skill may be wrong.

Inputs

Gather or infer:

• Existing skill directory containing SKILL.md.
• Current repository path to use as the source of truth.
• Existing references/repo-provenance.md from the skill, when present.
• Optional previous repository baseline, branch, tag, release, commit, or date when the skill has no provenance file.
• Python inspection environment and installed package name when live API or CLI verification is needed.
• Existing review/test artifact directory, if any.
• Desired review/test artifact output directory, if the user has a preference.

If the existing skill directory is missing or does not contain SKILL.md, stop and ask for the correct skill path. If the repository path is missing and cannot be inferred from the current working directory or user request, ask for it.

Reference Map

Read these references as the workflow reaches each stage:

• references/change-detection-and-staleness-audit.md: identify the current repo state, optional baseline, stale claims, and affected skill areas.
• references/refresh-editing.md: edit the existing skill in place, replace outdated guidance, preserve useful identity, and update tests/scripts/references.
• references/verification-and-handoff.md: run stale-claim checks, live verification, usability review, and final handoff.
• ../verify-repo-skill/scripts/resolve_repo_license.mjs and ../verify-repo-skill/scripts/apply_repo_license.mjs: resolve and recursively apply the source repository license for the exact refresh commit before final verification.

Use scripts/check_repo_provenance.py when references/repo-provenance.md exists. It compares the skill snapshot with the current Git checkout and prints JSON with current, stale, or unknown status.

When useful, also read sibling workflow-skill references:

• ../create-repo-skill/references/ for repository evidence discovery, installed-package inspection, and output structure.
• ../verify-repo-skill/references/ for usability case format, verification review, and import/index routing guidance.
• ../extend-repo-skill/references/ for narrow editing and regression review rules.
• ../prepare-repo-skill-env/SKILL.md if live Python inspection is needed and no verified environment is available.

Required Workflow

1. Resolve the existing skill directory, current repository path, existing references/repo-provenance.md baseline, optional user-provided baseline, Python inspection context, review/test artifact directory, and review output path. If the user does not specify an artifact directory, default to <repository-path>/skills/tests/<skill-id>/, with usability cases under test-cases/ and review reports under reports/. If the existing skill is the live managed copy under <agent-dir>/skills/repositories/repo-skills/<skill-id>/, copy only its runtime tree to a temporary working directory outside <agent-dir>/skills/ before editing. Keep that working copy until the dedicated importer succeeds; never edit the live managed copy in place.

2. Read references/change-detection-and-staleness-audit.md. Build a current-state map of the existing skill. When provenance exists, run python scripts/check_repo_provenance.py --skill-dir <skill_dir> --repo-path <repo_path> from this workflow-skill directory or adapt the script path to the installed skill copy. Use its JSON output as the first staleness signal, then gather current repository evidence and optional change evidence from Git history or release notes.

3. Produce a staleness audit that separates:

   • Claims still supported by current repo evidence.
   • Claims that are stale, removed, renamed, or behaviorally changed.
   • New repo capabilities that should be represented because they replace or materially alter existing skill guidance.
   • Unknowns requiring live inspection or user clarification.

4. If live Python inspection is required and no verified environment exists, use prepare-repo-skill-env to create or repair one, then continue only from its verified handoff.

5. Read references/refresh-editing.md. Edit the resolved runtime working copy in place. Preserve root and sub-skill identities unless the user explicitly asks for a rename or the current name is invalid. Add or update references/repo-provenance.md with the refreshed source snapshot. Preserve the canonical repo_id and skill_id by default. Treat the existing area-family assignments as the routing baseline: keep them when the repository's capability scope is unchanged, but do not keep them blindly when the refresh adds, removes, or materially changes a capability. If the capability scope changed, the taxonomy hash changed, or the user requests reclassification, produce a new external area-family routing handoff and matching minimal v2 metadata before import. Do not hand-edit generated router Markdown or silently change assignments in prose.

6. Resolve and apply the repository license after the refreshed source commit is known and before handing the tree to verification:

   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
   node ../verify-repo-skill/scripts/apply_repo_license.mjs \
     --skill-dir <external-runtime-skill-dir> \
     --license <value-from-report>

   Re-query on every refresh; do not preserve a stale license solely because it was present in the previous skill. Update all root/sub-skill frontmatter to the same result. Preserve NOASSERTION when GitHub returns it; normalize only unavailable results to NO_LICENSE, keep the report outside the runtime tree, and carry old value, new value, source commit, status, and reason into the handoff. NO_LICENSE is a warning and not a legal conclusion.

7. Update usability test cases under the review/test artifact directory's test-cases/ subtree so at least one case proves refreshed behavior and at least one case guards a pre-existing workflow that should remain valid.

8. Read references/verification-and-handoff.md. Verify that refreshed public skill content is self-contained, current, privacy-safe, and reachable from nearby SKILL.md files. Save staleness audits, verification reports, and human-review notes under the review/test artifact directory's reports/ subtree.

9. After verification passes, follow verify-repo-skill's structured import policy: use ask_user_question when approval is still required, then run the approved or auto-authorized refresh through verify-repo-skill/scripts/import_repo_skill.mjs with --overwrite, the refreshed runtime skill directory, and --routing-entry <repo-path>/skills/disco/routing_decision/classification.json. The external handoff is mandatory for a normal classified import, even when the existing area-family assignments are retained. Use --overwrite only because this workflow is updating that exact approved repo skill. The helper installs the refreshed runtime tree under ~/.disco/agent/skills/repositories/repo-skills/<skill-id>/, rebuilds the sibling live DisCo repo-skills-router under the global lock, and restores both on failure. Do not hand-edit router Markdown or manually combine copy and updater commands. The refreshed skill is directly available to DisCo Researcher in a new session; use import-repo-skills-to-agent only when the user explicitly asks for a cross-agent export.