> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
```markdown theme={null}
---
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.
```markdown theme={null}
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...
## 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.
```markdown theme={null}
## 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:
````markdown theme={null}
---
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.
## Related
Create, upload, enable, and assign skills in your workspace.
Understand how skills fit into the CloudThinker platform and agent workflow.