Agent Skills
How CUGA discovers and runs SKILL.md playbooks — architecture, Anthropic PPTX example, and build-your-own walkthrough
Agent Skills
Agent skills are reusable instruction packs. Each skill is a folder with SKILL.md (YAML frontmatter + markdown body) and optional helper scripts.
CUGA discovers skills at startup, lists short descriptions in the agent prompt, and exposes load_skill so the model pulls the full playbook only when a task matches — keeping the system prompt small.
Reusable playbooks
Capture domain workflows once, then reuse them across tasks.
On-demand context
Load full skill instructions only when the task needs them.
Sandbox-ready assets
Ship scripts with the skill; CUGA copies them into /workspace/skills/ for run_command.
How CUGA works with skills
| Step | What happens |
|---|---|
| Discovery | CUGA scans one configured root for **/SKILL.md, reads name + description from frontmatter |
| Prompt | Short skill summaries appear in the system prompt; full body is not inlined |
load_skill | Model calls the tool when the task matches a skill description; full markdown body is injected |
| Sandbox copy | Skill folder (scripts, templates) is copied to /workspace/skills/<name>/ |
| Execution | Agent follows the skill playbook using filesystem + shell tools in the sandbox |
| Uploads | JSON dropped in /chat lands in /workspace/uploads/ (thread-scoped) for skills that need data |
Where skills live
CUGA scans one directory — no merge across paths. Default is the CUGA-native layout:
.cuga/skills/<skill-name>/SKILL.mdConfigure in src/cuga/settings.toml:
[skills]
enabled = true
root = "cuga" # defaultskills.root | Path | When to use |
|---|---|---|
cuga (default) | .cuga/skills/ | Recommended — keeps skills with CUGA policy, workspace, and uploads |
agents | .agents/skills/ | If you prefer to leave skills where npx skills installs them |
global_agents | ~/.config/agents/skills/ | Global npx skills -g |
global_cuga | ~/.config/cuga/skills/ | Legacy global CUGA path |
Override at runtime: export SKILLS_ROOT=agents
The skills CLI with -a universal writes to .agents/skills/, not .cuga/skills/. After installing, move or copy the skill folder into .cuga/skills/ (see the PPTX example tab), or set root = "agents".
Quick start
From the CUGA repository root:
cuga start demo_skillsOpen http://localhost:7860/chat. The Skills panel lists discovered skills; load_skill is available when [skills] enabled = true.
demo_skills enables skills and shell tooling for that run. Default sandbox is sandbox_mode = "native" (macOS sandbox-exec; falls back to local on other platforms).
Configuration
[skills]
enabled = true
root = "cuga"
[advanced_features]
enable_shell_tool = true # required for run_command / skill scripts
sandbox_mode = "native" # "native", "opensandbox", "e2b", or "local"
[policy]
enabled = true # tool approvals; recommended with shell tools| Setting | Use |
|---|---|
skills.enabled | Skill discovery, load_skill, /api/skills, sandbox skill upload |
skills.root | Single skills directory to scan |
advanced_features.enable_shell_tool | run_command, write_file, and skill helper scripts |
advanced_features.sandbox_mode | Where shell-style tools execute |
policy.enabled | Policy system including tool approvals |
Use sandbox_mode = "local" only in trusted dev environments. Pair with tool approval.
Sandbox backends
Default on macOS — good for local development.
cuga start demo_skillsDocker or remote isolation; skill files are synced into the sandbox workspace.
uv sync --extra opensandbox
cuga start demo_skills[advanced_features]
sandbox_mode = "opensandbox"Runs on the host — trusted environments only.
[advanced_features]
sandbox_mode = "local"
enable_shell_tool = trueAnthropic PPTX skill
The Anthropic skills repo includes a pptx skill for creating, reading, and editing PowerPoint files.
npx skills add https://github.com/anthropics/skills --skill pptx -a universalThe CLI installs to .agents/skills/pptx/ (universal agent layout). CUGA’s default root is .cuga/skills/, so move the skill:
mkdir -p .cuga/skills
mv .agents/skills/pptx .cuga/skills/Your skill path should be:
.cuga/skills/pptx/SKILL.mdAlternatively, skip the move and set [skills] root = "agents" in settings.toml.
cuga start demo_skillsOpen http://localhost:7860/chat and confirm pptx appears in the Skills panel.
Create a 5-slide sales overview deck about our product roadmap.CUGA should call load_skill("pptx"), follow the skill’s instructions, and use bundled scripts from /workspace/skills/pptx/.
Use -g on the npx skills command for a global install under ~/.config/agents/skills/ — then set skills.root = "global_agents" or copy into .cuga/skills/.
Build your own skill (E2E)
Walk through authoring a skill with a helper script, configuring CUGA, using /chat, and optionally uploading JSON data.
Sample files in cuga-agent docs/examples/skills-playbook/: snapshot-report skill + sales_q1.json.
git clone https://github.com/cuga-project/cuga-agent.git
cd cuga-agent
uv sync
cp .env.example .envUncomment one provider block in .env (Groq, OpenAI, OpenAI-compatible via settings.openai.toml + OPENAI_BASE_URL, WatsonX, etc.). See Model Configuration.
# src/cuga/settings.toml
[skills]
enabled = true
root = "cuga"
[advanced_features]
enable_shell_tool = true
sandbox_mode = "native"mkdir -p .cuga/skills
cp -R docs/examples/skills-playbook/sample-skill/snapshot-report .cuga/skills/Expected layout:
.cuga/skills/snapshot-report/
├── SKILL.md
└── summarize_upload.pycuga start demo_skillsOpen http://localhost:7860/chat → Skills panel should list snapshot-report.
- Start a conversation (upload needs an active thread)
- Drag
docs/examples/skills-playbook/sample-data/sales_q1.jsononto the chat area - File appears under
/workspace/uploads/in the Workspace panel
Load the snapshot-report skill and summarize my uploaded sales JSON. Write the report to output/.The agent should load_skill, run uv run python /workspace/skills/snapshot-report/summarize_upload.py …, and write ./output/snapshot-report-<timestamp>.md.
Minimal SKILL.md (roll your own)
---
name: hello
description: Friendly greeting demo. Use when the user asks for a hello-world skill test.
---
Reply with a short greeting and one tip about CUGA skills.Save as .cuga/skills/hello/SKILL.md and restart CUGA.