skillset-fix
Diagnose and clear generated-output trouble in a Skillset repository — drift reported by check, a missing or hand-edited generated file, a conflicted path under a managed output root, or a halted rebase or merge. Routes to skillset resolve, skillset build --repair, and skillset check --only outputs. Use when a generated file or a skillset.lock differs from source, is missing, or is conflicted. Do not use for conflicts in authored source.
- License 许可
- MIT
- 最近更新
- 2026-11-01
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- skillset-fix
- metadata
- { "version": "0.4.0", "skillset.schema": "1" }
- description
- Diagnose and clear generated-output trouble in a Skillset repository — drift reported by check, a missing or hand-edited generated file, a conflicted path under a managed output root, or a halted rebase or merge. Routes to skillset resolve, skillset build --repair, and skillset check --only outputs. Use when a generated file or a skillset.lock differs from source, is missing, or is conflicted. Do not use for conflicts in authored source.
03 SKILL.md 正文
Fix Skillset Generated Output
Skillset commits its generated output. Those files are derived and
non-authoritative: their final content must come from authored source, never from
manual reconciliation. A conflict carries no valid merged content. A diff can
still preserve evidence of a misdirected human edit, so keep it until Skillset
reports an output-edited or diverged verdict and the intent is recovered.
Never leave an edit in a generated file, and never hand-merge one.
Run the repository's own compiler
First check whether the repository builds Skillset itself by looking for
apps/skillset/package.json with package name skillset.
- In a Skillset compiler checkout, compare
skillset --versionwith the version inapps/skillset/package.json, then invoke the compiler through the repository:bun ./apps/skillset/src/cli.ts <command>, or thebun run skillset:*scripts. - In a consumer repository, use the installed binary. MUST NOT compare it with the
root
package.json; that version belongs to the consuming application.
When the compiler-checkout versions differ, a globally installed skillset is
shadowing the one under test, and its answers describe a different compiler.
This is not hypothetical. A stale 0.26.1 binary reporting build is blocked on a
repository whose own compiler restores the file correctly is what produced the
false premise behind SET-599.
Decide whether the path is generated
Do this first. It determines everything that follows.
- Run
skillset explain <path> --root .. It reports ownership and provenance, and labels a derived path(generated). - When
explainis unavailable, treat a path as generated if it appears as anoutputPathor infiles[]of askillset.lock, or is askillset.lock. - When the path is authored source, this skill does not apply. Resolve it as ordinary source.
Read the verdict
skillset build --repair reports repair verdicts and actions. A dry-run
skillset resolve instead prints the conflict partition (generated, authored,
or hand-edited); after --yes reaches the repair preview, it prints any
non-clean repair verdicts before its summary. Read the command's exact report
rather than re-deriving it.
| Verdict | What it means | What happens |
|---|---|---|
clean |
The file already equals what source produces. | Nothing. |
output-missing |
A managed file is absent. | Restored. No edit can be lost. |
source-ahead |
Source moved; the output is stale. | Regenerated. |
output-obsolete |
The lock claims it but source no longer produces it. | Removed. |
output-edited |
The generated file was edited; source was not. | Preserved, not overwritten. See ## Recover a misdirected edit. |
lock-untrusted |
The lock records no verdict this repair can rely on. | Preserved. The fault is the lock, not the output. See ## Rebuild an untrusted lock. |
diverged |
The generated file and its source both moved. | Refused. See ## Escalate. |
The verdicts come from a three-way comparison against the outputHash the lock
recorded for the last build — the file on disk, the lock, and what a fresh render
would produce.
MUST NOT use file modification times to decide any of this. A rebase or a checkout rewrites mtimes across the whole tree, so in the situation where drift matters most, every file appears equally fresh.
outputHash is recorded per lock item, which is a group of files, so a single
edited file marks its whole group. A path whose bytes already equal the render is
reported clean regardless, because writing it would change nothing.
Clear a conflict during a rebase or merge
- Run
skillset resolve --root .to see the partition without writing anything. - When it names authored conflicts, it stages nothing and exits non-zero.
Resolve those files,
git addthem, then return to step 1. Regenerating from source that still carries conflict markers would render those markers into generated output. - When it reports paths edited by hand on one side of the conflict, it
stages nothing and exits non-zero. Follow
## Recover a misdirected editfor each named path, rungit add <source-path>for the recovered source change, then return to step 1. MUST NOT commit while generated paths are still unmerged; continuation creates the rebased or merged commit after generated output is repaired. - Run
skillset resolve --root . --yes. It repairs the generated paths and stages them. - When it exits zero, continue the operation with the command that owns it:
gh stack rebase --continuein a stack,git rebase --continuefor a rebase, orgit merge --continuefor a merge. - When it reports a
divergedpath, follow## Escalate.
A conflicted file on disk represents neither side, so the verdict table has no
baseline there. skillset resolve instead checks each conflict side against the
lock that side committed, and refuses when either disagrees. MUST NOT resolve
such a path by taking a side. The pre-rebase commit still holds the edit; recover
it from there.
skillset resolve reads lock ownership from exact index blobs: stage 0 for an
unconflicted lock and stages 2 and 3 for the two conflict sides. It never trusts
mutable worktree lock bytes as provenance, so a lock carrying markers does not
need fixing by hand first. It stages only paths it classified as generated, and
MUST NOT be used to stage authored source.
With --yes, resolve refuses worktree-only compiler inputs that could change the
projection: source, workspace config and manifest files, external repository
package sources, and explicit feature inputs. Staged inputs and unrelated dirt
outside that input inventory do not block it.
The repair is transactional across the whole projection, not only the paths that happened to conflict. Before writing, resolve records each affected path's exact bytes, executable mode, absence, missing parent directories, or symlink target. If validation, build, or staging fails, it restores those preimages rather than leaving a partially repaired worktree.
Repair drift outside a conflict
Use this when skillset check reports drift and no rebase or merge is in progress.
- Run
skillset build --repair --root .. It classifies every managed path against filesystem reality and prints a verdict for each that needs action. - When every verdict is
clean,output-missing,source-ahead, oroutput-obsolete, runskillset build --repair --root . --yes. It restores, regenerates, and removes. - When any verdict is
output-edited, it writes nothing. Follow## Recover a misdirected editfor each named path, then return to step 1. - When any verdict is
lock-untrusted, it writes nothing. Follow## Rebuild an untrusted lock, then return to step 1. - When any verdict is
diverged, it writes nothing. Follow## Escalate. - Run
skillset check --only outputs --root .. Continue only when it passes.
--repair restores a deleted managed file byte-identically and leaves the lock
untouched when nothing else changed.
skillset build --repair --discard-edits overwrites a hand-edited output instead
of preserving it. Use it only after the edit has been carried into source, or when
the edit is confirmed unwanted. It cannot override a diverged verdict.
Rebuild an untrusted lock
A lock-untrusted verdict means the lock's own integrity check failed (its
header hash or an entry's hash no longer verifies), so the
repair cannot tell a stale output from a hand-edited one. The generated file is
not necessarily wrong, and there is probably no misdirected edit to recover.
MUST NOT treat this as output-edited. MUST NOT go looking for an edit to port
into source.
- Confirm the generated files themselves are what you expect:
git statusandgit diffover the named paths. - Rebuild so the lock is regenerated with valid provenance:
skillset build --root . --yes. - Rerun
skillset build --repair --root .. The verdicts should now be real. - When the lock was tampered with deliberately, or step 2 does not clear it, stop and report that. A lock that will not rebuild is a compiler problem, not a content problem.
Recover a misdirected edit
Do this for every output-edited path. When the generated file changed and its
source did not, the edit was almost certainly aimed at the wrong file. The intent
is usually right and the target is wrong.
MUST NOT discard the edit. MUST NOT leave the edit in the generated file.
- Capture the edit:
git diff -- <generated-path>, or read the backup Skillset wrote under.skillset/snapshots/before any overwrite. - Find the authoring source:
skillset explain <generated-path> --root .. - Apply the equivalent change to that source file.
- Regenerate:
skillset build --root . --yes. - Confirm the generated file now contains the intended change, and that
skillset check --only outputs --root .passes. - When the change cannot be expressed in source, stop and report that. It means either the source format lacks the capability or the change does not belong in generated output.
Which row is it?
source-ahead. A skill's source gained a new section. The generatedSKILL.mdno longer matches what the compiler would emit, and nobody touched the generated file. Regenerate.
output-edited. Someone fixed a typo directly in.agents/skills/<name>/SKILL.md. The source still says what it always said. Port the typo fix to source, then regenerate.
lock-untrusted. Nobody touched the generated file at all; a merge or an edit damagedskillset.lock, so its recorded hashes no longer verify. There is no edit to port. Rebuild the lock.
Both look identical in git status — one modified generated file. Only the lock
comparison separates them, which is why the verdict is worth reading rather than
guessing.
Escalate
Stop and hand back when either holds:
- A path's verdict is
diverged: the generated file was edited and its source changed. - A change cannot be expressed in authored source.
Report the exact paths and which condition applies. MUST NOT guess which side to keep, and MUST NOT resolve the path by picking one.
Verify before finishing
- Run
skillset check --only outputs --root .. It MUST pass. - Confirm no generated file contains a conflict marker. Generated output merges
as ordinary text, so a true conflict writes markers into it;
skillset resolve --yesregenerates those paths from the index stages, and a marker left behind means a conflicted path was staged without being resolved. - Confirm no authored source was staged by a resolve step that should only have touched generated output.
04 同仓库更多 Skills
use-skillset
Use the skillset compiler in a repo with skillset.yaml or a .skillset/ directory. Covers creating a workspace, adding skills, rules, agents, hooks, and plugins, building and checking Claude, Codex, and Cursor output, repairing stale or hand-edited generated files, recording changes, cutting releases, importing existing skills, and marketplaces. Use when asked to add a rule, record a change, cut a release, or fix generated output.
broken
42
reference
Keep project references organized for review.
portable-proof
Proves that generated Agent Skills are accepted by pinned external consumers.
plugin-proof
Proves immediate-child skill fidelity inside an Agent Plugins package.
sink
Kitchen-sink skill exercising shared resources and custom resource mappings.