Skip to content
Skills Library
AI & agents · Building & coding

implementing-skill-changes

/implementing-skill-changes

Implements the fix for a skill change whose failing test already exists, runs the repository's gates, sweeps the layers the change contradicts, and pushes the branch, updating the pull request when one exists. Follow the workflow in the body; the description does not summarize it. TRIGGER when: a .skill-change-<key>.md handoff file and a failing test both exist and you are ready to make the test pass; you are at the final step of the skill-change pipeline. DO NOT TRIGGER when: no failing test exists yet, use test-driving-skill-changes; no analysis or design brief exists, use analyzing-skill-bu

Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Implements the fix for a skill change whose failing test already exists, runs the repository's gates, sweeps the layers the change contradicts, and pushes the branch, updating the pull request when one exists. Follow the workflow in the body; the description does not summarize it. TRIGGER when: a .skill-change-<key>.md handoff file and a failing test both exist and you are ready to make the test pass; you are at the final step of the skill-change pipeline. DO NOT TRIGGER when: no failing test exists yet, use test-driving-skill-changes; no analysis or design brief exists, use analyzing-skill-bu

Arguments

/implementing-skill-changes <key>
Original author description

Implements the fix for a skill change whose failing test already exists, runs the repository's gates, sweeps the layers the change contradicts, and pushes the branch, updating the pull request when one exists. Follow the workflow in the body; the description does not summarize it. TRIGGER when: a .skill-change-<key>.md handoff file and a failing test both exist and you are ready to make the test pass; you are at the final step of the skill-change pipeline. DO NOT TRIGGER when: no failing test exists yet, use test-driving-skill-changes; no analysis or design brief exists, use analyzing-skill-bu

How it works

  1. User Input
  2. Your role
  3. Tool usage
  4. Input and setup
  5. Implement
  6. Registration
  7. Verify
  8. Sweep
  9. Changelog
  10. Scope check
Original SKILL.md headings · 260 lines, 1,885 words
SKILL.md preview
---
name: implementing-skill-changes
description: >-
  Implements the fix for a skill change whose failing test already exists, runs
  the repository's gates, sweeps the layers the change contradicts, and pushes
  the branch, updating the pull request when one exists.
  Follow the workflow in the body; the description does not summarize it. TRIGGER when: a .skill-change-<key>.md handoff file and
  a failing test both exist and you are ready to make the test pass; you are at
  the final step of the skill-change pipeline. DO NOT TRIGGER when: no failing
  test exists yet, use test-driving-skill-changes; no analysis or design brief
  exists, use analyzing-skill-bugs or grilling-skill-features; you are changing
  Infrahub the product rather than this repository's guidance.
argument-hint: <key>
compatibility: >-
  Requires this repository checked out on the pipeline branch. `gh` and a GitHub
  remote are needed only for the PR path. `skillgrade` is needed for the
  targeted eval run and the discrimination proof on guidance-class changes.
  Node.js with `npm`, and network access for `npm ci`, are needed to build the
  docs when the change adds a new skill.
user-invocable: true
metadata:
  internal: true
  pipeline: "skill-change (stage 3 of 3: analyze or grill, then test-drive, then implement)"
  version: 0.1.0
  author: OpsMill
---

# Skill change implementer

## User Input

```text
$ARGUMENTS
```

## Your role

Make the failing test pass by fixing what the analysis or design brief says is
wrong, not by editing the test until it stops complaining. The test is the
validation criterion the prior stage proved fails; the handoff's root cause or
design brief is what drives the fix. Those are not the same thing, and
collapsing them, by weakening a grader check or patching whatever the test
happens to touch, is the failure this stage exists to prevent.

## Tool usage

- Use the `Read` tool to read files and the `Glob` tool to find them, rather
  than `cat`, `find`, or `ls -R`.
- Use the `Grep` tool when you are searching the tree yourself. That covers
  exploration, not the commands this pipeline prints: where this skill or a
  file it links gives a literal `grep`, `head`, or `tail`, run it as given.
  The sweep and the ground-truth reads are those commands.
