Skip to content

Make a skill safe to install

Last reviewed October 24, 2026

Anthropic's advice to people installing skills is to treat it like installing software, and to use skills only from sources they trust (Agent Skills overview). That is the bar your skill has to clear. This page is about clearing it: doing nothing surprising, and making that easy to see.

What a skill can do on someone's machine

A skill's instructions steer an agent that can run commands, and its scripts run with the user's privileges and network access, like any other program. A badly written skill can delete the wrong files; a malicious one can direct the agent to do things its description never mentioned. People reviewing your skill are looking for the gap between what it says and what it can do, so close it: say in the README which commands it runs, which files it writes, and what it sends over the network.

allowed-tools grants; it does not restrict

The frontmatter field allowed-tools lets a skill pre-approve tools so the agent does not ask the user each time. In Claude Code that approval lasts for the turn that invoked the skill, it does not stop the agent using other tools, and workspace trust does not gate it (Claude Code skills). So a skill in a cloned repository can grant itself broad access the user never agreed to.

List the fewest tools the skill needs, scoped as tightly as the agent allows (Bash(git log:*), not Bash). A broad grant is among the first things a careful reviewer looks for, and the standard still calls the field experimental, so the skill should work without it.

Scripts that behave when an agent runs them

Agents learn how to call a script the way people do, by asking it. Give every script a skill ships these, where they make sense (using scripts):

  • --help: usage, every option, an example or two, and what the exit codes mean.
  • --version: the name and the same version as the skill's metadata, then exit.
  • --dry-run: for anything that writes, deletes, spends or sends, show exactly what would happen without doing it.
  • No interactive prompts, since an agent cannot answer them. Offer --yes where a step needs confirming, and --json where the output will be read by a program.
  • Results on stdout and diagnostics on stderr, a non-zero exit on failure, and secrets from environment variables, never from arguments and never printed.
shell
$ release-notes --version
release-notes 1.0.0
$ release-notes write --dry-run
Would write 12 lines to CHANGELOG.md under "## 1.1.0"
No changes made (dry run).

Pin your dependencies and commit the lockfile, so the script someone reviewed is the script that runs.

Content the skill fetches

A skill that reads web pages, issues or emails passes text from strangers to the agent, and that text can carry instructions. Anthropic also warns that a trustworthy skill can turn untrustworthy when something it fetches changes later. Say in the README which steps fetch outside content, and keep the instructions explicit about treating that content as data.

Stay on the right side of safety scans

This site's safety scan reads a listing's manifest and README. Among other things, it looks for:

  • Real keys or tokens in the repository. Use placeholders that are obviously fake.
  • Telling people to pipe a download straight into a shell. Download it, say how to verify it, then run it.
  • Hidden characters or encoded blobs in instructions. If you need one, say what it is right next to it.
  • Instructions about the agent's own rules rather than the task.

Add a SECURITY.md saying how to report a vulnerability. And if a finding on your listing is wrong, sign in and dispute it from the listing page.

Building something else? See the guides to a plugin or marketplace and an MCP server.