Claude Skill Security: Secrets, Paths, Permissions

By Yanni Papoutsis | 7 min read | 2026-07-19

A skill is executable influence: plain-text instructions that steer a model with access to your files, shell, and connected services. That makes skill folders worth securing in both directions, what you put into skills you write, and what you accept from skills you install. This post covers the three recurring risk areas: secrets, paths, and permissions, plus a practical audit checklist for third-party skills.

For authoring fundamentals, start with writing a Claude skill from scratch.

TL;DR: Never store real credentials anywhere in a skill folder; skills are plain text, they get zipped, shared, committed, and read in full by anyone who installs them, so use placeholders like YOUR_API_KEY in every example and have bundled scripts read real values from environment variables at runtime. Keep every path inside a skill relative to the skill folder, never absolute, and never instruct broad filesystem operations when a narrow one will do. Treat installed third-party skills as you would a shell script from a stranger: read every file before installing, especially bundled scripts and any instruction telling Claude to fetch remote content or run commands, and prefer skills whose scripts you can understand in one sitting. Where the environment supports scoping which tools a skill may use, scope tightly. Re-audit on every update, because an update is a new skill wearing a trusted name.

Secrets: the rules and the mechanics

Rule 1: nothing real, anywhere in the folder

Not in SKILL.md, not in scripts, not in example files, not in a commented-out line. Every file in the folder ships when the skill ships, and a .skill file is just a zip anyone can open, as covered in publishing and sharing Claude skills.

# Wrong: real value in a bundled script
API_KEY="sk-live-..."

# Right: read from the environment, fail with instructions
if [ -z "$WEATHER_API_KEY" ]; then
  echo "ERROR: export WEATHER_API_KEY before running this skill" >&2
  exit 1
fi

And in documentation and examples, placeholders that cannot be mistaken for real values:

API_KEY=YOUR_API_KEY
DATABASE_URL=postgres://USER:YOUR_PASSWORD@HOST:5432/DBNAME

Rule 2: instructions must not launder secrets either

A subtler leak: a skill whose instructions say "use the token from ~/.config/service/token when calling the API". The token never appears in the folder, but the skill now teaches every session to surface it, and the value can end up echoed into conversation output or logs. Better instruction pattern:

Run `scripts/call_api.sh <endpoint>`. The script reads the token
from the SERVICE_TOKEN environment variable itself. Never print
the token or include it in output shown to the user.

Keep the secret inside the script's process, out of the conversation.

Rule 3: sweep before every share and every commit

A minimal pre-share scan you can run from the skill's parent directory:

grep -rniE "(api[_-]?key|token|secret|password)\s*[:=]\s*['\"]?[a-z0-9]{16,}" changelog-writer/

It is crude, and crude is fine: it catches the paste-accident that causes most real leaks. Add it to the same pre-publish checklist as your trigger tests from the testing and eval guide.

Paths: keep skills inside their box

Relative paths only

Every reference inside a skill should be relative to the skill folder. Absolute paths break portability, and they also encode information about your machine and account names you may not intend to publish.

# Wrong
Run /Users/yanni/skills/report-gen/scripts/build.sh

# Right
Run scripts/build.sh from the skill folder.

Narrow operations over broad ones

Skill instructions get followed energetically. An instruction like "clean up old output files" invites a broad delete; write the narrow version:

Delete only files matching report-draft-*.html in the output
directory the user specified. Never delete outside that directory,
and list what will be deleted before deleting it.

The list-before-destroy pattern costs one step and converts silent damage into a visible decision.

Be suspicious of skills that reach outward

When auditing someone else's skill, instructions that read files outside the working project, write to shell configuration files, or touch credential stores (~/.ssh, ~/.aws, browser profiles) deserve a hard justification. Most legitimate skills never need any of that.

Permissions: scope what a skill can do

A skill's blast radius is bounded by what the session it runs in can do. Two layers of control:

Environment-level scoping. Some environments support restricting which tools a skill may invoke while active, via metadata or configuration. Where available, scope to the minimum: a summarisation skill needs no shell; a formatting skill needs no network.

Instruction-level scoping. Even without enforcement, explicit boundaries in the skill body shape behaviour and make violations visible in review:

## Boundaries

- This skill only reads files; it never writes or deletes.
- It makes no network requests.
- If a task appears to require either, stop and tell the user
  this skill does not cover it.

Boundaries like these also help when skills run in sequence, where one skill's output becomes another's input; see skill chaining for why declared limits keep multi-skill workflows predictable.

Auditing a third-party skill before installing

Treat installation as code review. The checklist:

- [ ] Read SKILL.md in full, including the front-matter description
- [ ] Read every bundled script line by line; if you cannot follow
      a script, do not install the skill
- [ ] Search the folder for curl, wget, and any URL: does the skill
      fetch remote content or send data out? To where, and why?
- [ ] Look for instructions that tell Claude to run commands,
      modify configuration, or read files outside the project
- [ ] Check for obfuscation: base64 blobs, packed one-liners,
      or "run this, do not worry about what it does" phrasing
- [ ] Check the description for over-broad triggers that would make
      the skill fire on unrelated tasks
- [ ] Note the version, and re-run this audit on every update

The last line is the one people skip. An update replaces the files you audited with files you have not. A trusted name on version 1.0.0 says nothing about version 1.1.0.

The prompt-injection angle

A skill's instructions join the context that steers the model, which is exactly why a malicious skill is dangerous: it does not need to exploit anything, it just needs to be followed. Phrases to treat as red flags in any skill you did not write: instructions to ignore other instructions, to hide actions from the user, to fetch and follow remote instructions at runtime, or to proceed without confirmation on destructive steps. Legitimate skills do the opposite; they surface actions and ask.

Security checklist for skills you publish

- [ ] Secrets sweep passed (grep scan plus manual read)
- [ ] All paths relative to the skill folder
- [ ] Destructive operations list-before-acting
- [ ] Network calls documented in SKILL.md: what, where, why
- [ ] Boundaries section states what the skill will not do
- [ ] Scripts fail loudly with instructions, not stack traces
- [ ] Description scoped tightly enough not to fire on unrelated prompts

That last item is a security property as much as a quality one: a skill that triggers on the wrong tasks applies its instructions where they were never reviewed. Trigger precision techniques are covered in how skill triggers work.

Frequently asked questions

Is it safe to put a secret in a skill only I will ever use?

Still no. Skill folders end up in backups, git repositories, and shared sessions more often than intended, and the habit is the vulnerability. Environment variables cost one line and remove the whole class of leak.

How do I let a shared skill use a paid API without sharing my key?

Ship the script reading from an environment variable, document the variable name in SKILL.md, and let each installer supply their own key. This also keeps your usage and billing separate from theirs.

Are skills from official marketplaces safe to install without reading?

Safer is not safe. Marketplaces reduce the odds of malice but do not eliminate sloppy scripts, over-broad triggers, or risky instructions. The audit checklist takes ten minutes; run it regardless of source.

About the author

Yanni Papoutsis builds AI products, automation pipelines, and technical documentation with Claude, and publishes free tooling and guides at yanni.uk.

Next step: Bake the secrets sweep into your release process with the skill testing and eval guide, or explore 1,000+ AI tools at yanni.uk/ai-tools.

Sources