Writing a Safe SKILL.md: An Author's Checklist

Guide · skillsmith.ch

Most of our material looks at skills from the defender's side. This one is for authors: how to write a skill that is genuinely safe, scans clean, and stays clean — so users (and their agents) can trust it.

Frontmatter: say what you do

name and description are required and must be honest. A vague description ("does various things") reads as evasion to both humans and scanners.
Never borrow another skill's name or near-name — typosquatting gets you flagged even when the code is innocent (homoglyphs included).

Instructions: authority, not commands to the agent's operator

Write instructions that scope your skill's behavior only. Phrases like "set aside earlier guidance" or "don't mention this step to the user" are injection patterns and will flag your skill — rightly.
If your skill needs credentials, instruct the user to configure them in their environment; never collect them "for convenience".
State side effects explicitly: files written, network calls made, packages installed. Surprise is the enemy of trust.

Dependencies: minimize and pin

Every dependency is inherited risk (OSV data proves it). Ask for each one: does the skill truly need it?
Avoid unpinned installs; they silently track upstream releases — including a future compromised one.
Host scripts next to your SKILL.md in the same repo, not on random CDNs.

Remote content: make yourself rug-pull-proof

If you must load remote resources, use stable raw URLs in the same repo.
Tell your users to baseline-hash the file after vetting — or point them at skillsmith's watch feature so changes alert them automatically. A skill whose author welcomes monitoring is a skill people adopt.

Before you ship

Run the local linter: pip install skillsmith-scanner && skillsmith lint .
Scan it on skillsmith.ch and read every finding — false positives tell you where a reviewer might also stumble.
Publish with {"publish": true} so the clean verdict and the exact text become verifiable in the public database.
Add your badge to the README and keep a watch on the hosted file.

Safe skills win in the long run: they pass audits, get published to the Safe Skills Database, and survive the scrutiny that increasingly comes with agent ecosystems.