Skill Authoring Standards

Provides: Agent Skills specification rules, scope and structure decisions, description writing for reliable triggering, and a review checklist.

Quick Reference

Golden Rule: Put trigger guidance in description; the body loads only after activation

Create a skill for: repeatable workflows, domain expertise, fragile procedures, bundled tools and resources

Do not create one for: always-on rules, one-off answers, generic best practice

Keep SKILL.md focused. Move conditional detail to references/ and state exactly when to read each file.

Never: add README.md or other auxiliary docs to a skill package unless asked

When to Create a Skill

Create a skill when the agent needs:

• A repeated multi-step workflow.
• Domain-specific knowledge, schemas, APIs, policies, or conventions.
• A fragile sequence where order matters.
• Bundled scripts, references, templates, or assets.
• Instructions too long or too conditional for always-on context files.

Do not create a skill when:

• The instruction should always apply. Use project or user instructions instead.
• The task is a one-off answer or a simple preference.
• The content is generic best practice with no non-obvious procedure.
• An existing skill already covers the workflow. Extend that one instead.

Package Structure

The portable baseline is a directory containing SKILL.md:

skill-name/
└── SKILL.md

Add optional directories only when they carry weight:

skill-name/
├── SKILL.md
├── scripts/       # deterministic or repeated logic the agent should execute
├── references/    # detailed docs loaded only when relevant
└── assets/        # templates or files used to produce outputs

Do not add auxiliary docs such as README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or QUICK_REFERENCE.md unless the user asks. A skill package should contain only what helps another agent do the task.

Frontmatter

Portable baseline:

---
name: skill-name
description: Clear description of what the skill does and when to use it.
---

Keep frontmatter minimal. Add compatibility only for real environment or client requirements, and metadata only when the keys add operational value. Omit license unless the user wants package metadata. Keep long descriptions on one line unless YAML syntax requires otherwise.

Name rules:

• Lowercase letters, digits, and hyphens only.
• At most 64 characters.
• No leading, trailing, or consecutive hyphens.
• Must match the directory name, even where a client is lenient about it.
• Prefer short verb-led or domain-led names.

Good: code-review, gh-address-comments, standards-skill-authoring, terraform-module-review.

Bad: CodeReview, -code-review, code--review, company/internal/review.

Description Writing

The description field is the primary trigger mechanism. Write it as an instruction to the agent, not as marketing copy.

A good description does three jobs:

1. Names the user intents that should trigger it, in words a user would actually type.
2. Adds an "even if" clause for small-looking requests and cases where the user does not name the domain.
3. Names the neighboring skill to use instead where false positives are likely.

Lead with the trigger, not a summary of the skill's contents. Agents see only name and description before deciding to load a skill, and they skip skills whenever a task looks self-contained. Pushy, intent-focused phrasing counters that tendency; a neutral sentence such as "Use this skill when writing Go code" does not.

Weak, because it only restates the category and gives the agent no reason to act:

description: Use this skill when writing, refactoring, or reviewing code in any language. Provides the language-neutral maintainability baseline.

Strong, because it names concrete intents and covers the small request that would otherwise slip through:

description: Use this skill whenever you write, refactor, or review production code in any language, including small edits and bug fixes, even when the user only asks for a quick change. Provides the language-neutral maintainability baseline for testable boundaries, cohesive units, explicit dependencies, clear errors, and minimal change scope. Load the language-specific standards skill alongside it.

Avoid:

description: Helps write skills.

Keep all trigger information in the description. A body section named "When to use this skill" is close to useless, because the agent will not read it until the skill has already triggered.

In the body, skip openers that only repeat the description. Start with scope, application boundaries, or the first workflow step.

Stay under 1,024 characters.

Authoring Workflow

1. Capture intent

Start from concrete use cases. Ask only the highest-value questions:

• What should this skill let the agent do?
• What user prompts should trigger it?
• What output should the agent produce?
• What corrections has the user repeated before?
• Does the task need scripts, references, or assets?

When extracting a skill from an existing conversation, mine the conversation before asking for more detail. Look for steps that worked, user corrections, input and output formats, tools, commands, APIs, file paths, gotchas, and verification steps.

