skill_leak_scan v1.0.0

name: "skill_leak_scan" description: "Scan a skill or agent package for leaks before public release: secrets, personal data, machine paths, and client names, plus flagging service code that should split into a plugin, with a fail-closed checklist. Use when a skill, plugin, agent package, template pack, or example bundle is about to be published, shared outside the team, listed in a catalog, or updated with new examples, and before any first public release of a package that was private while it was built." metadata: { "includeInPrompt": true }

Skill Leak Scan

Purpose

A package leaks in ways its author cannot see. The author knows which key is a fixture and which path is their own machine, so both look normal on the page. A reader, a catalog, or a bot scraping new releases sees them plain. This skill is the outgoing gate: scan the exact copy that will ship, decide every finding in writing, split out code that is really a service, and block the release until the gate passes. It covers outgoing release. Auditing a package you received from someone else is a different job with a different skill.

The bundled scanner is bin/leak_scan.py. It prints masked previews only, never a full value, so its report is safe to file with the release note. Rule details live in references/scan-rules.md, worked clean and dirty reports in references/report-examples.md, fixes and the plugin split test in references/remediation.md, and the full gate in references/release-checklist.md.

Workflow

1. Freeze the release copy. Copy the package to a clean folder exactly as it will ship. Scan that copy, never the working folder. If the shipped files change after the scan, scan again. A scan of a different copy proves nothing about the one that went out.
2. Build the denylist before scanning. One private term per line in a text file: client and customer names, project codenames, private repository names, internal hostnames, and names of real people used in examples. No public pattern list contains your client list, so this file is what catches the leak that matters most. Sources and method are in references/scan-rules.md.
3. Run the scanner in strict mode. Run python3 bin/leak_scan.py <release-copy> --denylist <denylist-file> --strict and save the output. Strict mode makes REVIEW findings block alongside BLOCK findings, so nothing passes on a shrug. Add --format json when the report needs to feed another tool.
4. Triage every finding by level. BLOCK means stop: a known secret format, a forbidden file such as .env or a .db, an SSN pattern, a Luhn valid card number, or a denylist hit. REVIEW means a person decides and writes the reason down: a generic secret assignment, a machine path, an email or phone, a high entropy string, a leftover log, or a plugin signal. INFO means read it and confirm the placeholder reads as fake at a glance. Never allowlist a BLOCK secret rule.
5. Rotate anything real before cleaning it. If a credential could be real, revoke or rotate it at the issuing service first, check that service for unknown use, and only then remove the value from the package. Deleting a line leaves the working credential in git history, forks, and caches. Order and proof standards are in references/remediation.md.
6. Replace, do not just delete. Put a plainly fake placeholder where a key was, a generic example where a client example was, a package relative path where a machine path was, and a schema plus synthetic seed where a database was. A package with holes where the teaching was helps nobody, and a half emptied example invites the next author to paste a real one back in.
7. Decide the plugin split for every code finding. Apply the five question test in references/remediation.md. Code that polls, holds a token, keeps state, runs on a schedule, or opens a port belongs in a plugin or connector with its own credential handling and its own release. Code that takes input, does one job, and exits can stay as a script. Record each call in the release note.
8. Run the scans the bundled tool cannot do. For any package that was ever public or shared, scan full git history with gitleaks or trufflehog, not just the shipping files. Open every image and screenshot and look at it. Text scanning says nothing about a name burned into a chart or a dashboard screenshot with real rows in it.
9. Do the human read. Read SKILL.md and every example in full, as a stranger. Hunt the five misses listed at the end of references/scan-rules.md: names in prose, case studies that identify a customer by combined details, credentials split or encoded across lines, internal URLs missing from the denylist, and unreleased product names.
10. Write the release note and only then publish. Six lines: the scanner command as run, the verdict and counts, every REVIEW decision with its reason, anything rotated (service and credential type, never the value), anything split and where it went, and who did the human read and what they read. The checklist in references/release-checklist.md must pass in full. An item that cannot be checked gets a written reason and a named person accepting the gap, or the release waits.

Output Contract

A finished scan hands back:

• The scan report from the release copy, with every finding masked, plus the verdict (CLEAN, REVIEW, or BLOCKED) and counts by level
• The denylist file used, kept with the release record
• A decision for every REVIEW finding, written in one or two sentences each
• A rotation record for every real or possibly real credential: service, credential type, date, and who rotated it, with no values anywhere
• A plugin split decision for every code finding, and the new home of anything that split out
• The six line release note from references/remediation.md, and a completed copy of the checklist in references/release-checklist.md

If any item is missing, the gate has not passed, whatever the scanner verdict line says.

Operating Rules

1. Fail closed. Unscanned is not clean, unread is not reviewed, and a tool error is a blocked release, not a pass. When the scanner cannot read a file, a human reads it another way or it leaves the package.
2. Never print a secret to prove you found one. Masked previews, file names, line numbers, and a short hash are enough for the owner to locate and rotate a value. A report, ticket, or chat message that carries the full value is a second leak created by the cleanup itself.
3. Rotation beats removal, every time. A credential that left the machine is compromised until the issuing service says otherwise by accepting a rotation. History rewriting with git-filter-repo comes after rotation, and only when the package was already public.
4. Entropy is a hint, not a verdict. High entropy shows randomness, not sensitivity: hashes, UUIDs and generated ids score high and are often harmless, and weak human passwords score low and are still secrets. Entropy findings always need a human call.
5. Suppression needs a reason that travels with the code. Inline suppressions carry a reason on the same line, allowlist entries live in version control next to the package, and the whole allowlist gets re-read at every release. A silent or growing allowlist hides real leaks among ignored fixtures.
6. One copy ships, the scanned copy. Never keep a convenience copy of split plugin code, a real example, or a working config inside the skill after the clean version is made. Two copies means the fix lands in one and the leak ships in the other.
7. Accuracy rule. Every factual claim in a skill must be verified via web search or a primary source. Never invent numbers, dates, quotes, or events. Unverifiable means cut it or frame it as opinion. No confident unverified claims, ever.