> ## 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

> How to write effective SKILL.md files — structure, frontmatter, and best practices

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

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

```yaml theme={null}
---
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.

```markdown theme={null}
<!-- 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.

```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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Custom Skills" icon="wand-magic-sparkles" href="/guide/skills/custom-skills">
    Learn how to create, upload, and manage skills in your workspace.
  </Card>

  <Card title="Skills Overview" icon="sparkles" href="/guide/skills/overview">
    Understand how skills fit into the CloudThinker platform and agent workflow.
  </Card>
</CardGroup>