Agent Skills Framework
Relevant source files
The following files were used as context for generating this wiki page:
The Agent Skills Framework in pi-digby provides a structured mechanism for extending the assistant's capabilities through reusable Command Line Interface (CLI) tools. These "Skills" allow the agent to perform recurring tasks such as interacting with external APIs, processing data, or managing coding sessions. Skills are defined as directories containing scripts and metadata, which the agent can discover and execute dynamically within its environment.
Sources: src/agent/prompt.ts:100-102, src/agent/skills.ts:1-5
Skill Architecture and Discovery
Skills are organized hierarchically and discovered from two primary locations: the global workspace directory and channel-specific directories. This structure allows for a mix of universal tools available to all agent instances and specialized tools tailored for specific Slack or Linear communication channels.
Directory Structure
Skills must follow a specific filesystem layout to be recognized by the framework:
- Global Skills: Located in
${workspacePath}/skills/ - Channel Skills: Located in
${channelDir}/skills/
When a name collision occurs between a global skill and a channel skill, the channel-specific version takes precedence, allowing for localized overrides of global behavior.
Sources: src/agent/skills.ts:17-40, src/agent/prompt.ts:105-107
Skill Metadata (SKILL.md)
Every skill requires a SKILL.md file located in its root directory. This file uses YAML frontmatter to define mandatory attributes used by the agent to understand and invoke the skill.
| Field | Type | Description |
|---|---|---|
name | String | Required. The unique identifier for the skill. |
description | String | Required. A short summary of what the skill does, presented to the LLM. |
Sources: src/agent/prompt.ts:110-120, skills/claude-code/SKILL.md:1-5
Discovery Logic
The loading process involves merging global and channel-specific tools into a single map.
The discovery logic ensures that diagnostics (errors or warnings) encountered during the loading of either directory are logged, but do not necessarily halt the entire agent initialization.
Sources: src/agent/skills.ts:20-42
Skill Integration and Execution
Once loaded, skills are integrated into the agent's system prompt and execution loop. This allows the LLM to understand what tools are available and how to call them via the host machine's shell.
Prompt Integration
Available skills are formatted and injected into the system prompt using formatSkillsForPrompt. The prompt includes instructions on how to create new skills, including the use of the {baseDir} placeholder, which dynamically resolves to the skill's directory path at runtime.
Sources: src/agent/prompt.ts:122-124, src/agent/setup.ts:114-118
Execution Flow
Skills are essentially wrappers around CLI commands. When the agent decides to use a skill, the AgentSession manages the execution through a bash interface.
The system captures tool execution start and end events, tracking duration and success/failure status, which are then reported back to the user interface (Slack or Linear).
Sources: src/agent/events.ts:98-130, src/agent/setup.ts:190-210
Example Implementation: Claude Code
The claude-code skill demonstrates a complex implementation of the framework. It delegates coding tasks to a Claude Code session, managing its own worktree and lifecycle.
Workflow Configuration
The skill defines a multi-step process for coding delegation:
- Prepare: Create a task directory under
{baseDir}/tasks/. - Prompt: Write the task context to a
prompt.mdfile. - Execute: Run
claude -pwith flags such as--dangerously-skip-permissionsand--output-format json. - Verify: Check exit codes and parse the resulting
result.json.
Sources: skills/claude-code/SKILL.md:16-65
Skill Constraints and Authentication
Skills can also define their own operational limits and authentication requirements. For instance, the claude-code skill includes a cost cap (default $5) and requires a long-lived token stored in ~/.claude/ on the persistent EFS volume.
Sources: skills/claude-code/SKILL.md:79-106, CLAUDE.md:12-18
Summary
The Agent Skills Framework is a decentralized and extensible system that empowers the pi-digby agent to interact with its environment. By leveraging a simple filesystem-based discovery mechanism and standard YAML/Markdown metadata, developers can create complex, stateful tools that the agent can utilize to perform engineering and automation tasks across different channels.
Sources: src/agent/skills.ts, src/agent/prompt.ts