Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cowagent.ai/llms.txt

Use this file to discover all available pages before exploring further.

skill-creator is a “meta-skill” that helps the Agent create, install, and update other skills, ensuring every skill follows a consistent SKILL.md format and directory layout.

​
When It Triggers

  • The user wants to install a skill from a URL or remote repository
  • The user wants to create a brand-new skill from scratch
  • An existing skill needs upgrading or restructuring

​
What Is a Skill?

A skill is a reusable instruction set plus optional scripts and assets. It injects domain expertise into the Agent so it can handle specific tasks like a specialist. A skill typically contains:
  1. Specialised workflow — step-by-step instructions for a category of tasks
  2. Tool usage — how to call a particular API or process a particular file format
  3. Domain knowledge — team conventions, business rules, data schemas, etc.
  4. Attached resources — scripts, reference docs, templates, etc.
Core principle: less is more. Only write what the Agent wouldn’t figure out on its own. For every line you add, ask yourself: is it worth the tokens?

​
Directory Structure

skill-name/
├── SKILL.md            # Required: skill definition
│   ├── YAML frontmatter (name / description are mandatory)
│   └── Markdown body (instructions + examples)
└── Optional resources
    ├── scripts/        # Executable scripts (Python / Bash, etc.)
    ├── references/     # Large reference docs the Agent reads on demand
    └── assets/         # Templates, icons, etc. used directly in output

​
SKILL.md Specification

Frontmatter fields in the SKILL.md header:
FieldDescription
nameSkill name — lowercase with hyphens, must match the directory name
descriptionThe most important field. Clearly state what the skill does and when to use it. The Agent reads this to decide whether to invoke it. All trigger-related descriptions go here, not in the body
metadata.cowagent.requires.binsSystem CLI tools that must be installed
metadata.cowagent.requires.envRequired environment variables (all must be present)
metadata.cowagent.requires.anyEnvMultiple API keys — at least one must be set
metadata.cowagent.requires.anyBinsMultiple tools — at least one must be installed
metadata.cowagent.alwaysSet to true to always load, skipping dependency checks
metadata.cowagent.emojiDisplay emoji (optional)
metadata.cowagent.osOS restriction, e.g. ["darwin", "linux"]
The category field does not need to be set manually — the system automatically sets it to skill.
Two ways to declare API key dependencies: 
metadata:
  cowagent:
    requires:
      env: ["MYAPI_KEY"]            # Must be present

metadata:
  cowagent:
    requires:
      anyEnv: ["OPENAI_API_KEY", "LINKAI_API_KEY"]   # At least one
Skills are auto-enabled/disabled based on dependencies: they activate when all required environment variables are present and deactivate when any are missing — no need for manual /skill enable.

​
Resource Directories

DirectoryWhat goes hereWhat does NOT go here
scripts/Code that needs to run repeatedly, or scripts that produce deterministic resultsDemo-only code snippets
references/Documents over 500 lines that genuinely won’t fit in SKILL.md (e.g. a full DB schema)General API docs, tutorials, examples
assets/Files that appear in the final output (templates, icons, boilerplate, etc.)Explanatory documentation
In principle, everything goes in SKILL.md — only split into resource directories when it truly won’t fit.Do not add README.md, CHANGELOG.md, or INSTALLATION_GUIDE.md to a skill — put everything in SKILL.md. Resource directories should only contain scripts that actually run or assets that are actually used.

​
Installing External Skills

After installation, the skill lands in <workspace>/skills/<name>/.
SourceHow to install
URL (single file)curl / web_fetch
URL (zip archive)Download and extract
Local SKILL.mdRead directly
Local zip archiveExtract
Installation steps:
  1. Locate the SKILL.md (may be at the root or in a subdirectory of the archive)
  2. Read the name from the frontmatter
  3. Copy the entire skill directory (including SKILL.md, scripts/, assets/, etc.) to <workspace>/skills/<name>/
  4. If the archive contains an INSTALL.md or similar setup script, run it — but the final result must still reside under <workspace>/skills/<name>/

​
Creating a Skill from Scratch

Recommended order:
  1. Clarify requirements — ask the user for a few concrete use cases (don’t ask too many at once)
  2. Plan the structure — does this skill need scripts? Reference docs? Template assets?
  3. Scaffold — use the init script: 
    scripts/init_skill.py <skill-name> --path <workspace>/skills [--resources scripts,references,assets] [--examples]
  4. Fill in content — write SKILL.md, add scripts and resources. Always test scripts after writing them
  5. Validate (optional): 
    scripts/quick_validate.py <workspace>/skills/<skill-name>
  6. Iterate — keep improving based on real-world usage feedback

​
Naming Conventions

  • Use only lowercase letters, digits, and hyphens. Normalise user-given names, e.g. Plan Mode → plan-mode
  • Maximum 64 characters
  • Keep it short, start with a verb, make it self-explanatory
  • Use tool names as prefixes when appropriate, e.g. gh-address-comments, linear-address-issue
  • The directory name and the name field must match exactly

​
Three-Level Loading

Skills are not loaded into context all at once — they use a three-level progressive loading mechanism:
  1. Metadata (name + description) — always in context (~100 words). The Agent uses this to decide whether to invoke the skill
  2. SKILL.md body — loaded only when the skill is activated; keep it under 500 lines
  3. Resource files — read on demand by the Agent
For skills with multiple variants (e.g. multi-cloud deployment), organise like this: 
cloud-deploy/
├── SKILL.md             # Main workflow and provider selection logic
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md
When the user picks AWS, the Agent only reads aws.md — no need to load all three providers.

​
Common Design Patterns

Step-by-step: numbered steps with corresponding scripts. 
1. Analyse form structure (run analyze_form.py)
2. Generate field mappings (edit fields.json)
3. Auto-fill the form (run fill_form.py)
Branching: different flows based on user intent. 
1. Determine operation type:
   **Creating new content?** → follow the "Create" workflow
   **Editing existing content?** → follow the "Edit" workflow
Template-based: when output format has strict requirements, include a template in SKILL.md for the Agent to follow.