agentleFS
christofferbergjchristofferbergj/agent-skills/skills/agents/maintain-skills/SKILL.md

maintain-skills

Skill1 starsChanged 25 days agoMITView on GitHub

Adopt upstream changes into this skill library while keeping its local adaptations, and audit its skills.

6 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 2 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run in one of two modes:

    line 11
  2. Distinctive:

    Audit: do the upstream work, then work through carried items, the fidelity backlog, pending skills, and stale reviews, checking each skill …

    line 14
  3. Very specific:

    Read the repository's AGENTS.md, the adaptation contract, and the maintenance guide.

    line 22
  4. Very specific:

    Run fetch, then compare --fetch with --resume.

    line 30
  5. Very specific:

    When items 1 to 4 are empty in upstream mode, save a checkpoint from the compare reports, prune old runs, run release, and stop.

    line 38
  6. Very specific:

    Run the contract's fidelity check on every sourced skill you edit or find in changedSince, and in audit mode on backlog records.

    line 48

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “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

Maintain skills

Keep this library's sourced skills current with their upstreams while keeping the light local adaptations that fit them to this setup. The adaptation contract defines that setup and how to decide each upstream change. The maintenance guide gives the helper commands, runtime state, checks, and branch rules the steps use.

Run in one of two modes:

  • Upstream: adopt upstream changes since each skill's reviewed position, import new upstream skills, and review skills whose files changed since the last run.
  • Audit: do the upstream work, then work through carried items, the fidelity backlog, pending skills, and stale reviews, checking each skill against current tools, documentation, and repository conventions.

The user or the scheduled task can name the mode; otherwise begin picks it. Only an explicitly named subset of skills narrows either mode.

Use /swarm throughout. Give each worker one slice, such as a source group, a batch of skills, or a repair, with the exact local revision, the immutable candidate, the adaptation contract, its evidence requirements, and the files it may write. Workers do their slice directly without starting another coordinator. The coordinator fetches sources, owns the checkpoint, canonical documents, and integration, and collects every worker's result; a failed or missing result stays pending. Without delegation, work sequentially and note the lost independence in the run's report.

1. Begin

Read the repository's AGENTS.md, the adaptation contract, and the maintenance guide. Run begin. When it reports the lock held, stop and name the run that holds it. Otherwise this run owns the lock until it runs release.

Note begin's leftovers, the edits of a run that ended before delivery, for the report, then sync both worktrees by the guide's branch rules, which discards them. That work returns on its own: a run settles its checkpoint and carried items only after delivery, so the interrupted run's items are still open in the state begin found. When begin reports legacyNextActions, convert that file into next-actions.json. Read the owner comments posted since commentsSince on the open maintenance PRs and on the PRs the questions link to. Check installed copies with scripts/check-installs.py, and refresh them as AGENTS.md says when they are stale. Run inventory --resume with begin's checkpoint from the library worktree.

Complete when: this run holds the lock, both worktrees match their sync rule, and you hold begin's mode, checkpoint, questions, carried items, and leftovers, every owner comment since commentsSince, a current install check, and the inventory with its changedSince, contextChanged, and staleReviews lists, or the run has stopped on a held lock and named the run that holds it.

2. Find what changed

Run fetch, then compare --fetch with --resume. Save the inventory, fetch result, and compare reports in the run folder. Build the worklist in this order, which is also the order of work:

  1. Owner answers and comments not yet applied, and maintenance branches pushed without a PR.
  2. Changed upstream skills and shared inputs, and every source whose fetch failed.
  3. New, removed, or moved upstream skills in the catalog's suites.
  4. Skills in changedSince, including new skills, and the inputs in contextChanged.
  5. In audit mode only: carried items, overdue ones first; the inventory's fidelityBacklog; skills the checkpoint lists as pending; then the oldest staleReviews, up to a quarter of the library.

When items 1 to 4 are empty in upstream mode, save a checkpoint from the compare reports, prune old runs, run release, and stop. A quiet run needs no branch, checks, review, PR, or report.

Complete when: every unapplied owner answer, branch pushed without a PR, compare report entry, failed source, changedSince skill, and contextChanged input, and in audit mode every carried item, fidelityBacklog record, pending skill, and the oldest staleReviews up to a quarter of the library, is on the worklist or recorded as unchanged, or the run has stopped as a quiet run.

3. Decide and repair

Edit on the maintenance branches by the guide's branch rules. Decide each upstream change by the adaptation contract, and record each decision as it describes. Dispatch repairs to isolated writers using /writing-for-agents, and inspect each returned diff. Import new upstream skills and propose retirements as the contract describes. When a change touches a shared owner, check its consumers in both suites.

For each skill in changedSince, check that its edits keep its recorded adaptations and repository conventions. For each input in contextChanged, read its diff since the checkpoint's libraryRevision and name every skill whose review it affects. In audit mode, check tool names, commands, links, and practices against the environments each skill supports, starting from exposed tool schemas, installed versions, and local help output. Review first-party skills and local adaptation text with /writing-for-agents, and treat sourced text by the contract's minimal-divergence rule.

Run the contract's fidelity check on every sourced skill you edit or find in changedSince, and in audit mode on backlog records.

Before editing for a repair that no checkpoint tracks, such as one this run found in a skill's or this skill's own text, add it to next-actions.json with today's date, so an interrupted run leaves it open. Settle each item that waits on the owner as a question, as the contract's decision records describe. Carry an item only when the budget ran out or it waits on a later upstream revision: keep or add its next-actions.json entry with the date it was first carried. An overdue carried item has already survived an audit; finish it in this audit or ask it as a question.

Complete when: every worklist item is adopted, adapted, excluded, asked as a question, or carried in next-actions.json with its reason; every overdue carried item is finished or asked; every contextChanged input has its affected skills named; and every edited or locally changed sourced skill passes both fidelity directions.

4. Validate

Read changed instructions end to end and run the maintenance guide's checks. Exercise changed scripts or workflows on a small isolated example, and confirm each new regression test fails with its repair reverted. Dispatch an independent final review of the exact diff, its decisions, fidelity, and coverage, and resolve its findings. Re-enumerate skills so additions made during the run enter coverage.

Advance a skill's reviewed-through position only when its whole upstream delta is decided and checks pass.

Complete when: checks pass; every new regression test fails with its repair reverted; every final-review finding is fixed, asked, or carried; and every moved reviewed-through position has its whole delta decided.

5. Deliver

Commit library changes and changes to this skill's own process on their separate maintenance branches, push each by the guide's push rule, and create or update one draft PR for each, within the action grant: the scheduled prompt's grant for a scheduled run, and the user's request for an invoked one. Once each PR is verified, settle runtime state: remove the carried items its commits finish or its description asks, and the questions whose answers its commits record, then save the checkpoint with this run's finished local reviews, adding --context-reviewed with the affected skills after step 3 reviewed a context change; a checkpoint never advances a position. Prune old runs, then run release.

Report what changed, the questions waiting on the owner, failures such as failed sources and discarded leftovers, and coverage still pending.

At the budget's wrap-up point, start no new worklist items: validate, deliver, and checkpoint what is finished, carrying the rest.

Complete when: each PR is a draft whose head on the forge equals the pushed commit and whose description lists its open questions and names each /usage-review contract the guide requires; runtime state is settled and the checkpoint saved after that verification; the report is written; every action stayed within the grant; and the lock is released.

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.