Effective Agent Skills

Effective Agent Skills

1. What agent skills are

An Agent Skill is a folder containing a SKILL.md file (YAML frontmatter + markdown instructions), plus optional subfolders for scripts, references, and assets that the agent loads on demand.

Copy code
my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code (CLIs, validators, helpers)
├── references/       # Optional: detailed docs loaded only when needed
└── assets/           # Optional: templates, fonts, static files

Agent Skills (agentskills.io) is an open standard. The folder and SKILL.md format are portable; optional behavior such as invocation control can be client-specific.

2. Why use skills

Skills package procedural knowledge and context for reuse:

• Context efficiency — instructions load only when relevant
• Repeatability — multi-step procedures become auditable workflows
• Composability — multiple skills combine at runtime per task
• Portability — same files work across vendors and surfaces

3. How they work — progressive disclosure

Three levels of loading:

Level 1 — Discovery (~100 tokens per skill, always in context): The agent sees name + description first to decide whether the skill applies.

Level 2 — Activation (<5,000 tokens, loaded on match): When the request matches, the agent reads the full SKILL.md body.

Level 3 — Execution (unbounded, on demand): The agent reads references (references/foo.md) or runs scripts (scripts/validate.py) as needed. Running a script need not load its source into context.

Bundled files consume context only when their contents are loaded.

4. SKILL.md anatomy

markdownCopy code
---
name: skill-name
description: What this skill does AND when to use it. Include trigger phrases the user will say.
---

# Skill Name

## Quick start
[Minimal working example]

## Workflow
[Step-by-step procedure with checklists]

## Output format
[What the user/agent should expect back]

## Advanced
[Link to references/ for rarely-needed detail]

Frontmatter constraints:

