Menü
Create, update, or review Agent Skill directories and SKILL.md files for valid frontmatter, structure, portability, progressive disclosure, and validation readiness.
| name | author-agent-skill |
| description | Create, update, or review Agent Skill directories and SKILL.md files for valid frontmatter, structure, portability, progressive disclosure, and validation readiness. |
| metadata | {"version":"1.1.1"} |
Use this skill when creating, updating, or reviewing an Agent Skill. The goal is to keep each skill valid, easy for agents to discover, portable across projects, and concise enough to load only the guidance needed for the task.
The expected outcome is a skill directory that can be copied into a compatible agent environment, discovered from its metadata, followed without hidden local context, and validated or reviewed with clear evidence before handoff.
Use this skill when:
SKILL.mdscripts/, references/, or assets/Define the task the skill helps an agent perform. Prefer a focused workflow over a broad collection of unrelated guidance.
Confirm:
Use a short, descriptive, kebab-case directory name. The frontmatter name must
match the parent directory exactly.
The name must:
Prefer action-oriented names such as write-adr, run-local-quality-gate, or
author-agent-skill.
SKILL.md must start on the first line with YAML frontmatter. Include name,
description, and metadata.version.
Use this minimal shape:
---
name: skill-name
description: Brief description of what the skill does and when to use it.
metadata:
version: "1.0.0"
---
The description should explain both:
Keep the description non-empty, specific, and no longer than 1024 characters.
Use metadata.version to track skill revisions. Increase the version whenever
the skill behavior, instructions, metadata, assets, scripts, or references
change. Prefer semantic versioning:
Add optional fields only when they are useful and supported by the skill format.
For this skill format, include metadata.version; additional metadata keys remain
optional.
Supported optional fields are:
licensecompatibilitymetadataallowed-toolsKeep optional fields concise and format them according to the target Agent Skills
specification. Use compatibility only for meaningful environment requirements,
additional metadata keys only for useful key-value metadata, and
allowed-tools only when tool pre-approval is supported by the target
environment.
Do not add custom frontmatter fields unless the target skill system or repository tooling explicitly requires them.
After frontmatter, include one top-level heading that names the skill in a human-readable form.
A practical structure is:
---
name: skill-name
description: Brief description of what the skill does and when to use it.
metadata:
version: "1.0.0"
---
# Skill Name
Short explanation of when and why to use the skill.
## Steps
1. First action
2. Second action
3. Validation or handoff action
Use section headings only when they improve navigation. Use ## Steps for a
repeatable workflow.
Keep the main SKILL.md concise and self-contained. Move detailed or rarely used
material into optional directories when needed:
scripts/ for executable helper codereferences/ for focused supporting documentationassets/ for templates, static files, schemas, or examplesOnly add these directories when they reduce main-file complexity or provide content an agent can load on demand. Do not create empty optional directories or split short guidance just to mirror the directory convention.
When referencing supporting files, use relative paths from the skill root. Prefer simple one-level references where practical.
For reusable skills, avoid local repository paths, private project names, local usernames, or commands that only make sense in one repository.
Prefer placeholders such as:
<package_name><app_name><repo_name><python_version>If a section must be repository-specific, label it clearly so readers can tell it is not part of the portable guidance.
Use plain Markdown that improves navigation and correctness. Avoid emojis, decorative separators, banners, ornamental callouts, and visual-only formatting.
Prefer:
Run the repository's skill or documentation validation command when available. If the target environment provides an Agent Skills validator, use it for the changed skill directory.
When no validator is available, manually check the review checklist below.
In the handoff, report what changed, which skill directory was validated, which commands passed, and any validation that was skipped with the reason.
SKILL.md exists in the skill directoryname, description, and metadata.versionname matches the parent directory exactlyname is valid kebab-casedescription explains both what the skill does and when to use itmetadata.version is present, quoted, and increased when the skill changedscripts/, references/, and assets/ content is necessary,
non-empty, and referenced clearly when relevantExtracts what the user actually wants instead of what they think they should want. Achieves this through one-question-at-a-time interview until ~95% confidence about the underlying intent. Use when an ask is underspecified ("build me X" without "for whom" or "why now"), when the user explicitly invokes ("interview me", "grill me", "are we sure?", "stress-test my thinking"), or when you catch yourself silently filling in ambiguous requirements before any plan, spec, or code exists.
Discover and run the project's local formatting, linting, static analysis, test, and build checks before handoff.
Update project-facing documentation after a user-visible behavior, configuration, operation, or workflow change.
Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.
Add logs, metrics, traces, profiling, or operational notes for meaningful workflows without unsupported performance claims.
Design stable APIs, module contracts, schemas, component boundaries, command interfaces, or other public integration surfaces that are predictable, documented, and hard to misuse.