Contract
- Input: skill invocation with the user's request and available context.
- Output: a structured artifact or guidance aligned to the skill's declared outputs.
- Scope: stay within the skill's declared boundaries; do not broaden without explicit direction.
- Rule: follow the skill's completion criteria and stop condition exactly.
Provenance
| Question |
Answer |
| What is the source of truth? |
The user's request, originating spec/issue, and the skill's declared outputs |
| What is in scope? |
Work covered by the skill's acceptance criteria and completion rules |
| What is explicitly out of scope? |
Files, behaviors, and decisions outside the skill's declared boundary |
| Who or what consumes this artifact afterward? |
The next skill in the workflow or the user |
| What evidence proves it is done? |
Completion criteria met, artifact saved, validation passed |
| What risk remains? |
Subjective judgment calls, missing context, or external dependency failures |
Artifact
Emit LockfileMaintenanceArtifact as both:
- JSON:
.agents/skills/platform/artifacts/lockfile-maintenance/{identifier}.json
- Markdown view: same filename with
.md extension
Rules
- Rule: enumerate canonical
SKILL.md files from .agents/skills before changing lock data.
- Rule: distinguish content hash drift from path drift, missing entries, and deleted skill entries.
- Rule: update hashes from the exact bytes currently in each
SKILL.md; do not hash rendered excerpts or generated summaries.
- Rule: remove lock entries only when the corresponding skill path is intentionally absent and no symlink still points to it.
- Rule: preserve existing lockfile schema, indentation, and stable ordering unless the repository's maintenance script defines a different order.
- Rule: prefer
scripts/update-lockfile.mjs for canonical bundle lock refreshes; inspect its dry-run output before committing changes.
- Rule: run the repository validator after lock updates and report the command, exit status, and any warning.
- Rule: if a lock update follows skill edits, include both the edited skill names and the resulting lock entries in the summary.
Workflow
- Read the lockfile and list canonical skill files.
- Compare lock entries to the filesystem by skill name, path, and hash.
- Classify drift as missing entry, stale hash, extra entry, moved skill, duplicate name, or malformed metadata.
- Apply the smallest lockfile change that reconciles the intended tree.
- Validate the full skill bundle using the repository's available validation commands.
- Summarize every lockfile mutation and cite remaining drift, if any.
Script
Use scripts/update-lockfile.mjs from this skill directory to reconcile the canonical skill tree with skills-lock.json.
node .agents/skills/skill-dev/lockfile-maintenance/scripts/update-lockfile.mjs --dry-run
node .agents/skills/skill-dev/lockfile-maintenance/scripts/update-lockfile.mjs --write
The dry run reports added, updated, and removed lock entries without changing files. The write mode preserves the lockfile schema, sorts skill names, and writes hashes from the exact current SKILL.md bytes.
Completion
- the skill's completion criteria are explicitly checked
- the artifact is saved and validated
- any blockers or skipped validations are documented
- the next consumer is identified or the work is handed off
- no approval is required for lockfile writes: the script only updates skills-lock.json hashes for resolved SKILL.md files, reversible via git
@include .agents/skills/platform/contract-base.xml
1---2name: "lockfile-maintenance"3category: "skill-dev"4maturity: "stable"5version: "1"6description: "Maintain the skills lockfile by detecting missing, stale, extra, or mismatched skill entries and updating hashes only after the corresponding SKILL.md files are resolved."7license: "MIT"8capabilities:9 - apply lockfile maintenance methods within explicit skill-dev boundaries10 - analyze maintain the skills lockfile by detecting missing, stale, extra, or mismatched skill entries and updating hashes only after the corresponding skill.md files are resolved with assumptions, constraints, and failure modes11 - produce and validate a skill-dev artifact with evidence, decisions, and next steps12outputs: "skill-dev artifact containing the scoped result, supporting evidence, validation status, and residual risks required by this skill's contract."13sideEffects:14 - write-files15dependencies: ""16stopCondition: "Lockfile entries match the current skill tree or every drift item has a stated blocker and recommended repair."17risk: "low"18trustTier: "2"19maxIterations: "5"20promptVersion: "2.0"21artifactType: "skill-dev"22modelTier: "fast"23evaluators: ["behavioral", "regression"]24fixturesPath: ""25diataxis: "how-to"26tags: ["skill-dev"]27compatibility: []28approvalRequired: "false"29approvalFor: []30metadata:31 source: https://skillmd.com/skills/quantumquirkxyz/lockfile-maintenance32---3334## Contract3536- Input: skill invocation with the user's request and available context.37- Output: a structured artifact or guidance aligned to the skill's declared outputs.38- Scope: stay within the skill's declared boundaries; do not broaden without explicit direction.39- Rule: follow the skill's completion criteria and stop condition exactly.4041## Provenance4243| Question | Answer |44|---|---|45| What is the source of truth? | The user's request, originating spec/issue, and the skill's declared outputs |46| What is in scope? | Work covered by the skill's acceptance criteria and completion rules |47| What is explicitly out of scope? | Files, behaviors, and decisions outside the skill's declared boundary |48| Who or what consumes this artifact afterward? | The next skill in the workflow or the user |49| What evidence proves it is done? | Completion criteria met, artifact saved, validation passed |50| What risk remains? | Subjective judgment calls, missing context, or external dependency failures515253## Artifact5455Emit `LockfileMaintenanceArtifact` as both:56- JSON: `.agents/skills/platform/artifacts/lockfile-maintenance/{identifier}.json`57- Markdown view: same filename with `.md` extension585960## 61## 62## Rules6364- Rule: enumerate canonical `SKILL.md` files from `.agents/skills` before changing lock data.65- Rule: distinguish content hash drift from path drift, missing entries, and deleted skill entries.66- Rule: update hashes from the exact bytes currently in each `SKILL.md`; do not hash rendered excerpts or generated summaries.67- Rule: remove lock entries only when the corresponding skill path is intentionally absent and no symlink still points to it.68- Rule: preserve existing lockfile schema, indentation, and stable ordering unless the repository's maintenance script defines a different order.69- Rule: prefer `scripts/update-lockfile.mjs` for canonical bundle lock refreshes; inspect its dry-run output before committing changes.70- Rule: run the repository validator after lock updates and report the command, exit status, and any warning.71- Rule: if a lock update follows skill edits, include both the edited skill names and the resulting lock entries in the summary.7273## Workflow74751. Read the lockfile and list canonical skill files.762. Compare lock entries to the filesystem by skill name, path, and hash.773. Classify drift as missing entry, stale hash, extra entry, moved skill, duplicate name, or malformed metadata.784. Apply the smallest lockfile change that reconciles the intended tree.795. Validate the full skill bundle using the repository's available validation commands.806. Summarize every lockfile mutation and cite remaining drift, if any.8182## Script8384Use `scripts/update-lockfile.mjs` from this skill directory to reconcile the canonical skill tree with `skills-lock.json`.8586```bash87node .agents/skills/skill-dev/lockfile-maintenance/scripts/update-lockfile.mjs --dry-run88node .agents/skills/skill-dev/lockfile-maintenance/scripts/update-lockfile.mjs --write89```9091The dry run reports added, updated, and removed lock entries without changing files. The write mode preserves the lockfile schema, sorts skill names, and writes hashes from the exact current `SKILL.md` bytes.9293## Completion9495- the skill's completion criteria are explicitly checked96- the artifact is saved and validated97- any blockers or skipped validations are documented98- the next consumer is identified or the work is handed off99- no approval is required for lockfile writes: the script only updates skills-lock.json hashes for resolved SKILL.md files, reversible via git100---101@include .agents/skills/platform/contract-base.xml