← skillsmith scanner · all guides

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.

What the scanner treats as red flags (2026 engine)

Heads-up for authors: URLs that start with api., data. or telemetry. subdomains add a small score penalty (+4), because exfiltration endpoints often hide there. Calling a legitimate API like api.github.com is fine — expect one informational finding, not a bad verdict. Combined findings can push a skill to "medium"; check the finding list to see exactly which line triggered it.

Recent engine updates catch obfuscation that used to slip past keyword scans — avoid all of these, even unintentionally:

• Injection phrasing in description — the frontmatter is scanned too, not just the body.
• Unicode tricks — zero-width characters, RTL/bidi direction overrides (text can look reversed), fullwidth characters, stacked combining marks. All are folded/normalized before scanning.
• Base64-encoded text — short blobs are decoded and the plaintext is scanned.
• Credential-bearing URLs — links containing key=, token=, secret=, password= or auth= query parameters.
• Malformed YAML — invalid frontmatter fails the lint with a clear error instead of a confusing verdict.

Before you ship

1. Run the local linter: pip install skillsmith-scanner && skillsmith lint .
2. Scan it on skillsmith.ch and read every finding — false positives tell you where a reviewer might also stumble.
3. Publish with {"publish": true} so the clean verdict and the exact text become verifiable in the public database.
4. 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.