• name is lowercase, hyphens only, 1–64 chars, exactly matches the parent folder name
• Avoid < and > in frontmatter (they can inject into the system prompt)
• Invalid YAML silently prevents loading
• Never put : (colon + space) inside an unquoted description — strict YAML parsers (e.g. Pi's) reject it as a nested mapping ("Nested mappings are not allowed in compact mappings"), even though lenient parsers (Claude Code) accept it. If the text needs a mid-sentence colon, single-quote the whole value and double any inner apostrophes: description: 'Differentiator: finds gaps in the user''s knowledge.'

Manual-only invocation is client-specific

disable-model-invocation: true is not part of the core Agent Skills specification. It is a client extension supported by Claude Code and VS Code/Copilot. In those clients, put it in SKILL.md frontmatter to prevent automatic invocation while keeping explicit invocation available.

OpenAI Codex uses a separate file at agents/openai.yaml inside the skill:

yamlCopy code
policy:
  allow_implicit_invocation: false

For a manual-only skill shared across Claude Code, VS Code/Copilot, and Codex, include both configurations. Never assume a client-specific frontmatter field works in every Agent Skills implementation; verify each target client's documentation and test implicit invocation in each runtime.

5. Two design philosophies

Pattern A — Capability primitives (tool wrappers)

The skill is a thin wrapper over a deterministic CLI or script. Logic lives in code. SKILL.md teaches the agent how to invoke it.

• Adds: new capabilities (search, email, browser, API access)
• Reliability via: shell tools, not prompts
• Typical length: 30–80 lines, mostly command examples
• Use when: the bottleneck is "the agent can't do X"

Pattern B — Process primitives (cognitive disciplines)

The skill encodes a methodology the agent should follow. Pure prompt engineering — no scripts needed.

• Adds: structured workflows (TDD, code review, design alignment, debugging loops)
• Reliability via: explicit procedure, checklists, validation loops
• Use when: the bottleneck is "the agent's output quality or process is bad"

6. How to write effective skills — do this

Description as routing contract

The description is the only thing the agent sees before deciding to load the skill. If your skill doesn't trigger, the description is wrong 95% of the time, not the body.

Include three elements:

1. What the skill does (one phrase)
2. When to use it (trigger phrases, situations)
3. Differentiator vs related skills (prevents routing conflicts)

Pattern: "X via Y. Use for [situations]. [Differentiator: no Z required / faster than W / handles edge case V]."

Never summarize the full workflow in the description. If the description contains a step-by-step summary of how the skill works, the agent tends to follow that summary and skip loading the body. Describe what and when, never how. The description answers "should I open this skill now?" — not "what are the steps?"

Keep SKILL.md lean

• Beyond a certain length, you're usually encoding logic that should be in a script or referenced file

Bash-first, prose-second

Prefer concrete command examples with inline comments to lengthy prose.

Push determinism into code

Anything fragile, repetitive, or where variation is a bug → script. Use markdown only for tasks requiring judgment.

Match strictness to task fragility (degrees of freedom)

Scale instruction rigidity to how costly a wrong move is:

• Loose natural-language heuristics when many approaches are valid (e.g. code review).
• Pseudocode or templates when there's a preferred pattern but variation is acceptable (e.g. report format).
• Exact scripts and strict step lists when the workflow is fragile, error-prone, or consistency-critical (e.g. migrations, document patching).

Build validation loops

State a verify → fix → re-verify loop explicitly.

• Document skills: visual QA pass before delivery
• Code skills: tests pass + zero type errors before completion
• Data skills: schema validation before output

State-check before action

Don't assume setup is done. Instruct the agent to verify state, then branch:

Copy code
First check if X is configured: [command]
If not, walk the user through setup: [steps]

Just-in-time loading with explicit pointers

Tell the agent exactly when to read each referenced file:

Copy code
For standard cases, follow the steps below.
For [specific edge case], read references/edge-cases.md first.

Keep references one level deep

Link references directly from SKILL.md; nested chains risk partial reads and missed instructions. Add a table of contents to references longer than 100 lines.

Document output formats

Show structured output examples so other tools can parse them reliably.

Defer to --help for completeness

Show common operations in SKILL.md; use tool --help for the rest.

Compose primitives, don't bundle workflows

Keep each skill to one capability or discipline; compose focused skills for larger workflows.

Cite established principles when applicable

Name the source of established methods such as TDD, DDD, or red-green-refactor so agents and users can verify the intended approach.

Persistent artifacts for cross-session memory

Skills can keep durable context in repo files (CONTEXT.md, ADRs, decision logs) for future sessions.

7. What not to do — anti-patterns

Don't re-teach what the model already knows

Provide context the model lacks. Skip basic Python or Git tutorials; make every paragraph earn its place.

Don't include human-facing docs

No README.md, no CHANGELOG.md, no INSTALLATION_GUIDE.md inside the skill folder. Skills are for agents.

Don't write vague descriptions

• Bad: "A helpful skill for documents"
• Good: "Fill PDF form fields, extract form data, flatten completed PDFs. Use when the user mentions PDF forms, fillable forms, or programmatic field population."

Don't bundle library code

If you need a parsing library, install via npm/pip. Don't paste source into the skill.

Don't write monolithic mega-skills

Split skills that bundle design, planning, implementation, testing, and deployment.

Don't assume the agent will infer

Be explicit about every step that matters.

• Bad: "Then deploy it."
• Good: "Run npm run deploy:staging and wait for HTTP 200 from /healthz before reporting success."

Don't write style-only variants

A skill that just changes tone or formatting belongs in user preferences or a system prompt, not a skill.

Don't ignore failure modes

For each fallible step, describe how to recognize failure and what to do.

Don't include time-sensitive information

"As of Q4 2024..." rots fast. Fetch live data via script or omit.

Don't use absolute paths

Always relative. Forward slashes regardless of OS. Use runtime placeholders for skill-directory references.

Don't trust unfamiliar skills

Skills can run code, steer behavior, and leak data. Audit scripts, references, names, and access scope before use; follow the security checklist below.

8. Authoring workflow

1. Identify the gap. Run your agent on real tasks. Where does it consistently fail or need re-prompting? That's a skill candidate.
2. Decide the pattern. Capability primitive (need new tools) or process primitive (need better methodology)?
3. Draft the description first. What + when + differentiator. Read it back: would the agent know when to fire it?
4. Write the smallest body that works. Add only when testing reveals gaps.
5. Move detail to references/ once SKILL.md grows too long.
6. Test triggering. Ask the agent something the skill should handle without invoking it explicitly. If it doesn't fire, fix the description.
7. Test execution. Invoke explicitly. If output is wrong, fix the body.
8. Adversarial test. Have another LLM ask: "What edge cases break this skill?" Patch the gaps.
9. Version control. Treat skills as code. Tag, branch, review.

9. Testing and debugging

• "Which skill did you use?" — ask the agent post-task. Fastest routing debug.
• Routing fails → description problem. Add specific trigger phrases.
• Execution fails → body problem. Add explicit steps, examples, or validation.
• Skills snapshot at session start. Edits during a session require a restart.
• Test against the weakest model you'll deploy on. Stronger models forgive vague skills; weaker models expose them.
• Run an eval suite. A handful of representative prompts that should and shouldn't trigger the skill, with expected outputs.

10. Composition

Agents can combine skills for one task:

• One skill = one concern. Resist bundling.
• Define interfaces between skills. If skill A produces artifacts that skill B consumes, document the shape.
• Share repo-level context. Files such as AGENTS.md, CONTEXT.md, or settings.json can coordinate multiple skills without explicit handoffs.
• Connect skills into useful workflows such as align → spec → build → verify → refactor.

11. Security checklist

Before installing any third-party skill:

• Read every file in the folder
• Audit scripts/ for outbound network calls, file access outside expected scope, command execution
• Check references for prompt injection ("ignore previous instructions...")
• Verify the skill name isn't typosquatting a popular one
• Run in a sandboxed environment first
• Pin to a specific version/commit, not latest

12. Ship checklist

Before publishing a skill:

• Frontmatter name matches folder name
• Description includes what + when + differentiator
• Description includes likely user trigger phrases
• No human-facing docs inside the skill folder
• No time-sensitive information
• Relative paths only
• State-check before action where applicable
• Validation loop documented
• Output format documented if relevant
• Tested with weak and strong models
• Tested for both correct triggering and correct execution
• Skill does one thing
• Composes cleanly with related skills
• Version controlled