@cleocode/skills

Part of CLEO. Start with the root README; run cleo <command> --help for any command.

CLEO skill definitions - bundled capabilities for AI agents.

Overview

This package contains pre-built skills and capabilities that extend CLEO agents with specialized functionality. Skills define what an agent can do and how it should do it.

What are CLEO Skills?

Skills are modular capability packages that:

• Define specific tasks an agent can perform
• Provide detailed instructions and workflows
• Include constraints and best practices
• Extend the base agent protocols
• Are injected at spawn time by orchestrators

Installation

npm install @cleocode/skills

pnpm add @cleocode/skills

yarn add @cleocode/skills

Included Skills

Tiers and install behaviour come from each SKILL.md's metadata (owner decision D11157). packages/skills/skills/manifest.json is generated from them by node scripts/skills/generate-manifest.mjs; gates 29-31 keep the manifest, installability and every documented cleo command honest.

Core (installed to every harness, always relevant)

On demand (installed; loaded by description or by stage guidance)

Internal (CLEO development only; never installed to a harness)

Merged or retired in T12649: ct-docs-write and ct-docs-review are references of ct-documentor; ct-memory and ct-stickynote are references of ct-cleo; ct-skill-creator and ct-skill-validator became ct-skill-author; ct-docs-lookup (use the Context7 MCP) and ct-master-tac were retired; signaldock-connect moved to the SignalDock repository.

Skill Structure

Each skill follows a standardized structure:

skills/
├── <skill-name>/
│   ├── SKILL.md              # Main skill definition (required)
│   ├── README.md             # User documentation (optional)
│   ├── INSTALL.md            # Installation guide (optional)
│   ├── agents/               # Specialized agent definitions
│   │   ├── analyzer.md
│   │   └── executor.md
│   ├── references/           # Reference documentation
│   │   ├── patterns.md
│   │   └── examples.md
│   └── assets/               # Assets and templates
│       └── template.md

Using Skills

From CLI

# Load a skill
cleo skills load ct-research-agent

# Use skill with a task
cleo skills apply ct-research-agent --task T1234

# List available skills
cleo skills list

# Show skill details
cleo skills show ct-research-agent

From Code

import { skills } from '@cleocode/core';

// Load a skill
const skill = await skills.load('ct-research-agent');

// Apply skill to a task
await skills.apply({
  skill: 'ct-research-agent',
  taskId: 'T1234',
  context: { topic: 'API design patterns' }
});

// Get skill information
const info = await skills.get('ct-codebase-mapper');
console.log(info.description);
console.log(info.capabilities);

From Agents

Skills are automatically injected when spawning agents:

import { orchestration } from '@cleocode/core';

// Skill is injected based on task context
await orchestration.spawn({
  agent: 'cleo-subagent',
  taskId: 'T1234',
  skill: 'ct-implementation' // Injected at spawn
});

Skill Definition Format

Skills are defined in SKILL.md files with YAML frontmatter:

---
id: ct-example-skill
name: Example Skill
description: |
  Multi-line description of what this skill does
  and when to use it.
version: 1.0.0
author: CLEO Team
tags:
  - development
  - example
dependencies:
  - ct-cleo
allowed_tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
  - WebFetch
  - WebSearch
---

# Example Skill

## Overview

Detailed explanation of the skill's purpose and usage.

## Capabilities

- **Capability 1**: Description
- **Capability 2**: Description

## Workflow

1. **Step 1**: Description
2. **Step 2**: Description
3. **Step 3**: Description

## Constraints

| ID | Rule | Enforcement |
|----|------|-------------|
| EX-001 | **MUST** follow constraint | Required |
| EX-002 | **SHOULD** consider guideline | Recommended |

## Examples

### Example 1: Basic Usage

```bash
# Command example

Example 2: Advanced Usage

# Advanced command example

References

• Related Documentation
• Pattern Guide

## Creating Custom Skills

### 1. Create Skill Directory

```bash
mkdir -p skills/my-custom-skill

2. Create SKILL.md

---
id: my-custom-skill
name: My Custom Skill
description: |
  Description of what this skill does.
version: 1.0.0
author: Your Name
tags:
  - custom
  - specialized
allowed_tools:
  - Read
  - Write
  - Bash
---

# My Custom Skill

## Purpose

Explain what this skill does and when to use it.

## Workflow

1. Analyze the task
2. Execute the work
3. Validate the output

## Output Format

Describe expected output format.

3. Register the Skill

import { skills } from '@cleocode/core';

skills.register({
  id: 'my-custom-skill',
  path: './skills/my-custom-skill',
  version: '1.0.0'
});

Skill Validation

Validate skills before distribution:

# Validate a skill
cleo skills validate my-custom-skill

# Or programmatically
import { skills } from '@cleocode/core';

const result = await skills.validate('my-custom-skill');
if (result.valid) {
  console.log('Skill is valid ✓');
} else {
  console.log('Issues:', result.issues);
}

Skill Categories

Skills are organized by category:

Development Skills

• Codebase mapping and analysis
• Implementation guidance
• Testing strategies

Research Skills

• Information gathering
• Documentation lookup
• Multi-source synthesis

Orchestration Skills

• Multi-agent coordination
• Workflow management
• Consensus building

Quality Skills

• Code review
• Documentation review
• Compliance checking

Domain Skills

• Framework-specific guidance
• Platform integration
• Tool expertise

Skill Dependencies

Skills can depend on other skills:

# In SKILL.md frontmatter
dependencies:
  - ct-cleo          # Base CLEO operations
  - ct-research-agent # Research capabilities
  - ct-validator     # Validation support

Dependencies are automatically loaded when a skill is applied.

Skill Chaining

Skills can be chained together:

import { skills } from '@cleocode/core';

// Chain multiple skills
await skills.chain([
  { skill: 'ct-research-agent', taskId: 'T1234' },
  { skill: 'ct-spec-writer', taskId: 'T1235' },
  { skill: 'ct-epic-architect', taskId: 'T1236' }
]);

Skill Profiles

Group skills into profiles for different roles:

# profiles/backend-developer.yaml
name: Backend Developer
skills:
  - ct-codebase-mapper
  - ct-research-agent
  - ct-spec-writer
  - drizzle-orm
  - ct-dev-workflow

Use profiles:

cleo skills apply-profile backend-developer --task T1234

Shared Resources

Common patterns and utilities in skills/_shared/:

• manifest-operations.md - Working with pipeline_manifest via cleo manifest CLI
• subagent-protocol-base.md - Base subagent protocols
• skill-chaining-patterns.md - Chaining best practices
• testing-framework-config.md - Test configuration
• task-system-integration.md - Task system integration
• cleo-style-guide.md - CLEO documentation style

Integration with Agents

Skills and agents work together:

1. Orchestrator identifies task requirements
2. Selects appropriate skill based on task type
3. Spawns agent with skill injected
4. Agent follows skill instructions
5. Skill guides execution within agent framework

Example:

Task: "Research authentication patterns"
  ↓
Orchestrator selects: ct-research-agent skill
  ↓
Spawns: cleo-subagent with ct-research-agent injected
  ↓
Agent follows LOOM protocol
  ↓
Skill guides research methodology
  ↓
Output: Research report written to file

Dependencies

This package has no runtime dependencies. It contains:

• Skill definitions (markdown files)
• Reference documentation
• Configuration templates
• Example outputs

License

MIT License - see LICENSE for details.