Writing Better Skills

Use when creating or improving a skill for an AI agent, especially when the skill needs strong trigger wording, project-local context, references, scripts, t...

Security Scan

The skill is internally consistent: its files, scripts, and instructions match a meta-skill for authoring other skills and do not request unrelated credentials or external installs.

Purpose & Capability

Name/description (authoring skills) align with the shipped files: templates, references, validator, example project, generator, tests, and a small self-healing helper. All required artifacts are appropriate for a skill-authoring/reference toolkit.

Instruction Scope

SKILL.md instructs agents to read/write project-local files, run provided scripts, and use references. Those instructions are consistent with the purpose. The only file-write behavior called out is creating project.skill.md from the template and a narrow self-healing script that creates a missing output directory — both documented and expected.

Install Mechanism

No install spec or external downloads; this is an instruction-and-scripts package that runs local Python scripts. No evidence of fetching arbitrary remote code or using obscure host URLs.

Credentials

The skill requests no environment variables, credentials, or config paths. All scripts operate on local files passed as arguments; there are no unrelated secrets or external service tokens required.

Persistence & Privilege

always is false and the skill is user-invocable/autonomous invocation is enabled (platform default). The skill does not request permanent presence or modify other skills' configs. Autonomous invocation is normal — no additional privilege escalation observed.

Assessment

This package is a meta-skill for writing skills and appears coherent. Before installing or allowing autonomous runs: 1) skim the scripts (scripts/quick_validate.py and the reference generator) to ensure you trust their local file operations; they operate on repository files and may create project.skill.md from the template and create missing output directories via a benign healing script. 2) Never put secrets in project.skill.md (the templates explicitly warn against it). 3) Run the quick_validate and provided tests locally in a safe environment if you want to confirm behavior before enabling autonomous invocation. 4) If you use this on sensitive repos, be mindful that agents following this skill will write small project-local files and run shipped Python scripts — audit them first.

Create better skills for agents.

A skill helps an agent do work. It is reusable operational guidance plus optional references, scripts, tests, and narrow remediation. It is not something that "turns an agent into a skill."

This skill is the control plane for authoring other skills:

• it tells the agent when to use the skill-creation framework
• what laws must not be violated
• which references to read for each decision
• when scripts, tests, and self-healing are justified
• what completion means

When to Use

Use this when authoring or revising a skill and you need to decide:

• what belongs in SKILL.md
• what should move into references/
• when project-local context is needed
• when to add scripts and tests
• whether self-healing is justified
• whether a fresh agent could use the skill without guessing

The Iron Laws

NO PROJECT-SPECIFIC CONTEXT IN THE GLOBAL SKILL

If a path, command, constraint, or convention belongs to one repository, it goes in project.skill.md, not in the reusable skill.

NO SKILL IS COMPLETE UNTIL A FRESH AGENT COULD USE IT WITHOUT GUESSING CRITICAL FACTS

If another agent would have to invent project-local commands, output paths, trigger conditions, or completion criteria, the skill is incomplete.

Violating the letter of these laws is violating the spirit of the skill.

Project-Local Context Comes First

The global skill must stay reusable.

Before doing substantial work with a skill in a repository:

1. Look for project.skill.md in the project root.
2. If it exists, read it before taking action.
3. If it does not exist and local context is needed, create it from project.skill.template.md.
4. Put environment-specific paths, commands, constraints, and conventions in project.skill.md, not in the global skill.
5. Treat project.skill.md as overriding generic guidance in SKILL.md when local details differ.

Read references/project-skill-context.md before defining or revising that contract.

Skill Organization Model

SKILL.md = the router

SKILL.md is the main behavioral document. It should tell the agent:

• when to use the skill
• what laws and stop conditions apply
• what order to follow
• which references to read
• which scripts to run
• what completion requires

references/ = deep guidance

References hold heavier, conditional, or decision-specific material.

Use references for:

• description-writing rules
• project-local context rules
• architecture-level decisions
• script/test conventions
• self-healing rules
• behavioral validation
• completion gates

scripts/ = deterministic helpers

Use scripts for repeated deterministic work the agent should not keep re-deriving.

tests/ = proof

Use tests to prove shipped scripts or promised behaviors work.

self-healing/ = narrow remediation

Use self-healing only for safe, local, repeatable fixes.

Architecture Levels

Choose the smallest structure that reliably supports the work.

Minimal skill

my-skill/
└── SKILL.md

Reference-backed skill

