Skill Format

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

A skill has a required SKILL.md entrypoint with a Markdown instruction body. You can create it in CloudThinker or upload a .zip package with permitted supporting files.

File structure

SKILL.md can start with YAML frontmatter, followed by instruction sections as Markdown headings:

---
name: security_review-checklist          # letters, digits, underscores, and hyphens
description: Enforce OWASP checks in code review   # optional card summary
---

## 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
SKILL.md entrypoint	Yes	The instruction file CloudThinker stores and agents read when the skill is loaded
Frontmatter block	Optional for a new standalone upload; required when editing an existing skill	Provides metadata such as name and description
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

Upload formats

The Skills page accepts .zip only. A non-zip file is rejected with “Only .zip files are accepted”.

Upload	Requirements and behavior
.zip package	The package must contain SKILL.md. It can include permitted scripts/, schemas/, and references/ directories. Maximum 5 MB. If frontmatter has no name, CloudThinker uses the name of the folder containing SKILL.md.

Limits

Field	Limit
Instructions	50,000 characters
Description	2,000 characters
Skill name	255 characters
Upload size	5 MB

Frontmatter fields

Field	Required	Description
name	Conditional	A manual edit of an existing SKILL.md must include the selected skill name. A .zip upload can omit it and take the containing folder’s name instead. Names start with a letter or digit and can contain letters, digits, underscores, and hyphens.
description	No	Optional short summary shown on the skill card.
argument_hint	No	Optional hint describing the arguments the skill expects.

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 start with a letter or digit. It can contain letters, digits, underscores, and hyphens. It cannot contain spaces or other special characters.

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

Existing skill edit rejected

An existing SKILL.md must include frontmatter with a name that exactly matches the selected skill. Restore the matching name before you save the edit.

Agent does not use the skill

• Verify the skill is enabled (toggle is on)
• Verify the skill is attached to the correct surface
• In Chat, Incident, and Assessment, eligible skills appear in the workspace catalog for load_skill
• In Code Review, attached bodies currently preload under a bounded policy
• 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 attach skills in your workspace.

Skills Overview

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