Doc / Python script / example skill (ZIP + PDF)Write Agent Skills that trigger when they should and are safe to share: an authoring guide (trigger-first descriptions, lean bodies, finish conditions, gated side effects), a 7-criterion review rubric, a worked example skill, and skill_lint.py, which scores any SKILL.md folder and flags weak descriptions, missing steps, secrets, instruction-override language, curl-pipe-shell and unconfirmed send/pay/delete steps. Works as a CI gate.
What's inside
01_Skill_Authoring_Guide.md02_Skill_Review_Rubric.mdexample-skill/SKILL.mdskill_lint.py15_Agent_Skill_Authoring_Kit.pdf: every document in one printable guide
Verify it works
python3 skill_lint.py --selftestprintsselftest ok(the bundled example scores 90+; a deliberately bad skill is flagged for a weak description, secret, override language and unconfirmed side effects).python3 skill_lint.py example-skillshows the score and findings for the example.- Run it on your own skills:
python3 skill_lint.py ~/.agents/skills/* --min-score 75(exit 1 fails a CI job). - Review each skill with
02_Skill_Review_Rubric.md; rewrite descriptions using section 1 of01_Skill_Authoring_Guide.md. Python 3.9+, no installs.
Preview
First part of the main document, shown as-is:
Writing Agent Skills that agents actually pick up
An Agent Skill is a folder with a SKILL.md file: YAML frontmatter (name, description at minimum) followed by instructions, optionally with scripts/, references/ and assets/. Agents read only the name and description at startup and load the rest when a task matches, so the description decides whether your skill is ever used. Format reference: https://agentskills.io and https://github.com/agentskills/agentskills.
1. The description is a trigger, not a tagline
- Start with when to use it: "Use when …" plus the concrete situations, file types or phrases that should activate it.
- Say what it produces.
- Say when not to use it if a neighbouring skill could be confused with it.
- Keep it short (the linter warns above 1,024 characters).
2. Body: instructions an agent can follow
- Numbered steps with a clear finish condition ("done when the test passes and the summary is written").
- Put long references in
references/and point to them; don't paste them inline. Smaller SKILL.md files load faster and cost less context. - Name every script and the exact command to run it. Scripts should be deterministic and print a clear pass/fail.
- State inputs you need from the user and what to do if they are missing.
3. Safety
- No secrets, tokens or personal data in the folder.
- Any step that sends, posts, pays or deletes must say "ask the user first" and name the action.
- Don't instruct the agent to ignore other instructions, disable checks or hide what it did.
- Pin or vendor anything you download; don't
curl | shfrom a moving URL.