Skip to main content
A skill is a Markdown file with YAML frontmatter. The frontmatter provides metadata, and the body contains the instructions that agents follow. Understanding the format helps you write skills that agents apply reliably.

​
File structure

A skill is a single SKILL.md file:

​
Frontmatter reference

The YAML frontmatter block at the top of SKILL.md defines skill metadata.
FieldRequiredDescription
nameYesUnique identifier in slug format (lowercase, hyphens, no spaces). Example: security-review-checklist
descriptionYesShort summary of what the skill does. Displayed on the skill card in the UI.
---
name: security-review-checklist
description: Enforce OWASP Top 10 checks during code review
---

​
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:
FreedomStyleUse case
HighGuidelines and principlesCreative tasks, architectural advice, exploratory reviews
MediumChecklists with examplesStandard code reviews, security audits, compliance checks
LowExact templates and rulesRegulatory 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

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
  • 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
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.

​
Next steps

Custom Skills

Learn how to create, upload, and manage skills in your workspace.

Skills Overview

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