- Reserve Bash for git, `gh`, the snippets this skill gives you, and anything
  else that needs a shell.
- Shell state does not persist across separate Bash calls. Variables and `cd`
  are gone by the next call, so re-derive or restate anything a later snippet
  needs.

## Input and setup

Parse `$ARGUMENTS` for `<key>`, then read `.skill-change-<key>.md` and take
`BRANCH` from its `Branch` field. Re-deriving the branch name here drifts from
the name the entrance stage recorded, which is why the handoff carries it.

```bash
BRANCH="<the Branch field from .skill-change-<key>.md>"
gh pr list --head "$BRANCH" --json number,body,headRefName --jq '.[0]'
```

Two guards, both hard stops, checked in this order before anything else runs:

- The body does not contain `AGENT_EVAL_COMPLETE`: the failing-test stage
  never ran. Tell the user to run `test-driving-skill-changes` first, and
  stop.
- The body already contains `AGENT_IMPL_COMPLETE`: this stage already ran
  against this change. Say so, and stop.

No PR found for `$BRANCH`: proceed in local mode instead of failing closed.
Skip the two body guards, since there is no PR body to read; verify instead
that the failing test the prior stage wrote still exists, and run it before
touching anything else. Say plainly that no PR was found.

If that test already passes, stop: say the fix appears to have already been
applied on this branch, and do not proceed. A PR carries `AGENT_IMPL_COMPLETE`
as its idempotency guard against a second run; local mode has no PR body to
check, so a test that is already green is the only equivalent signal
available, and it means the same thing.

Back to the handoff file. Missing file: stop and say so, since this stage has
nothing to implement without it. Pull `Minimum change rung`, `Rule path`,
`Eval task`, `Sweep terms`, `Do NOT`, and `Defect class`; the rest of this
skill acts on exactly those fields. Also read the failing test the prior stage
committed.

## Implement

State the reasoning before editing anything: name the file, the change, and
why it addresses the diagnosis rather than the symptom the test happens to
touch.

Respect the recorded `Minimum change rung`. Rung 3 or lower: refuse to add a
new rule file, and say which rung blocked it. A stage that quietly upgrades
the change defeats the ladder the earlier stages already climbed.

Then branch on `Defect class`:

- `guidance`: write or edit the rule at the handoff's `Rule path`,
  `skills/<skill>/rules/<category>-<concern>.md`. Link it from `SKILL.md` at
  the workflow step that needs it, saying when to read it, because a rule
  reachable only from `_sections.md` gets read after the mistake, which is the
  same as not writing it down. A new category prefix also touches
  `_sections.md`, the `Rule Categories` table, and any ladder or severity
  legend the skill keeps.
- `grader`: fix the check function in `graders/<skill>/lib.py`, or the eval
  task, so it asserts what the handoff's `Test plan` describes.
- `script`: fix the bundled script, or write the `scripts/check-*.py` the test
  demands.

The handoff's `Do NOT` list names artifacts the minimum-change rung already
ruled out. Treat it as binding, not as a suggestion to reconsider.

## Registration

Only when the change adds a new skill: wire every surface listed in
[`../../../dev/guidelines/skill-registration.md`](../../../dev/guidelines/skill-registration.md),
and write the skills-reference page in the shape that file gives. Link the
table rather than restating it here; a second copy is the exact drift the
guideline warns about. It comes before Verify so that `uv run invoke lint`
and the docs build there run against the wired surfaces: lint fails a skill
missing from any surface it checks, and the scenarios and pair tables are
yours to judge. In your report, name each surface you added to and what
you added: the check's output only names the surfaces a skill is missing
from.

## Verify

Run every gate, each with its command:

```bash
skillgrade --eval=<task> --trials=1     # guidance class only, must score 1.0
uv run invoke test
uv run invoke lint
if ! uv run python scripts/sync-evals.py; then
  echo "GATE FAILED: sync-evals.py exited non-zero; the diff below means nothing"
elif git diff --quiet -- evaluations/; then
  echo "evals in sync"
else
  echo "STALE: evaluations/ regenerated, commit the result"
  git diff --stat -- evaluations/
fi
```

