Skip to content
LogoLogo

Creating Skills

Skills are reusable instructions that sandbox agents can load when a task matches the skill's purpose. They are not API tools and they do not grant new network access by themselves. Use them for repeatable procedures, repo-specific operating knowledge, QA playbooks, investigation steps, or formatting rules.

Users can author a skill's name, description, and Markdown instructions from the Console Skills page. Console generates the complete SKILL.md when an agent reads it. Private skills are available only to that user's Console principal. Shared skills are available to every principal and update immediately when their author saves them. New skills are public by default and can be made private from their detail page.

Builtin organization skills live in an overlay repo under .agents/skills/. See Using an overlay for packaging, mount paths, and chart configuration.

Skills are loaded from CENTAUR_SKILL_DIRS in the sandbox. In a repo-cache overlay deployment, they must exist under the source's skillsSubdir, which defaults to .agents/skills/, in the sandbox repo checkout, for example /home/agent/github/your-org/centaur-overlay/.agents/skills. The sandbox entrypoint copies those skills into the agent workspace during startup; a source without the directory is skipped.

Write SKILL.md

Keep the entrypoint concise and action-oriented:

---
name: incident-response
description: Investigate production incidents, failed rollouts, and service outages.
---
 
# Incident Response
 
Use this skill when investigating a production incident, failed rollout, or
service outage.
 
## Workflow
 
1. Identify the affected service, namespace, and timeframe.
2. Check rollout history and current pod health.
3. Inspect logs around the first failure.
4. State root cause, blast radius, and recovery path.

Add references only when they save context. Put long runbooks in references/, scripts in scripts/, and examples in examples/.

Console-authored skills contain only the generated SKILL.md. Keep skills with supporting scripts/, references/, or assets in the overlay repository.

What Belongs In A Skill

Good skills:

  • encode a repeated workflow
  • say when they should be used
  • point at local scripts or references
  • keep the first page short
  • avoid secrets and credentials

Avoid using skills for tool credentials, API clients, or durable automation. Those belong in tools, secret configuration, and workflows.

Discover Skills

Agents can search Console-authored skills through the catalog command:

centaur-skills search "investigate a failed rollout"
centaur-skills read customer-research
centaur-skills read skl_example
centaur-skills list --scope shared

The CLI reads Console skills by exact name or skl_ OID through iron-proxy using the sandbox's existing entitlement token. Names use lowercase letters, numbers, and hyphens, so they cannot conflict with the underscore in an OID. Builtin skills remain separate: the sandbox mounts them from the overlay and the agent's native skill loader discovers them directly. A skill never adds credentials or grants.

Author Skills From A Sandbox

Console users can create shared skills and edit skills they own from a sandbox:

centaur-skills create deployment-checks \
  --description "Check a deployment before declaring it healthy." \
  --instructions-file instructions.md
centaur-skills edit skl_example \
  --description "Check and diagnose deployments." \
  --instructions-file updated-instructions.md
centaur-skills delete skl_example

Use --instructions instead of --instructions-file for a short inline Markdown body. edit accepts partial changes and targets skills by OID. Pass the current lock_version with --lock-version when an edit should fail if another writer changed the skill first. Newly created skills are public and edits to public skills are visible to agents immediately. delete archives an owned skill by OID, removing it from the active catalog without deleting its stored record.

Verify Builtin Skills

Start an agent with the overlay loaded and ask it to inspect available skills. For a running sandbox, the agent can confirm overlay state with:

echo "$CENTAUR_SKILL_DIRS"
find /workspace/.agents/skills -maxdepth 2 -type f -name SKILL.md | sort

If a skill is missing, check the configured repo/ref, the rendered CENTAUR_SKILL_DIRS, and that the skill directory contains SKILL.md.