agentleFS
vbonkvbonk/repo-template/.claude/skills/template-upgrade/SKILL.md

template-upgrade

Skill8 starsChanged 3 months agoMITView on GitHub

Reconcile an existing repository descended from vbonk/repo-template with a newer template baseline while preserving project-specific work. Use when asked to upgrade, update, sync, reconcile, refresh, or compare a repo-template-based project; when .repo-template.yaml is present; or when legacy template ancestry is suspected and current template improvements should be reviewed. Distinguish pristine legacy instances from lightly customized and mature projects, use semantic three-way reconciliation instead of file synchronization, and preserve project authority.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. Ampli-Group/agentic-mobile-blueprint★ 4same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository9 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 9 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill for downstream template maintenance after repository creation.

    line 8
  2. Very specific:

    Read docs/TEMPLATE-UPGRADE.md before performing an upgrade.

    line 12
  3. Very specific:

    Do not activate merely because a mature project differs from current repo-template.

    line 23
  4. Very specific:

    Read .repo-template.yaml when present.

    line 28
  5. Very specific:

    Keep project-specific CLAUDE.md and AGENTS.md project-specific.

    line 36
  6. Distinctive:

    Verify repository controls that files alone cannot prove, where relevant.

    line 37
  7. Distinctive:

    Run project validation plus reconciliation-specific validation.

    line 38
  8. Very specific:

    Update .repo-template.yaml to the current baseline only after successful reconciliation.

    line 39
  9. Distinctive:

    Do not overwrite project architecture, source, README, CI, agent instructions, or other project-owned material with current template …

    line 52
  10. Distinctive:

    Do not restore removed template files without a demonstrated project need.

    line 53
  11. Distinctive:

    Do not infer stack, licensing, deployment, or environment configuration from the template.

    line 54
  12. Distinctive:

    Do not mark the new baseline as reconciled before validation passes.

    line 55
  13. Distinctive:

    Use normal repository branch, review, and validation controls.

    line 56
  14. Distinctive:

    Before declaring success, answer:

    line 60

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Template Upgrade

Use this skill for downstream template maintenance after repository creation. It is not the normal first-agent bootstrap path for a fresh current template instance; that path is Phase 0.

Source of Truth

Read docs/TEMPLATE-UPGRADE.md before performing an upgrade. If the local copy is absent or clearly older than the marker's canonical reference, retrieve the canonical specification referenced by .repo-template.yaml.

The SOP is model-neutral and authoritative. This skill is a Claude execution helper, not a replacement for the SOP.

Activate When

  • The user asks to upgrade, update, reconcile, refresh, or compare a repo-template-derived repository.
  • .repo-template.yaml exists and template compatibility is being reviewed.
  • A repository appears to descend from vbonk/repo-template but predates the provenance marker.
  • A template security, agent-routing, governance, or repository-integrity improvement may need to be adopted downstream.

Do not activate merely because a mature project differs from current repo-template. Intentional divergence is expected.

Execution Contract

  1. Determine repository identity and confirm this is not the vbonk/repo-template source repository.
  2. Read .repo-template.yaml when present; otherwise assess legacy ancestry from history and inherited template evidence.
  3. Classify project maturity as PRISTINE, LIGHTLY_CUSTOMIZED, PROJECT_MATURE, or AMBIGUOUS.
  4. Build the SOP's three-way model:
    • A: historical template baseline,
    • B: current project,
    • C: current template.
  5. Review A to C changes by downstream value. Prioritize security, agent safety/routing, and repository integrity; treat source-template marketing and maintenance machinery as non-downstream by default.
  6. Reconcile against B semantically. Preserve project-owned behavior and intentional removals. Equivalent or stronger project controls satisfy a template improvement without requiring identical files.
  7. Keep project-specific CLAUDE.md and AGENTS.md project-specific. Ensure they retain a concise Template Ancestry routing rule when .repo-template.yaml remains.
  8. Verify repository controls that files alone cannot prove, where relevant.
  9. Run project validation plus reconciliation-specific validation.
  10. Update .repo-template.yaml to the current baseline only after successful reconciliation.
  11. Report adopted, adapted, equivalent, skipped, and unresolved changes separately.

Legacy Repositories

Absence of .repo-template.yaml does not mean the repository is unrelated to the template. Use multiple independent ancestry signals and label confidence CONFIRMED, LIKELY, or UNKNOWN.

For a confirmed pristine legacy instance, refreshing the inherited substrate and then using Phase 0 is appropriate.

For an established legacy project, never reset it to the current template. Reconcile selectively and add provenance only after the upgrade succeeds.

Safety Boundaries

  • Do not overwrite project architecture, source, README, CI, agent instructions, or other project-owned material with current template versions merely because paths match.
  • Do not restore removed template files without a demonstrated project need.
  • Do not infer stack, licensing, deployment, or environment configuration from the template.
  • Do not mark the new baseline as reconciled before validation passes.
  • Use normal repository branch, review, and validation controls.

Completion Check

Before declaring success, answer:

  • What was the previous baseline or ancestry evidence?
  • What maturity class is this project?
  • Which current template improvements were reviewed?
  • Which were adopted, adapted, already satisfied, skipped, or unresolved?
  • What project validation passed?
  • Were repository-level settings checked where relevant?
  • Does the project retain future upgrade routing?
  • Does .repo-template.yaml now truthfully represent completed reconciliation?

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.