Skills Authoring

Overview

Skills are installable modules under ~/.agent-os/skills/<name>/. Each skill has:

• skill.yaml or SKILL.md — Name, description, optional metadata; SKILL.md can embed a YAML block for the same.
• tools.yaml — Optional. Defines tools (HTTP or exec-based) that the skill adds to the tool registry.
• config.schema.json — Optional. JSON schema for skill config; the dashboard uses it for a config form.
• SETUP.md — Optional. Setup instructions (e.g. how to get API keys).

Agents declare skills: ["weather", "memory"]. The loader reads each skill’s YAML and tools, registers tools, and stores per-skill config in ~/.agent-os/configs/<skill_id>.json.

Skill folder layout

~/.agent-os/skills/weather/
├── skill.yaml       # or SKILL.md (Markdown with embedded ```yaml block)
├── tools.yaml       # optional
├── config.schema.json  # optional
└── SETUP.md         # optional

• skill.yaml (or SKILL.md) — Required. Defines name, description, and optionally credentials, api_base, metadata, etc.
• tools.yaml — Optional. Top-level tools: array; each entry defines a tool (id, description, method/path for HTTP, or exec). See loader and existing skills in the repo for the exact schema.
• config.schema.json — Optional. Schema for the key/value config stored in ~/.agent-os/configs/<skill_id>.json. Exposed as GET /api/skills/:id/config/schema.
• SETUP.md — Optional. Returned as GET /api/skills/:id/setup for dashboard display.

Create your first skill

1. Create the directory:

   mkdir -p ~/.agent-os/skills/hello-world
   

2. Add skill.yaml (or SKILL.md):

   name: hello-world
   description: Use when the user says hello or asks for a greeting.
   

   
   Or in SKILL.md with embedded YAML:

   # Hello World
   Use when the user wants a greeting.
   ```yaml
   name: hello-world
   description: Use when the user says hello or asks for a greeting.
   

3. (Optional) Add tools.yaml — If the skill needs tools, add a tools: array. Each tool has at least id and description; for HTTP tools, method, path, and parameters; for exec, the loader may expect a different shape (see repo skills).
4. Install / load — Copy the folder to ~/.agent-os/skills/ or use Install system skills / Upload from the dashboard. Restart the server or rely on hot-load if supported. Then assign the skill to an agent in the Agents page.

Skill format (reference)

• name — Unique skill id (folder name usually matches). Used in agent skills and in configs.
• description — One-line summary; helps the runtime and dashboard know when the skill applies.
• credentials — Optional list of env/config key names the skill needs (e.g. API keys). Users set them in Settings → Skills → config for this skill.
• api_base / base_url_env — Optional. For HTTP tools, base URL or env var name for the base URL. Integration base URLs are runtime config; skills use placeholders like {{base}} in tools where the agent supplies base at runtime.
• metadata — Optional. e.g. metadata.clawdbot.requires.env for extra required env vars.

Tools (tools.yaml)

Tools are registered in the tool registry when the skill is loaded. Each tool has:

• id — Unique tool name (e.g. weather_current). Must be unique across all skills.
• description — When to call this tool (for the model).
• method, path — For HTTP tools: method and path (or full URL). Path can use {{base}} if the skill uses a runtime-supplied base URL.
• parameters — Input schema for the model (names, types, descriptions).

See existing skills in data/skills/ in the repo for examples (e.g. weather, memory, web-search). The loader may also support exec-based tools that run a script in the skill dir with skill_id; see skills/loader.ts and tools/exec.ts for the contract.

Config and credentials

• Required env/config — Declare in skill YAML (credentials or metadata.clawdbot.requires.env). Users fill them in the dashboard (Settings → Skills → select skill → Config) or you can document them in SETUP.md.
• Storage — Values are stored in ~/.agent-os/configs/<skill_id>.json. The runtime and tools read them when executing; do not put secrets in the skill repo.

Where skills load from

• Primary: ~/.agent-os/skills/ (or AGENT_OS_SKILLS_DIR). Each subdirectory is one skill (with skill.yaml or SKILL.md).
• System/seed: data/skills/ in the repo (or AGENT_OS_SEED_SKILLS_DIR). Use Install system skills (dashboard or POST /api/skills/install-system) to copy them into ~/.agent-os/skills/.
• Store: Optional. If a store registry URL is configured, the dashboard and POST /api/skills/install can install skills by slug from that registry.

Adding to a store (optional)

If you run or use a skill store (e.g. SulalaHub-style):

• Publish skill content (README/Markdown + tools.yaml) at a URL.
• Add an entry to the store’s registry: slug, name, description, version, url. Then users can install via the dashboard or API with that slug.

Agent OS does not require a store; skills can be installed by copying to ~/.agent-os/skills/ or via upload/install-system.

Validation

Follow the existing skill layout and naming in the repo. The loader parses YAML and registers tools; invalid YAML or missing name/description may cause the skill to be skipped (check server logs).