skills-lock · diff
v1.0.0 to v1.0.0
5 added, 9 removed. Audit A to A.
---
name: skills-lock
description: >-
skills.lock — version locking and integrity tracking for agent skills
repositories. Generates a SHA256-verified lock file that tracks every
skill with its version, file hash, dependencies, and last update. Use
when creating skills.lock for a repo, validating skill integrity, or
managing skill dependencies. Triggers on: "skills.lock", "lock file",
"skill integrity", "freeze skills", "skill dependencies".
license: MIT
compatibility: Claude Code, Jesse, Codex, Hermes, Windsurf, OpenCode, Gemini CLI, Copilot, Zed, VS Code, Goose
metadata:
version: "1.0.0"
author: LeadMagic
category: automation
tags: [skills-lock, versioning, integrity, dependencies, lockfile]
related_skills: [agent-skills-repo-authoring, hermes-agent-skill-authoring]
frameworks:
- "npm package-lock.json — deterministic dependency resolution"
- "Cargo.lock (Rust) — version pinning and integrity"
- "SHA-256 — cryptographic hash for file integrity verification"
---
# skills.lock
## Overview
skills.lock is a manifest file that pins every skill in a repository to a
specific version with a cryptographic hash. It ensures that consumers of your
skills library get exactly what you shipped — no tampering, no drift, no
surprises. When a CI pipeline or agent loads skills, it verifies the lock file
first. If a hash doesn't match, the skill has been modified and the consumer
is warned. This skill covers generating, validating, and maintaining skills.lock.
- ## Frameworks Referenced
-
- This skill is grounded in public frameworks and source material relevant to the task:
+ ## Authoritative Foundations
- - **npm package-lock.json — deterministic dependency resolution.** Use the relevant method or published guidance where it improves the requested deliverable; do not cite it as decoration.
- - **Cargo.lock (Rust) — version pinning and integrity.** Use the relevant method or published guidance where it improves the requested deliverable; do not cite it as decoration.
- - **SHA-256 — cryptographic hash for file integrity verification.** Use the relevant method or published guidance where it improves the requested deliverable; do not cite it as decoration.
+ - **npm package-lock.json — deterministic dependency resolution** — deterministic dependency resolution
+ - **Cargo.lock (Rust) — version pinning and integrity** — version pinning and integrity
+ - **SHA-256 — cryptographic hash for file integrity verification** — cryptographic hash for file integrity verification
## When to Use
Trigger phrases: "generate skills.lock", "create lock file for skills", "freeze
skill versions", "verify skill integrity", "lock file for agent skills",
"skill dependency lock", "skills.lock validation"
## Step-by-Step Process
### Phase 1: Generate skills.lock
**The lock file structure (JSON):**
```json
{
"version": "1.0.0",
"repository": "LeadMagic/gtm-skills",
"generated_at": "2026-06-07T18:00:00Z",
"generator": "hermes-agent v2026.5.29.2",
"total_skills": 172,
"skills": {
"founder-led/founder-sales": {
"version": "1.0.0",
"path": "skills/founder-led/founder-sales/SKILL.md",
"sha256": "a1b2c3d4e5f6...",
"dependencies": [
"founder-led/pricing-strategy",
"sales-revops/sales-enablement"
],
"frameworks": [
"SPICED (Winning by Design)",
"SPIN Selling (Neil Rackham)"
],
"size_bytes": 10676,
"last_updated": "2026-06-07T12:00:00Z"
}
}
}
```
**Generate script (run after every skill change):**
```bash
#!/bin/bash
# scripts/generate-skills-lock.sh
echo "Generating skills.lock..."
SKILLS_COUNT=$(find skills -name "SKILL.md" | wc -l | tr -d ' ')
cat > skills.lock << EOF
{
"version": "1.0.0",
"repository": "LeadMagic/gtm-skills",
"generated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"total_skills": $SKILLS_COUNT,
"skills": {
EOF
FIRST=true
for skill in $(find skills -name "SKILL.md" | sort); do
SKILL_NAME=$(echo "$skill" | sed 's|skills/||' | sed 's|/SKILL.md||')
SHA256=$(sha256sum "$skill" | cut -d' ' -f1)
SIZE=$(wc -c < "$skill" | tr -d ' ')
# Extract version from YAML frontmatter
VERSION=$(head -20 "$skill" | grep "version:" | head -1 | sed 's/.*"\(.*\)".*/\1/' | sed 's/version: *//' | tr -d '"' | tr -d ' ')
if [ "$FIRST" = false ]; then
echo "," >> skills.lock
fi
FIRST=false
cat >> skills.lock << INNER
"$SKILL_NAME": {
"version": "$VERSION",
"path": "$skill",
"sha256": "$SHA256",
"size_bytes": $SIZE,
"last_updated": "$(date -u -r "$skill" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u +%Y-%m-%dT%H:%M:%SZ)"
}
INNER
done
cat >> skills.lock << FINAL
}
}
FINAL
echo "skills.lock generated: $SKILLS_COUNT skills locked"
```
### Phase 2: Validate skills.lock
**Validation script:**
```bash
#!/bin/bash
# scripts/validate-skills-lock.sh
echo "Validating skills.lock..."
ERRORS=0
SKILLS=$(find skills -name "SKILL.md" | sort)
for skill in $SKILLS; do
SKILL_NAME=$(echo "$skill" | sed 's|skills/||' | sed 's|/SKILL.md||')
ACTUAL_HASH=$(sha256sum "$skill" | cut -d' ' -f1)
LOCKED_HASH=$(python3 -c "
import json
with open('skills.lock') as f:
data = json.load(f)
print(data['skills'].get('$SKILL_NAME', {}).get('sha256', 'NOT_FOUND'))
" 2>/dev/null)
if [ "$LOCKED_HASH" = "NOT_FOUND" ]; then
echo "ERROR: $SKILL_NAME not found in skills.lock"
ERRORS=$((ERRORS + 1))
elif [ "$ACTUAL_HASH" != "$LOCKED_HASH" ]; then
echo "ERROR: $SKILL_NAME hash mismatch"
echo " Locked: $LOCKED_HASH"
echo " Actual: $ACTUAL_HASH"
ERRORS=$((ERRORS + 1))
fi
done
if [ $ERRORS -eq 0 ]; then
echo "skills.lock valid. 0 errors."
else
echo "skills.lock validation FAILED: $ERRORS error(s)"
exit 1
fi
```
### Phase 3: CI Integration
**GitHub Actions step (add to validate.yml):**
```yaml
- name: Validate skills.lock
run: bash scripts/validate-skills-lock.sh
```
### Phase 4: Consumer Usage
**How AI agents consume skills.lock:**
1. Clone/fetch skills repo
2. Read `skills.lock` to discover available skills and versions
3. Verify SHA256 of a skill before loading it — integrity check
4. Check `dependencies` field to load prerequisite skills
5. Use locked version for reproducible behavior
## Output Format
```json
{
"version": "1.0.0",
"repository": "owner/repo",
"generated_at": "ISO-8601",
"total_skills": N,
"skills": {
"category/skill-name": {
"version": "X.Y.Z",
"path": "skills/category/skill-name/SKILL.md",
"sha256": "hex-hash",
"dependencies": ["other-skill"],
"frameworks": ["Framework Name (Authority)"],
"size_bytes": N,
"last_updated": "ISO-8601"
}
}
}
```
## Implementation Checklist
- [ ] skills.lock generated after every skill change (automated in CI)
- [ ] SHA256 verified for every skill (no hash mismatches)
- [ ] skills.lock committed to repo alongside skills
- [ ] Validation runs in CI on every push and PR
- [ ] Consumer instructions documented (how to verify a skill's integrity)
- [ ] Version field matches skill's frontmatter version
- [ ] Total count matches actual skill count
## Quality Check
Before delivering, verify:
- [ ] Output matches the user's stated request
- [ ] Named frameworks or sources are reflected in the recommendation
- [ ] The deliverable is specific enough for an agent to execute
- [ ] Any assumptions, risks, or dependencies are explicit
- [ ] No unsupported claims, invented facts, or private/internal references are included
## Common Pitfalls
1. **skills.lock not updated after skill changes.** Skill changes pushed.
skills.lock stale. Validation fails. Fix: Generate skills.lock as part
of the commit/push workflow. Never commit skill changes without updating
the lock file.
2. **No validation in CI.** Stale or corrupted skills.lock goes undetected.
Consumers load tampered or outdated skills. Fix: CI runs validation on
every push. Failing validation blocks merge.
3. **Lock file too large.** 500+ skills with full dependency trees = multi-MB
lock file. Fix: Keep it lean. SHA256 + version + path + size. Skip full
metadata (frameworks, dependencies are optional extensions).
4. **No consumer documentation.** Consumers don't know skills.lock exists
or how to use it. Fix: Document in README. "To verify skill integrity:
check that SHA256(skill) matches skills.lock."
## Why This Matters (Unique GTM Skills Differentiator)
Most agent skills repos on GitHub have NO lock file. They publish skills
with no integrity verification. If someone modifies a skill silently, there's
no way to detect it. skills.lock provides:
1. **Tamper detection:** Any modification to a skill file changes its SHA256.
Validation catches it immediately.
2. **Reproducible loading:** Consumers can verify they have the exact skill
the publisher intended.
3. **Dependency tracking:** Skills can declare dependencies. Agents can load
prerequisites automatically.
4. **Supply chain integrity:** If a malicious PR modifies a skill, the lock
file hash won't match and CI blocks it.
This is unique to `gtm-skills` — a first-of-its-kind lock file for agent
skills repositories.
## Execution Artifacts
- This skill includes lightweight artifacts the agent can load on demand:
-
- `references/framework-notes.md` — named frameworks, citation anchors, and operating assumptions
- `templates/output-template.md` — copy-paste deliverable structure for the user
- `scripts/check-output.py` — local checklist validator for required sections
-
+ This skill includes lightweight artifacts the agent can load on demand:
Use the artifacts when the user asks for an implementation-ready deliverable, a repeatable workflow, or a quality check rather than generic advice.
## Related Skills
- `agent-skills-repo-authoring` — Repository scaffolding and CI/CD
- `hermes-agent-skill-authoring` — Skill authoring standards
- `skills-library-audit` — Systematic skill library auditing