2. Choose the scope

Make the skill one coherent unit of work.

Good scope: github-pr-review, billing-query-analysis, run-local-app.

Too narrow: check-one-header, run-one-command.

Too broad: engineering, all-company-workflows, everything-about-cloud.

If one task needs several unrelated procedures, split it into separate skills.

3. Plan resources

Decide what belongs in SKILL.md versus supporting files before writing.

4. Write instructions

Use imperative, task-oriented instructions:

1. Inspect the repository's existing release format.
1. Draft release notes from merged PRs.
1. Propose a semantic version bump with reasoning.
1. Provide a copy-pasteable `gh release create` command.

Not:

You are an expert release manager. Be careful and follow best practices.

Explain why when it improves judgment: "Read the existing changelog before drafting new notes, because this keeps tone, section ordering, and version terminology consistent."

5. Add examples and gotchas

Use examples where they remove ambiguity:

Input: Added JWT login and logout endpoints.
Output: `feat(auth): add JWT login and logout`

Gotchas correct likely model assumptions:

- The `users` table uses soft deletes. Queries must include `deleted_at IS NULL`.
- The health endpoint only checks the web process. Use `/ready` for database readiness.
- The release branch is `stable`, not `main`.

Add a gotcha whenever the user has to correct the agent about the same thing twice.

6. Add validation

Every skill should tell the agent how to know it is done:

## Checklist

- [ ] Run `npm test` if package files changed.
- [ ] Check generated JSON with `jq`.
- [ ] Confirm all required fields are present.
- [ ] Report final file paths and any skipped checks.

For destructive or fragile tasks, use plan, validate, execute: draft the plan, validate it against the source of truth, show the user what will change, execute only after approval, then verify the result.

Progressive Disclosure

Design the package so the agent loads only what it needs.

• Keep SKILL.md under 500 lines where practical.
• Keep each reference file focused, and link it from SKILL.md.
• State the condition for reading each reference.
• Avoid nested reference chains.
• Do not duplicate content between SKILL.md and a reference.

A resource map earns its place by being specific:

- Read `references/aws.md` only for AWS deployments.
- Read `references/gcp.md` only for GCP deployments.
- Run `scripts/validate-config.sh` after editing deployment config.

Not: "See references for more information."

Scripts in Skills

Use a script when repeated code or deterministic validation saves time or prevents errors.

• Accept input through flags, files, environment variables, or stdin.
• Never prompt interactively.
• Provide --help.
• Send structured data to stdout and diagnostics to stderr.
• Use safe defaults, and support --dry-run for destructive operations.
• Return meaningful exit codes.
• Pin dependencies where practical, and prefer self-contained scripts.

Tell the agent when to run it and what to do on failure: "Run bash scripts/validate.sh path/to/config.json before finalizing. If validation fails, fix the reported issue and run it again."

Checklist

Before handing back a skill:

• The skill has a clear, reusable purpose, and its behavior matches the user's intent
• Frontmatter parses as valid YAML
• name is strict lowercase hyphen-case and matches the directory
• description is specific, trigger-oriented, and under 1,024 characters
• description names concrete user intents, includes an "even if" clause, and names the neighboring skill for near misses
• Trigger guidance is not hidden in the body
• Frontmatter is minimal; extra fields are justified
• Instructions are concise and imperative, with generic advice removed
• Prose is not hard-wrapped mid-sentence
• Gotchas capture non-obvious mistakes, and examples are realistic
• A validation or checklist section is present
• Supporting files are necessary, referenced, and have stated read conditions
• Scripts are non-interactive and documented
• Destructive actions require confirmation or a dry run
• No secrets are requested in chat
• Client-specific compatibility assumptions are documented in compatibility
• The skill was tested with realistic prompts, or reviewed against them

See also

• Read cross-client compatibility when targeting a specific client such as Pi, OpenCode, Codex, Claude Code, Gemini CLI, VS Code, GitHub Copilot, or Goose.
• Read testing and evaluation when the skill triggers too often or too rarely, or when building eval cases.
• Load standards-markdown for the Markdown formatting rules the file itself must follow.
• Load standards-documentation when the skill ships user-facing documentation.