Publishing agent skills without leaking secrets

Agent skills have a security property that is easy to miss: they are authored inside real projects, right next to .env files, service configs, and terminal history full of tokens — and then they are distributed, by design, to every machine on the team. That combination makes them a quiet, efficient channel for leaking credentials.

This is not hypothetical caution. It's the same mechanism behind years of accidental secrets in git repos and npm packages — a packaging step that swept up more than the author intended. Skills add a twist: they are often written by the agent itself, summarizing a working session in which real values were on screen.

The four ways secrets end up in skills

1. The helpful example. "Here's how we call the internal API" — with a real bearer token pasted into the example, because the author copied a command that worked.
2. The swept-up file. The skill folder gets packaged with everything in it: the .env used while testing, a config.local.json, a private key that happened to live there.
3. The agent-authored draft. You ask your agent to "turn what we just did into a skill". What you just did involved real hostnames, real credentials, real customer identifiers — and the agent, summarizing faithfully, includes them.
4. The internal detail that isn't a secret but shouldn't travel. Database schemas, unreleased product names, client identifiers. Not credentials — still not for every laptop in the company, and definitely not for a public location.

Note what these have in common: none of them are malicious, and none of them are visible at a glance in a folder that "just contains markdown".

Defense layer 1: authoring habits

Two habits eliminate most incidents at the source:

• Placeholders, always. Examples use YOUR_API_KEY and api.example.com. If the example only works with a real value, that's a sign the material belongs in an MCP server's configuration, not in a distributed document.
• Review agent-authored skills before publishing. Read the draft as if it were leaving the company — because once distributed, it effectively has.

Habits, however, fail at scale — which is why the pipeline has to check.

Defense layer 2: the publishing pipeline

A publishing flow for skills should behave like a paranoid release engineer:

• Exclude secret-shaped files by default. .env and friends, key files, local configs — stripped automatically and listed by name in the manifest, never silently dropped. The author must see what was excluded to notice when something surprising is in the folder.
• Show a manifest before anything uploads. Exact files, sizes, target audience — and a human approves it. Auto-publishing a folder the agent assembled is how twist #3 above ships to production.
• Scan content server-side, and let findings block. Token patterns, private keys, high-entropy strings — checked again on the server, where a compromised or outdated client can't skip the step. A finding fails the publish loudly rather than shipping "just this once".

This is how the MasterSkills pipeline is built: environment files are auto-excluded and named in the manifest, nothing uploads before explicit approval, and a server-side secret scan rejects findings — the same rules whether a human or an agent initiates the publish. The two product-wide guarantees exist precisely for this risk class: nothing is written to disk without approval, nothing is published without approval.

Defense layer 3: blast-radius control

Assume a leak eventually happens anyway, and shrink what it reaches:

• Private by default. A skill visible only to your organization leaks to your organization — bad, recoverable. A public one leaks to the internet.
• Scope access. The skill with infrastructure detail belongs to the platform team's scope, not "everyone with a laptop".
• Keep versions and an audit trail. When something slips through, you need to answer which version, since when, installed by whom — and to publish a clean version everyone actually receives.

The one-line policy

If your team adopts a single rule, make it this: skills are published through a pipeline, never copied around it. Every failure mode above gets caught by a pipeline that excludes, shows, scans, and scopes — and none of them get caught by cp -r.