Skill Format

Write SKILL.md files agents follow reliably — file structure, frontmatter fields, and instruction patterns

A skill is a single SKILL.md file: YAML frontmatter for metadata, a Markdown body with the instructions agents follow. This page is the reference for that format — structure, frontmatter fields, and the instruction patterns agents apply most reliably.

File structure

Every skill follows the same shape — frontmatter first, then instruction sections as Markdown headings:

---
name: security-review-checklist          # slug format: lowercase, hyphens
description: Enforce OWASP checks in code review   # shown on the skill card
---

## SQL injection                         # one H2 per rule group

- Flag raw string concatenation in SQL queries
- Require parameterized queries or ORM methods

## Secrets handling

- Flag hardcoded credentials, tokens, and API keys
- Require secrets to come from a secrets manager or environment variables

Part	Required	Purpose
Frontmatter block	Yes	Identifies the skill; the UI reads name and description from it
Instruction body	Yes	Markdown the agent loads verbatim when the skill runs
H2 rule groups	Recommended	One heading per domain keeps rules scannable for you and the agent
Inline examples	Recommended	Concrete good/bad examples that anchor each rule

Frontmatter fields

Field	Required	Description
name	Yes	Unique identifier in slug format (lowercase, hyphens, no spaces). Example: security-review-checklist
description	Yes	Short summary of what the skill does. Displayed on the skill card in the UI.

Writing effective instructions

Every token counts

Agents process skill instructions alongside their own system prompt and task context. Keep instructions concise — write only what the agent doesn’t already know.

<!-- Too verbose -->
When reviewing code, you should always check for SQL injection
vulnerabilities. SQL injection is a type of security vulnerability
where an attacker can execute arbitrary SQL commands through
user input that is not properly sanitized...

<!-- Effective -->
## SQL Injection
- Flag raw string concatenation in SQL queries
- Require parameterized queries or ORM methods
- Check for `execute()` calls with f-strings or `.format()`

Degrees of freedom

Match your instruction style to how much flexibility the agent should have:

Freedom	Style	Use case
High	Guidelines and principles	Creative tasks, architectural advice, exploratory reviews
Medium	Checklists with examples	Standard code reviews, security audits, compliance checks
Low	Exact templates and rules	Regulatory compliance, formatting standards, mandatory fields

Examples beat explanations

Agents follow concrete examples more reliably than abstract rules. When possible, show the expected behavior instead of describing it.

## Naming conventions

Use descriptive variable names that reveal intent.

### Good
- `remaining_retries` not `r`
- `is_authenticated` not `auth`
- `max_connection_pool_size` not `pool`

### Bad
- Single-letter variables outside loop iterators
- Abbreviations that aren't universally understood
- Boolean variables without `is_`, `has_`, or `should_` prefix

Complete example

A realistic skill for enforcing PR review standards:

---
name: pr-review-standards
description: Enforce team PR review standards including size limits, test coverage, and documentation requirements
---

## PR Size

- Flag PRs with more than 500 lines changed as "needs splitting"
- Warn on PRs with more than 10 files changed
- Suggest logical split points when flagging oversized PRs
- Auto-generated files (migrations, lockfiles) do not count toward limits

## Test Coverage

- Require test files for any new public function or method
- Flag removed tests without corresponding feature removal
- Check that edge cases are covered, not just happy paths

## Documentation

- Require JSDoc/docstring for exported functions with more than 3 parameters
- Flag breaking API changes without migration guide updates
- Check that README is updated when adding new environment variables

## Review Comment Format

Use this structure for review comments:

```
**[severity]** Brief title

Description of the issue.

**Suggestion:** How to fix it.
```

Severity levels: `critical`, `warning`, `suggestion`, `nitpick`

Troubleshooting

Skill name rejected

The name field must be in slug format: lowercase letters, numbers, and hyphens only. No spaces, underscores, or special characters.

• security-checklist — valid
• Security Checklist — invalid
• security_checklist — invalid

Agent ignores skill instructions

• Verify the skill is enabled (toggle is on)
• Verify the skill is assigned to the correct feature
• Check that instructions are specific and actionable — vague guidance is often deprioritized
• Shorter, focused skills are applied more reliably than long, broad ones

Instructions are too long

If your skill exceeds a few hundred lines, consider splitting it into multiple focused skills. Agents handle several short skills better than one massive skill.

Split by domain: separate security rules, performance guidelines, and style conventions into individual skills.

Related

Custom Skills

Create, upload, enable, and assign skills in your workspace.

Skills Overview

Understand how skills fit into the CloudThinker platform and agent workflow.