@cleocode/cleo 2026.2.8 → 2026.3.0

package/skills/agentskills-specs.md

@@ -1,255 +0,0 @@
-# Specification
-
-> The complete format specification for Agent Skills.
-
-This document defines the Agent Skills format.
-
-## Directory structure
-
-A skill is a directory containing at minimum a `SKILL.md` file:
-
-```
-skill-name/
-└── SKILL.md          # Required
-```
-
-<Tip>
-  You can optionally include [additional directories](#optional-directories) such as `scripts/`, `references/`, and `assets/` to support your skill.
-</Tip>
-
-## SKILL.md format
-
-The `SKILL.md` file must contain YAML frontmatter followed by Markdown content.
-
-### Frontmatter (required)
-
-```yaml  theme={null}
----
-name: skill-name
-description: A description of what this skill does and when to use it.
----
-```
-
-With optional fields:
-
-```yaml  theme={null}
----
-name: pdf-processing
-description: Extract text and tables from PDF files, fill forms, merge documents.
-license: Apache-2.0
-metadata:
-  author: example-org
-  version: "1.0"
----
-```
-
-| Field           | Required | Constraints                                                                                                       |
-| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
-| `name`          | Yes      | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen.             |
-| `description`   | Yes      | Max 1024 characters. Non-empty. Describes what the skill does and when to use it.                                 |
-| `license`       | No       | License name or reference to a bundled license file.                                                              |
-| `compatibility` | No       | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). |
-| `metadata`      | No       | Arbitrary key-value mapping for additional metadata.                                                              |
-| `allowed-tools` | No       | Space-delimited list of pre-approved tools the skill may use. (Experimental)                                      |
-
-#### `name` field
-
-The required `name` field:
-
-* Must be 1-64 characters
-* May only contain unicode lowercase alphanumeric characters and hyphens (`a-z` and `-`)
-* Must not start or end with `-`
-* Must not contain consecutive hyphens (`--`)
-* Must match the parent directory name
-
-Valid examples:
-
-```yaml  theme={null}
-name: pdf-processing
-```
-
-```yaml  theme={null}
-name: data-analysis
-```
-
-```yaml  theme={null}
-name: code-review
-```
-
-Invalid examples:
-
-```yaml  theme={null}
-name: PDF-Processing  # uppercase not allowed
-```
-
-```yaml  theme={null}
-name: -pdf  # cannot start with hyphen
-```
-
-```yaml  theme={null}
-name: pdf--processing  # consecutive hyphens not allowed
-```
-
-#### `description` field
-
-The required `description` field:
-
-* Must be 1-1024 characters
-* Should describe both what the skill does and when to use it
-* Should include specific keywords that help agents identify relevant tasks
-
-Good example:
-
-```yaml  theme={null}
-description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
-```
-
-Poor example:
-
-```yaml  theme={null}
-description: Helps with PDFs.
-```
-
-#### `license` field
-
-The optional `license` field:
-
-* Specifies the license applied to the skill
-* We recommend keeping it short (either the name of a license or the name of a bundled license file)
-
-Example:
-
-```yaml  theme={null}
-license: Proprietary. LICENSE.txt has complete terms
-```
-
-#### `compatibility` field
-
-The optional `compatibility` field:
-
-* Must be 1-500 characters if provided
-* Should only be included if your skill has specific environment requirements
-* Can indicate intended product, required system packages, network access needs, etc.
-
-Examples:
-
-```yaml  theme={null}
-compatibility: Designed for Claude Code (or similar products)
-```
-
-```yaml  theme={null}
-compatibility: Requires git, docker, jq, and access to the internet
-```
-
-<Note>
-  Most skills do not need the `compatibility` field.
-</Note>
-
-#### `metadata` field
-
-The optional `metadata` field:
-
-* A map from string keys to string values
-* Clients can use this to store additional properties not defined by the Agent Skills spec
-* We recommend making your key names reasonably unique to avoid accidental conflicts
-
-Example:
-
-```yaml  theme={null}
-metadata:
-  author: example-org
-  version: "1.0"
-```
-
-#### `allowed-tools` field
-
-The optional `allowed-tools` field:
-
-* A space-delimited list of tools that are pre-approved to run
-* Experimental. Support for this field may vary between agent implementations
-
-Example:
-
-```yaml  theme={null}
-allowed-tools: Bash(git:*) Bash(jq:*) Read
-```
-
-### Body content
-
-The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.
-
-Recommended sections:
-
-* Step-by-step instructions
-* Examples of inputs and outputs
-* Common edge cases
-
-Note that the agent will load this entire file once it's decided to activate a skill. Consider splitting longer `SKILL.md` content into referenced files.
-
-## Optional directories
-
-### scripts/
-
-Contains executable code that agents can run. Scripts should:
-
-* Be self-contained or clearly document dependencies
-* Include helpful error messages
-* Handle edge cases gracefully
-
-Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript.
-
-### references/
-
-Contains additional documentation that agents can read when needed:
-
-* `REFERENCE.md` - Detailed technical reference
-* `FORMS.md` - Form templates or structured data formats
-* Domain-specific files (`finance.md`, `legal.md`, etc.)
-
-Keep individual [reference files](#file-references) focused. Agents load these on demand, so smaller files mean less use of context.
-
-### assets/
-
-Contains static resources:
-
-* Templates (document templates, configuration templates)
-* Images (diagrams, examples)
-* Data files (lookup tables, schemas)
-
-## Progressive disclosure
-
-Skills should be structured for efficient use of context:
-
-1. **Metadata** (\~100 tokens): The `name` and `description` fields are loaded at startup for all skills
-2. **Instructions** (\< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is activated
-3. **Resources** (as needed): Files (e.g. those in `scripts/`, `references/`, or `assets/`) are loaded only when required
-
-Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files.
-
-## File references
-
-When referencing other files in your skill, use relative paths from the skill root:
-
-```markdown  theme={null}
-See [the reference guide](references/REFERENCE.md) for details.
-
-Run the extraction script:
-scripts/extract.py
-```
-
-Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains.
-
-## Validation
-
-Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference library to validate your skills:
-
-```bash  theme={null}
-skills-ref validate ./my-skill
-```
-
-This checks that your `SKILL.md` frontmatter is valid and follows all naming conventions.
-
-
----
-
-> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://agentskills.io/llms.txt

package/skills/agentskills-what-are-skills.md

@@ -1,75 +0,0 @@
-# What are skills?
-
-> Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.
-
-At its core, a skill is a folder containing a `SKILL.md` file. This file includes metadata (`name` and `description`, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, templates, and reference materials.
-
-```directory  theme={null}
-my-skill/
-├── SKILL.md          # Required: instructions + metadata
-├── scripts/          # Optional: executable code
-├── references/       # Optional: documentation
-└── assets/           # Optional: templates, resources
-```
-
-## How skills work
-
-Skills use **progressive disclosure** to manage context efficiently:
-
-1. **Discovery**: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant.
-
-2. **Activation**: When a task matches a skill's description, the agent reads the full `SKILL.md` instructions into context.
-
-3. **Execution**: The agent follows the instructions, optionally loading referenced files or executing bundled code as needed.
-
-This approach keeps agents fast while giving them access to more context on demand.
-
-## The SKILL.md file
-
-Every skill starts with a `SKILL.md` file containing YAML frontmatter and Markdown instructions:
-
-```mdx  theme={null}
----
-name: pdf-processing
-description: Extract text and tables from PDF files, fill forms, merge documents.
----
-
-# PDF Processing
-
-## When to use this skill
-Use this skill when the user needs to work with PDF files...
-
-## How to extract text
-1. Use pdfplumber for text extraction...
-
-## How to fill forms
-...
-```
-
-The following frontmatter is required at the top of `SKILL.md`:
-
-* `name`: A short identifier
-* `description`: When to use this skill
-
-The Markdown body contains the actual instructions and has no specific restrictions on structure or content.
-
-This simple format has some key advantages:
-
-* **Self-documenting**: A skill author or user can read a `SKILL.md` and understand what it does, making skills easy to audit and improve.
-
-* **Extensible**: Skills can range in complexity from just text instructions to executable code, assets, and templates.
-
-* **Portable**: Skills are just files, so they're easy to edit, version, and share.
-
-## Next steps
-
-* [View the specification](/specification) to understand the full format.
-* [Add skills support to your agent](/integrate-skills) to build a compatible client.
-* [See example skills](https://github.com/anthropics/skills) on GitHub.
-* [Read authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) for writing effective skills.
-* [Use the reference library](https://github.com/agentskills/agentskills/tree/main/skills-ref) to validate skills and generate prompt XML.
-
-
----
-
-> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://agentskills.io/llms.txt