Menu
Create well-formatted Agent Skills following the agentskills.io specification. Use when writing, authoring, scaffolding, or reviewing a new skill, SKILL.md file, or skill directory structure.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Architecture decisions: layering, design patterns, microservices trade-offs, and domain-driven design
Python architecture: PEP-8, type hints, clean layering, dependency injection, and testing strategy
General code review process: priority ordering, what to block on, how to give actionable feedback
Python data science: notebook structure, data validation, reproducibility, and model documentation
Git workflow: branch naming, conventional commits, PR conventions, and merge strategies
TypeScript refactoring: SOLID principles, DRY, type safety improvements, and eliminating code smells
| name | skill-authoring-general |
| description | Create well-formatted Agent Skills following the agentskills.io specification. Use when writing, authoring, scaffolding, or reviewing a new skill, SKILL.md file, or skill directory structure. |
This skill guides creation of valid, well-structured Agent Skills following the agentskills.io specification.
Every skill is a directory named after the skill itself:
skill-name/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable scripts
├── references/ # Optional: supplementary documentation
└── assets/ # Optional: templates, static resources
The directory name must exactly match the name field in SKILL.md.
SKILL.md must begin with YAML frontmatter, followed by Markdown instructions.
| Field | Rules |
|---|---|
name | 1–64 chars. Lowercase a-z, digits, hyphens only. No leading/trailing/consecutive hyphens. Must match directory name. |
description | 1–1024 chars. Describe what it does and when to use it. Include keywords agents use to identify the task. |
| Field | Notes |
|---|---|
license | License name or path to bundled license file. |
compatibility | 1–500 chars. Only include if the skill has specific environment requirements (tools, network, OS, product). |
metadata | Arbitrary key-value map for extra properties (version, team, links, etc.). |
allowed-tools | Space-delimited pre-approved tools, e.g. Bash(git:*) Read. Experimental. |
---
name: my-skill
description: Does X and Y. Use when the user asks about Z.
---
# My Skill
Instructions here.
---
name: my-skill
description: Extracts and transforms X. Use when working with X files or when the user mentions Y or Z.
license: MIT
compatibility: Requires python3 and internet access
metadata:
version: "1.0"
allowed-tools: Bash(python3:*) Read Write
---
# My Skill
Brief overview.
## Steps
1. Step one
2. Step two
## Examples
Input: ...
Output: ...
## Edge Cases
- Handle ...
Body content (after frontmatter) has no format restrictions — write whatever helps agents perform the task.
Recommended sections:
Size guidelines:
SKILL.md under 500 lines (~5000 tokens)references/ filesreferences/ files on demand — keep them focused and smalldescriptionThe description is how agents decide whether to activate a skill. Make it specific:
Good:
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
Poor:
description: Helps with PDFs.
Skill versions are tracked centrally in the repository's skills.json file. When you modify an existing skill or add a new one, you must update its version information using Semantic Versioning (SemVer):
x.x.Y): Minor fixes, typo corrections, or small clarifications that do not change how the skill is fundamentally used.x.Y.x): Adding new steps, examples, or optional capabilities in a backward-compatible manner.Y.x.x): Breaking changes to instructions, changing the allowed tools, or fundamentally altering the skill's purpose.When making a change:
skills array inside skills.json (or add a new entry for new skills).version field according to the SemVer rules above (start at "1.0.0" for new skills).metadata.version field in its SKILL.md frontmatter, ensure that is updated as well to match.Run the reference validator if available:
skills-ref validate ./my-skill
Common validation errors:
name contains uppercase letters or spaces → use lowercase hyphens onlyname doesn't match directory name → rename one to match the otherdescription is empty or too vague → expand with what/when languagename (e.g. my--skill) → not allowedname field exactlyname is lowercase with hyphens, no consecutive hyphensdescription explains both what it does and when to trigger itreferences/ not inlinescripts/ are self-contained with helpful error messagescompatibility field included only if environment requirements existskills.json has been updated following Semantic Versioning