Skill Management#

Overview#

A skill is a packaged unit of agent behavior: a named Markdown body paired with optional bundled files (scripts, configs, references). Skills are defined in SKILL.md format, attached to an agent config, resolved server-side, materialized on disk by the runner, and discovered by Pi at execution time.

The skill system was introduced across the SDK, API, and runner in PR #4814 1, with bundled file storage and runtime execution added in PR #4782 2.

SKILL.md Format#

A SKILL.md file is a YAML frontmatter block followed by a Markdown body:

---
name: release-notes
description: Draft release notes from a changelog.
allowed-tools: Read, Bash
disable-model-invocation: false
---

Read the changelog, then write release notes...

Frontmatter fields 1 3:

The body (everything after ---) can be up to 50,000 chars. Skills can also declare auxiliary files with path, content, and an optional executable flag 1.

SDK Layer#

Python skill models live in sdks/python/agenta/sdk/agents/skills/ 1:

• models.py — SkillConfig (name, description, body, files, flags) and SkillFile (path, content, executable). SkillFile.path rejects absolute paths, parent-directory escapes, and collisions with SKILL.md.
• parsing.py — parse_skill_config() / parse_skill_configs() validate inputs and raise SkillConfigurationError with indexed diagnostics.
• wire.py — skills_to_wire() serializes SkillConfig objects to the camelCase wire format consumed by the runner.
• errors.py — SkillConfigurationError with message, optional index, and value.

Skills are added to AgentConfig and HarnessAgentConfig via a skills field. Inline skills can be written directly; @ag.embed references to is_skill workflows are resolved server-side by ResolverMiddleware before the runner receives them 1.

API Layer#

There are no dedicated skill endpoints. Skills flow through the existing workflow catalog and config APIs 1.

Platform/static skills are defined in api/oss/src/core/workflows/platform_catalog.py under the reserved _agenta.* slug namespace, with deterministic UUIDs for stable cross-instance identity. Three build-flow platform skills — __ag__build_your_first_app, __ag__discover_and_wire_tools, and __ag__set_up_triggers — use the reserved __ag__ slug prefix and were added in PR #4930 4. A ReservedWorkflowSlugException (HTTP 400) prevents user workflows from shadowing these reserved prefixes.

Runner: Materialization and Execution#

Skills Engine (services/agent/src/engines/skills.ts)#

Introduced in PR #4814 1, this TypeScript engine transforms resolved inline skill packages into on-disk directories:

1. Creates a per-run temp root directory.
2. For each skill: validates the name (rejects ../, non-alphanumeric), composes SKILL.md with YAML-escaped frontmatter (:, #, " are quoted), writes bundled files, and optionally chmod +x executable files.
3. Triple-gated executable policy: skill opt-in (allowExecutableFiles=true) + file opt-in (executable=true) + caller policy (default deny).
4. Deduplicates by name (later duplicates are skipped); unsafe file paths are logged and skipped rather than aborting the run.
5. Returns { name, dir }[] plus a cleanup() callback called in a finally block.

Bundled ("Forced") Skills#

Bundled skills are static directories under services/runner/skills/ (volume-mounted in dev) 5. The resolveSkillDirs() function maps skill names to these directories; the root is overridable via AGENTA_AGENT_SKILLS_DIR 2.

The Agenta harness injects a fixed skill set into every pi_agenta run. Internally it maps agenta → pi for the rivet/ACP backend while preserving agenta as the user-facing identity in logs and traces 2.

Skill Path Stability on Cold Resume#

PR #5295 6 fixed cold-resume failures caused by skill paths changing after sandbox teardown.

Root cause: skills were copied into a random per-run directory deleted at teardown, leaving dangling paths on resume.

Fix: skills are now stored as content-addressed snapshots at a stable path:

<cwd>/agents/skills/<digest>/<skill-name>

The digest is computed from skill names, file paths, modes, and contents. Snapshots are published atomically via a staging directory + completion marker and are never deleted (append-only) until the session workspace itself is removed. pi-acp reads the path via PI_CODING_AGENT_SKILL_DIR 6.

Local Pi vs. Daytona Sandboxes#

2

Frontend: Skill Upload UI#

The skill editor lives in web/packages/agenta-entity-ui/ — a separate package from the OSS web/oss/ app. It was introduced in PR #4850 7 and extended with drawer-based editing in PR #4881 8.

Key components (all under web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/):

The skill editor mirrors the Tools and MCP section pattern: compact summary in the config panel, full editing in a right-hand drawer.

Paste-a-SKILL.md#

PR #5258 9 added drawer-wide paste support — the primary workaround for remote machines where drag-and-drop is unavailable:

• A document-level paste listener on the drawer ignores pastes when any text input is focused.
• Detects a SKILL.md by a leading --- frontmatter delimiter; non-matching pastes fall through.
• Calls mergePastedSkill(), which runs parseSkillMarkdown() and updates name, description, and body — but never modifies bundled files.
• Shows a toast: "Filled from the pasted skill." UI hint: "…or paste a SKILL.md anywhere here to fill the fields."

Key Source Locations#

Related PRs#