SkillCap Lock

Review what an Agent Skill can do before an agent loads it. SkillCap Lock validates the Agent Skills specification, hashes every file, extracts observable capability evidence, scores instruction quality and risk, and compares the result with a reviewed baseline.

Position in the ecosystem

skills, skillpm, skills-lock, sklock, and Tank focus on discovery, installation, dependency resolution, or reproducible distribution. skill-check focuses on structural quality. SkillCap Lock is the static review layer for capability change and quality policy; it never installs or executes a skill.

Install

npm install --save-dev skillcap-lock
npx skillcap --help

Node.js 20 or newer is required.

Baseline and CI

# Discover every nested SKILL.md and create the reviewed baseline
npx skillcap init ./skills

# Review semantic changes after an update
npx skillcap check ./skills --markdown
npx skillcap check ./skills --json > skillcap-report.json
npx skillcap check ./skills --sarif > skillcap.sarif

# Frozen CI: fail when the lock is missing or stale
npx skillcap check ./skills --frozen

# Accept an intentionally reviewed update
npx skillcap update ./skills --accept

The generated skillcap.lock.json stores file hashes, redacted capability evidence, quality/risk scores, validation issues, and provenance. It does not store skill bodies or secret values.

Evidence and scoring

Capabilities are reported with kind, value, file, line, provenance, and confidence:

| Evidence | Examples | | --- | --- | | network | URLs and remote destinations | | command / interpreter | npm, curl, python, shell and runtime invocations | | write / path | filesystem mutation language and paths | | executable | bundled scripts and executable filenames | | env / secret | environment names and token-shaped strings (redacted) |

Each skill has:

• a risk score reflecting observable network, command, write, executable, and secret signals;
• a quality score reflecting valid frontmatter, useful descriptions, body size, and completeness;
• stable validation IDs (SKV001–SKV006) and capability delta IDs (SKC001–SKC008).

Static evidence is deliberately conservative. It can miss behavior hidden behind indirection and can over-approximate examples; it is a review aid, not a sandbox or security certificate.

Policies

{
  "maxRiskScore": 35,
  "minQualityScore": 75,
  "requireFrontmatter": true,
  "deny": [
    { "kind": "network", "value": "internal.example.com" },
    { "kind": "executable", "value": "deploy.sh" }
  ]
}

Run npx skillcap check ./skills --policy skillcap.policy.json. Policy violations fail with exit code 1.

Commands and output

skillcap init <directory>
skillcap check <directory> [--policy file] [--frozen] [--json|--markdown|--sarif]
skillcap update <directory> --accept
skillcap explain <directory> <skill-name>

Exit code 0 means no high-severity change or policy violation, 1 means review is required, and 2 means invalid input or scanner failure. JSON is schema-versioned; Markdown is suitable for pull requests; SARIF integrates with code scanning.

Development

npm install
npm run lint
npm test
npm run test:cli
npm pack --dry-run

Issues and pull requests are welcome in the GitHub repository.

License

MIT © Debaditya Hait