Skill

Skill Best Practices

Write Skills that activate at the right time, spend context carefully, and produce repeatable results.

Write a trigger-focused description

The description is the catalog entry agents see before activation. It should describe the user intent, task shape, and boundaries, not just the topic.

# Weak
description: Helps with PDFs.

# Stronger
description: Extract text from PDFs, split or merge pages, fill forms, and validate generated PDF outputs.

Spend context wisely

Once activated, every word in SKILL.md competes with the user's request, project context, tool results, and other active instructions. Put the high-value procedure in the main file and move rare details to references.

Keep

Activation rules, workflow, success criteria, defaults, and critical gotchas.

Move out

Long API references, exhaustive examples, style guides, schemas, and large templates.

Load on demand

Tell the agent when to read each reference, script, or asset.

Favor procedures over declarations

Agents follow operational steps better than broad principles. Replace "be careful with migrations" with a checklist the agent can execute.

Inspect inputs

List the files, fields, or signals the agent must examine before acting.

Make changes

Describe the allowed actions and defaults for uncertain cases.

Validate

Specify tests, assertions, review checks, or output criteria.

Use templates for output

When the final answer has a required format, include a concrete template. Agents pattern-match against examples more reliably than prose descriptions.

## Final report

Summary:
- ...

Findings:
| Severity | Issue | Evidence | Recommendation |
| --- | --- | --- | --- |

Open questions:
- ...

Bundle scripts carefully

Scripts are useful for deterministic work such as parsing files, extracting data, validating outputs, or generating reports. Design them for agents, not interactive humans.

No promptsAccept flags and fail with clear messages instead of waiting for input.

Help textSupport --help so agents can inspect usage quickly.

Structured outputPrefer JSON, CSV, or delimited lines over visually aligned terminal tables.

PrerequisitesDocument runtime requirements in SKILL.md or compatibility metadata.