SKILL.md Format
The complete specification for the SKILL.md file format.
Overview
A SKILL.md file uses Markdown with YAML frontmatter to define an Agent Skill.
File Structure
---
# YAML Frontmatter (metadata)
name: Skill Name
description: Brief description
---
# Main Content
Your skill instructions in Markdown format.
Frontmatter Fields
Required Fields
| Field | Type | Description |
|-------|------|-------------|
| name | string | Skill name (max 50 characters) |
| description | string | Brief description (max 200 characters) |
Optional Fields
| Field | Type | Description |
|-------|------|-------------|
| version | string | Semantic version (e.g., "1.0.0") |
| author | string | Author name or organization |
| license | string | License type (e.g., "MIT") |
| platforms | array | Supported platforms |
| categories | array | Skill categories |
| tags | array | Search keywords |
| repository | string | Source repository URL |
| website | string | Documentation website |
Example Frontmatter
---
name: React Best Practices
description: Guidelines for writing clean React components
version: 2.1.0
author: React Community
license: MIT
platforms:
- claude-code
- codex
- chatgpt
categories:
- development
- frontend
tags:
- react
- javascript
- components
---
Content Structure
Recommended Sections
# Skill Name
## Context
Background information and domain knowledge.
## Guidelines
Specific rules and best practices.
## Do's and Don'ts
Clear behavioral guidance.
## Examples
Sample interactions or code snippets.
## References
Links to additional resources.
Formatting Tips
- Use headings (
#,##,###) to organize content - Use bullet lists for guidelines
- Use code blocks for examples
- Use bold for emphasis on key points
- Keep paragraphs concise
Platforms Field
Specify which platforms your skill supports:
platforms:
- claude-code # Claude Code CLI
- codex # Codex CLI
- chatgpt # ChatGPT Custom Instructions
Categories
Choose from available categories:
Technical:
development- General developmentfrontend- Frontend/UI developmentbackend- Backend/API developmentdevops- DevOps/Infrastructuredata- Data science/Analyticsai-ml- AI/Machine Learning
Professional:
marketing- Marketing/Contentdesign- Design/UXlegal- Legal/Compliancefinance- Finance/Accountinghr- Human Resourceseducation- Education/Training
Validation
Your SKILL.md will be validated for:
- Valid YAML frontmatter syntax
- Required fields present
- Field length limits
- Valid category/platform values
- Markdown formatting
Complete Example
---
name: TypeScript Best Practices
description: Guidelines for writing type-safe, maintainable TypeScript code
version: 1.0.0
author: TypeScript Community
license: MIT
platforms:
- claude-code
- codex
categories:
- development
- frontend
- backend
tags:
- typescript
- javascript
- types
---
# TypeScript Best Practices
## Context
This skill provides guidelines for writing high-quality TypeScript code.
## Guidelines
### Type Safety
- Always define explicit types for function parameters
- Avoid using `any` type
- Use type guards for runtime checks
### Code Organization
- One export per file for main modules
- Group related types in a `types.ts` file
- Use barrel exports for public APIs
## Do's and Don'ts
### Do
- Use strict mode
- Define interfaces for object shapes
- Use generics for reusable code
### Don't
- Suppress TypeScript errors with `@ts-ignore`
- Use `any` as a quick fix
- Mix JavaScript and TypeScript in the same project
## Examples
### Good: Explicit Types
\`\`\`typescript
function greet(name: string): string {
return \`Hello, \${name}!\`;
}
\`\`\`
### Bad: Implicit Any
\`\`\`typescript
// Avoid this
function greet(name) {
return \`Hello, \${name}!\`;
}
\`\`\`