# Cuga Build Cuga Skill

> Use when the user wants a running CugaAgent to load a new capability at runtime via cuga's own skill system, e.g. "add a skill to my agent", "create a .cuga/skills SKILL.md", "how does load_skill work".

- Skill: `cuga-project/cuga-build-cuga-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cuga-project/cuga-build-cuga-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cuga-project/cuga-build-cuga-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cuga-project (https://skillmd.com/u/cuga-project)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cuga-project/cuga-build-cuga-skill

---


# Authoring a cuga runtime skill

This is different from the IDE-assistant skill you're reading right now. **cuga's own agents** can discover and load `SKILL.md` files at runtime via a `load_skill` tool — this skill teaches you how to author one of those.

## Where skills live

Controlled by `[skills] root` in `settings.toml` (or `DYNACONF_SKILLS__ROOT`):

| `root` value | Directory | Notes |
|---|---|---|
| `cuga` (default) | `.cuga/skills/` | cuga's own convention, avoids colliding with `.agents/skills/` written by other tools |
| `agents` | `.agents/skills/` | shared convention used by e.g. `npx skills` |
| `global_agents` | `~/.config/agents/skills/` | global, not project-scoped |
| `global_cuga` | `~/.config/cuga/skills/` | legacy global path |

Skills are discovered recursively (`**/SKILL.md`) under whichever root is active.

## SKILL.md shape (cuga runtime contract)

Required frontmatter: **`name`** and **`description`** (shown to the agent in its available-skills list — write a description the agent can use to decide when to load it). Optional **`requirements`**: a pip/npm package or list of packages the skill needs installed. Everything below the frontmatter is arbitrary markdown — the full instruction text handed back by `load_skill` when the agent loads this skill.

```markdown
---
name: my-skill
description: Use when the user asks to <do X>. Loads instructions for <Y>.
requirements: some-pip-package
---

# My Skill

Step-by-step instructions, code snippets, examples — whatever the agent
needs in its context to actually perform the task.
```

Name validation: no path separators or `..` in `name` — cuga sanitizes/rejects unsafe or Jinja2-template-injected values in `name`/`description` for prompt-injection safety.

## Try it

```bash
uv run cuga start demo_skills
```

Runs with `[advanced_features] sandbox_mode = "native"` by default. For sandboxed execution instead: `uv sync --extra opensandbox` then use the `opensandbox` mode, or `uv sync --group sandbox` + `uv run cuga start demo --sandbox` with `[skills]` enabled for Docker/Podman isolation.

## Installing a ready-made skill

Anthropic publishes ready-made skill folders (e.g. `pptx`) that follow the same `SKILL.md` convention:

```bash
npx skills add https://github.com/anthropics/skills --skill pptx -a universal
```

This drops it under `.agents/skills/pptx/SKILL.md`. To use cuga's default layout instead, copy/symlink it into `.cuga/skills/`. Add `-g` to install globally. Restart `uv run cuga start demo_skills` (or your app) afterward so skills are rescanned — there's no hot-reload.

## Don't confuse this with policies

A runtime skill is instructional content the agent chooses to load. A policy (playbook, intent guard, etc. — see `cuga-author-policy`) is a rule the runtime *enforces* on the agent regardless of whether it "chooses" to. Use a skill for optional know-how, a policy for a constraint or workflow that must always apply.