When the change adds a new skill, also build the docs. It runs with
`onBrokenLinks: 'throw'`, and `uv run invoke lint` does not run it:

```bash
(cd docs && npm ci && npm run build)
```

Then, guidance class only, prove the task measures the skill rather than the
model. The green run above scored 1.0 with the skill read. Delete the task's
`Read the skill at ...` line and run the same task again. Delete, not comment:
`instruction:` is a block scalar, so a `#` leaves the pointer in the prompt.

```bash
skillgrade --eval=<task> --trials=1     # skill unread, expect below 1.0
# then restore the line
```

First check the output for a grader read, which voids the trial at any score
(see `dev/guides/running-evals.md` § "Prove the task discriminates"). On a
trial that counts, below 1.0 and the proof lands. A 1.0 does not mean the task
is broken: the line is a pointer and the sandbox still ships the skill, so read
the three readings in `dev/guides/running-evals.md` and report which one this
is rather than hardening a prompt that was never the problem. This proof only carries
signal now that the rule exists, which is why
`test-driving-skill-changes` leaves it to this stage: with the rule absent the
task scores below 1.0 either way.

Escalate to `--trials=3` only when a single run is ambiguous, and say why in
the report. Never report an interrupted or timed-out `skillgrade` run as a
pass; an interruption is not evidence of anything.

## Sweep

For every term in the handoff's `Sweep terms`:

```bash
grep -rn "<sweep term>" skills/ graders/ eval.yaml dev/ README.md AGENTS.md docs/ .agents/skills/
```

Skip `evaluations/`, which `sync-evals.py` regenerates from `eval.yaml`. Fix
every hit, and delete what the change makes wrong. An impact or severity label
bumped in a rule has to move in the skill's index too, or the index now
disagrees with the rule it indexes.

Then update every surface the handoff's `Docs impact` field names. Those pages
describe behavior this change just altered, so leaving them is worse than
having written nothing: a reader trusts a stale page and search finds it.
[`../../../dev/guidelines/skill-registration.md`](../../../dev/guidelines/skill-registration.md)
§ "When behavior changes" lists what goes stale and when. A `Docs impact` of
`none` needs no edit, and the report says so rather than passing over it in
silence.

## Changelog

```bash
uv run towncrier create -c "<one sentence describing the change>" <issue>.housekeeping.md
# With no issue number, use a descriptive slug prefixed with +:
uv run towncrier create -c "<one sentence>" +<slug>.housekeeping.md
```

Apply the matching `changes/*` label to the PR; it drives the version bump.
Never edit `CHANGELOG.md` by hand and never run `towncrier build`. This
repository assembles its changelog from fragments, and skill or tooling work
goes under `housekeeping`.

## Scope check

Read `git diff` against the base branch. Nothing unrelated widened, and no
file changed that the handoff did not name. A fix that grew past the
handoff's `Target` needs a fresh diagnosis, not a bigger commit.

## Close out

Close out only once Verify, Sweep, and Scope check have all passed.

In local mode there is no PR body to update, so push the branch, report its
name, and say plainly that the change still needs a pull request opened. Do
not run `gh pr edit`: `PR_NUMBER` is empty by construction on this path, and
this skill never opens the PR itself.

With a PR, push, then update the PR body by appending `AGENT_IMPL_COMPLETE`:

```bash
BRANCH="<the Branch field from .skill-change-<key>.md>"
PR_NUMBER=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number')
git push -u origin "$BRANCH"
gh pr view "$PR_NUMBER" --json body --jq .body > /tmp/pr-body-"$PR_NUMBER".md
printf '\n\nAGENT_IMPL_COMPLETE\n' >> /tmp/pr-body-"$PR_NUMBER".md
gh pr edit "$PR_NUMBER" --body-file /tmp/pr-body-"$PR_NUMBER".md
```

