Skill Format

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`	Yes	A short summary of when to use the skill. Agents choose skills by reading descriptions, so a skill without one cannot be selected and will not load.
`argument_hint`	No	Optional hint describing the arguments the skill expects.

When a skill cannot load

A skill whose SKILL.md has no usable description is listed as broken. Its detail view stays open so you can add one, but it is not offered in the / command picker and the CloudThinker CLI does not install it. Add a description: line to the frontmatter and save to make it loadable again.

Writing effective instructions

Every word counts

Agents read skill instructions alongside their built-in instructions and the task at hand. 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 — see how skills are applied
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.

Custom skills

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

Skills overview

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

Review

Optimize

Resolve

Cyber

ChatOps

Skills

Artifacts & Dashboards

File structure

Upload formats

Limits

Frontmatter fields

When a skill cannot load

Writing effective instructions

Every word counts

Degrees of freedom

Examples beat explanations

Complete example

Troubleshooting

Custom skills

Skills overview

​File structure

​Upload formats

​Limits

​Frontmatter fields

​When a skill cannot load

​Writing effective instructions

​Every word counts

​Degrees of freedom

​Examples beat explanations

​Complete example

​Troubleshooting

​Related

Custom skills

Skills overview

File structure

Upload formats

Limits

Frontmatter fields

When a skill cannot load

Writing effective instructions

Every word counts

Degrees of freedom

Examples beat explanations

Complete example

Troubleshooting

Related