my-skill/
├── SKILL.md
├── project.skill.template.md
└── references/

Operational skill

my-skill/
├── SKILL.md
├── project.skill.template.md
├── references/
├── scripts/
└── tests/

Resilient operational skill

my-skill/
├── SKILL.md
├── project.skill.template.md
├── references/
├── scripts/
├── tests/
└── self-healing/

Read references/skill-architecture-levels.md before deciding how much structure to add.

Authoring Phases

You must complete each phase before moving on.

Phase 1: Define the boundary

Decide:

• what problem the skill solves
• what belongs in the reusable global skill
• what must remain project-local
• whether local context actually matters

If local commands, paths, outputs, or constraints vary by project, plan for project.skill.template.md.

Phase 2: Define trigger and routing

Write the frontmatter and top of SKILL.md.

Requirements:

• description says when to use the skill
• SKILL.md routes the agent to project.skill.md early when local context matters
• SKILL.md tells the agent which references/scripts matter at which step

Read references/description-writing.md before finalizing the description.

Phase 3: Add only justified structure

Add references, scripts, tests, and self-healing only when earned.

Use these references:

• references/script-test-conventions.md before shipping scripts
• references/self-healing-rules.md before adding self-healing
• references/skill-testing.md before deciding what to validate

Phase 4: Validate fresh-agent usability

Before calling the skill complete, test whether a fresh agent could:

• identify when to use the skill
• find the right local context file
• choose the right reference or script
• know what completion means

Read references/behavioral-validation-checklist.md.

Phase 5: Apply the completion gate

Do not claim the skill is complete until it passes the completion gate.

Read references/completion-gate.md.

Routing Map

Use this map while authoring:

• Need to define project-local context? → references/project-skill-context.md
• Need to choose architecture level? → references/skill-architecture-levels.md
• Need to write a better trigger description? → references/description-writing.md
• Need to add or test scripts? → references/script-test-conventions.md
• Need to decide whether healing is allowed? → references/self-healing-rules.md
• Need to validate fresh-agent usability? → references/behavioral-validation-checklist.md
• Need to decide if the skill is complete? → references/completion-gate.md
• Need general workflow or output guidance? → references/workflows.md, references/output-patterns.md

Scripts in This Repo

Use the shipped scripts when they reduce repeated, deterministic work:

• scripts/quick_validate.py — fast validation of frontmatter and core structural promises

If you find yourself manually re-checking the same structural conditions repeatedly, prefer strengthening this validator rather than rewriting the checks ad hoc.

Reference Skill

See reference-skills/release-notes-generator/ for a canonical reference skill authored using this framework.

Use it as a model implementation of:

• a reusable global skill
• a shipped project.skill.template.md
• references routed from SKILL.md
• a deterministic script with a paired test
• narrow self-healing

It is a specimen of the framework, not a substitute for the framework.

Red Flags — STOP

Stop and correct course if you are thinking:

• "I’ll just put this command/path in SKILL.md"
• "The agent can infer the local commands"
• "This script is too small to test"
• "I’ll add the test later"
• "This self-healing is probably safe"
• "The example will clarify the missing instructions"
• "A fresh agent will figure it out"
• "Close enough"

All of these usually mean you are about to violate one of the iron laws.

Common Rationalizations

Excuse	Reality
"It’s faster to put the path in SKILL.md"	That contaminates the global skill with local assumptions. Use project.skill.md.
"Agents can infer the local commands"	Guessing local commands is exactly what project-local context is for.
"This script is simple, it doesn’t need a test"	If it is worth shipping, it is usually worth validating.
"Self-healing can just fix a bunch of stuff"	Broad auto-fixes are risk, not resilience.
"The worked example will show the pattern"	The skill itself must be usable without depending on an example.
"The structure looks right, so the skill is done"	Organization alone does not prove fresh-agent usability.

Completion Gate

Before claiming a skill is complete, verify all of these:

• the description says when to use the skill
• the global skill contains no project-specific commands, paths, or constraints
• SKILL.md routes the agent to project.skill.md early when local context matters
• references are clearly named and linked from SKILL.md
• shipped scripts are justified and paired with tests, or explicitly exempted with a reason
• self-healing is narrow and safe
• a fresh agent could use the skill without guessing critical facts

Bottom Line

A better skill is not just more elaborate.

A better skill:

• stays reusable at the global level
• pushes local facts into project.skill.md
• routes the agent clearly through references and scripts
• validates what it ships
• resists rationalization
• is complete only when a fresh agent could use it without guessing