`--body` replaces the whole body, so the marker has to be appended to the
body that is already there. Reading it back first is what keeps the stage's
own `AGENT_EVAL_COMPLETE` gate — and the description — from being
overwritten.

Report what ran and what it printed for every gate in Verify. Then offer a
full `skillgrade --smoke` run as an opt-in the user can decline; never run it
automatically.

## Escalation

Stop and report rather than guessing forward, when:

- the handoff file is missing or missing a required field
- the PR body is missing `AGENT_EVAL_COMPLETE`
- the PR body already contains `AGENT_IMPL_COMPLETE`
- local mode, and the failing test already passes before any fix is applied
- the fix the diagnosis calls for needs an artifact the recorded rung forbids
- the targeted eval will not reach 1.0 after reasonable rewording
- the discrimination run scores 1.0 with the skill unread and none of the
  readings in `dev/guides/running-evals.md` accounts for it
- three discrimination trials in a row, counted across runs, show a grader
  read, the re-run limit in
  `dev/guides/running-evals.md` § "Prove the task discriminates"
- a gate fails for a reason outside the handoff's scope

## Common mistakes

| Mistake | Why it breaks the pipeline |
| --- | --- |
| Weakening the grader instead of fixing the cause | The test passes, but the defect the handoff diagnosed is still there |
| Adding a rule file when the rung said edit an existing one | Splits one concern across two files and pays a second grader and eval forever |
| Linking the rule only from `_sections.md` | The rule is read after the mistake, which is the same as not writing it down |
| Skipping the discrimination proof | An unread run scoring 1.0 is unexplained until one of the readings in `dev/guides/running-evals.md` accounts for it |
| Skipping the sweep | An old claim the change makes wrong survives next to the new one |
| Committing `eval.yaml` without the regenerated JSON | `evaluations/*.json` silently diverges from the source it was built from |
| Editing `CHANGELOG.md` by hand | Bypasses the fragment system that assembles the release notes |
| Claiming a timed-out eval run passed | An interruption is not a score; the next reader trusts a result that never happened |

## Boundaries

Follow the repository-wide boundaries in [`../../../AGENTS.md`](../../../AGENTS.md) § Boundaries.

Versions

The database has no other skills named implementing-skill-changes.

Database snapshot: 13.11.2026 · package version 15b08c523fce (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100test-driving-skill-changes
    Writes the failing test for an analysed or grilled skill change, and proves it fails, before any fix is written. Chooses the test surface from the defect class: an eval.yaml task plus a grader check for guidance, a pytest for grader and script defects. Follow the workflow in the…
  • 100opsmill-dev-fixing-bugs
    Implements and validates the fix for a bug once a failing reproduction test exists. TRIGGER when: a bug has a failing reproduction test and you are ready to make it pass, implementing the root-cause fix, the final step of the bug-fixing pipeline. DO NOT TRIGGER when: no…
  • 100analyzing-skill-bugs
    Performs root-cause analysis of a defect in this repository's own skills, graders, or scripts, before any test or fix is written, and verifies every claim about Infrahub behavior against real source. Follow the workflow in the body; the description does not summarize it. TRIGGER…
  • 100opsmill-dev-test-driving-bugs
    Writes a single failing test that reproduces a bug after its root-cause analysis is complete, before any fix is written. TRIGGER when: a bug has a completed root-cause analysis and you need the failing reproduction test, writing a test that proves a bug exists, the second step…
  • 98analyze-skill-issues
    Query the integration-test storage account to find why a specific skill's tests are failing. Reads blob-stored test result files and surfaces error details. TRIGGERS: why is skill failing, skill test failures, debug skill tests, skill failing tests, analyze skill failures, why…
  • 100add-skill
    Use in the agent-skills repo when the user asks to add a new shared skill, change or split one in skills/, move a section to a reference file, or fix a failing check. Writes the skill to the rules in AGENTS.md, runs the skill and prose checks and the temp home install, and…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.