/agent-skill-author

name: agent-skill-author
description: Use this skill when the user wants to author, design, scope, or refine an Agent Skill (a SKILL.md file). Trigger phrases include "build a new skill", "design an agent skill", "scope a SKILL.md", "how should I structure this skill", "write a skill for X", "my skill isn't working well", or any request to improve an existing SKILL.md. Walks the user through an empirical, test-first process — probe the agent for real failures, design only for genuine knowledge gaps, iterate against runnable examples, and verify across models.
license: MathWorks BSD-3-Clause (see LICENSE)
metadata:
  author: MathWorks
  version: "1.0"

Authoring an Agent Skill

You are helping a user author or improve an Agent Skill. Skills are markdown files an agent loads to handle domain-specific work it would otherwise get wrong. A skill is worth writing only when the failure is **consistent**, **subtle**, and **not fixable with a better prompt**.

Follow the five-stage process below. Do not skip stages.

Stage 1: Probe for real failures

Before designing anything, find out what the agent actually gets wrong.

• Ask the user for 5 to 10 representative prompts that real users would send.
• For each prompt, run the agent **with no skill loaded** and collect the generated

code or output.

• Run the output against real data, real APIs, or a real session. Note exactly what

fails: missing functions, wrong superclass names, swallowed errors, wrong default arguments, hallucinated APIs.

• Categorize each failure: prompt-fixable, model-fixable (try another model), or

knowledge-gap.

Only knowledge-gap failures justify a skill. If a better prompt fixes it, use a better prompt.

Stage 2: Identify the real knowledge gaps

Group the failures from Stage 1 by root cause. Common categories:

• **Pattern-matched from another language.** Agent invents a function because the

same idiom exists in Python or Java (the blog's example: an `ormdelete()` that doesn't exist in MATLAB).

• **Wrong namespace or class path.** Agent gets the verb right but the path wrong

(`database.orm.Mappable` vs. `database.orm.mixin.Mappable`).

• **Missing guard or precondition.** Agent omits a check the runtime requires (a

`nargin == 0` guard for objects an ORM creates empty).

• **Wrong defaults or argument order.** Agent picks plausible-but-wrong defaults the

documentation doesn't make obvious.

• **Drift between major API versions.** Agent uses an older or newer signature than

the one the user actually has.

For each category, write down the **specific rule** the skill needs to teach. One rule per failure.

Stage 3: Design the skill

Apply these structural rules. The agent may not read your whole skill, so structure matters.

1. **Frontmatter description is a trigger spec, not a summary.** It should describe when to invoke the skill, with concrete trigger phrases the agent will match on. The agent reads this to decide whether to load you. Avoid `: ` (colon followed by space) inside the description value — strict YAML parsers will read it as a nested mapping and fail to load the skill. Use an em dash or comma instead. 2. **Most critical rules first.** Put the rules that fix the most failures at the top of the body. Don't bury the load-bearing rule. 3. **Progressive disclosure.** Common cases up front. Edge cases, exceptions, and variant APIs in later sections or in `references/`. 4. **One topic per section.** Use H2 (`##`) per topic. Consistent section order across your skill family makes it predictable for the agent. 5. **Show, don't tell.** Where a rule is about syntax, include a 2-to-5 line code example with the failing pattern and the corrected pattern side by side. 6. **Leave out what the agent gets right.** If your probing showed the agent handles `addComponent` correctly, don't document `addComponent`. Skills are compensators for failure, not API reference. 7. **Name common pitfalls explicitly.** A "Common pitfalls" section near the bottom for known gotchas the user might hit even with the skill loaded.

Suggested section order:

## When this skill applies            (1-2 paragraphs)
## Core rules                          (the load-bearing rules, in priority order)
## API patterns                        (code examples per category)
## Common pitfalls                     (gotchas, including known limitations)
## See also                            (links to references/ and related skills)

Use the template at [`templates/SKILL-template.md`](templates/SKILL-template.md) as a starting point.

Stage 4: Iterate against runnable examples

Run the same Stage 1 prompts **with the skill loaded** and the failures should drop.

• For each remaining failure, decide: tighten the skill, accept the failure (with a

documented pitfall), or escalate (the failure isn't a skill problem).

• Test across at least two models if the user expects cross-model use. Phrasing

that works for one model can be ignored by another.

• Read every generated output. Don't trust the model to self-report success.

Keep a short test log: prompt, model, pre-skill result, post-skill result. The log is the evidence that the skill works; without it, you're guessing.

Stage 5: Maintain

Skills aren't done. Models change, APIs change, and yesterday's failure becomes today's strength (and vice versa).

• Revisit the test log when the user's product version changes, when a new model

ships, or when users report fresh failures.

• Remove rules the agent now handles correctly without help. A bloated skill loses

attention budget.

• When a rule needs more depth than fits, move it to `references/` and link from

the main body.

Anti-patterns

• **API encyclopedia.** Writing down everything the API does. Skills are not docs.
• **Theoretical gaps.** Writing rules for failures you assumed without ever

running the agent.

• **Tone or style guidance only.** Telling the agent to "be helpf