Agent Skills Best Practices

These are the habits that keep a packaged AWS SDK skill useful instead of becoming stale, over-broad advice nobody trusts.

Walk the list once now, then treat it as a review checklist whenever you write a new skill or revisit an old one.

How to Use This List

• Each item is a rule stated positively, with a one-line rationale.
• Groups run roughly in the order you would apply them: scope the skill first, structure it, reference existing conventions, keep code treatment consistent, then maintain it over time.
• Check the boxes against a skill document you already have as a quick audit.
• Revisit this list whenever a new skill starts feeling unreliable or a reviewer stops trusting one's output.

A - Scope & Triggers

• Scope one task per skill. A skill covering "AWS help" in general has no checkable output; "scaffold a new service client" does.
• Write triggers the way requests actually sound. Phrase triggers like real asks ("add DynamoDB to this project"), not like a formal spec.
• Split ambiguity into separate skills. If two tasks could plausibly match one trigger, they are two skills, not one broad one.
• Define the expected output up front. A file, a diff, or a checklist - name the shape before writing the procedure.
• Reject "helps with everything" scope creep. The moment a skill tries to cover a whole domain, it collapses back into generic advice an assistant already has.

B - Content & Structure

• Number the procedure. A flat numbered list is easier for an assistant (and a person) to follow exactly than prose instructions.
• Include one worked example. An abstract procedure without a concrete example invites inconsistent interpretation.
• State what "done" looks like. End the procedure with a verification step - a smoke test, a checklist line - not just the last action.
• Keep the skill short. A skill that needs several pages to state is a sign the scope is still too broad.
• Name the skill for its task, not its topic. service-client-scaffold is checkable; aws-help is not.

C - Referencing Existing Conventions

• Defer to mechanics that are already documented. A credential-setup skill should point at the credential provider chain, not re-explain it.
• Never invent new AWS mechanics inside a skill. A skill packages a procedure around existing APIs and patterns; it does not create new ones.
• Link the skill to the pages it depends on. Make the dependency explicit so a reader (or a future editor) can tell what would break the skill.
• Keep security-sensitive logic in one place. Credential and IAM conventions should live in one reference, referenced by every skill that touches auth.
• Treat a skill as a thin wrapper, not a rulebook. If a skill is teaching mechanics from scratch, that content likely belongs on a different page.

D - Code & Language Neutrality

• Keep the skill's own document language-neutral. A skill's instructions file (its markdown/YAML) is a plain fence, not a <CodeGroup>.
• Dual-language only what the skill produces or checks. If the skill outputs or reviews real SDK code, show both boto3 and AWS SDK v3 for that output.
• Match real, current APIs in every example. An illustrative snippet inside a skill should call the same operations this site documents elsewhere, not an invented shorthand.
• Prefer a checklist output where judgment is involved. A cost-review skill's output is a pass/flag line per check, not a rewritten diff.
• Mark borderline judgment calls explicitly. A skill that only reports flags, never explicit passes, looks incomplete even when it ran correctly.

E - Maintenance & Review

• Give every skill an owner. An unowned skill has nobody responsible for noticing when it goes stale.
• Review a skill when its underlying pattern changes. A new batching helper or paginator API should trigger an update to any skill that assumed the old one.
• Keep a short review log. A couple of dated lines showing when a skill was written and last checked makes staleness visible instead of silent.
• Retire skills that no longer match team practice. An outdated skill that still looks authoritative is worse than no skill at all.
• Test a skill's output the same way you would test code. Run it once against a real task before trusting it in daily use.

FAQs

Related

• What an "Agent Skill" Means for AWS SDK Work - the concept these practices apply to.
• A Cost-Review Skill for SDK-Heavy PRs - a judgment-heavy skill that puts group D's rules to work.
• A Service-Client Scaffolding Skill - a narrowly-scoped skill that puts group A and B's rules to work.
• Agent Skills Basics - worked examples of the shapes described here.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).