Skills System and Bundled Resources

Relevant source files

The Skills System is a framework within Warp that enables AI agents to perform complex, multi-step tasks by providing them with a library of discoverable and executable tools. These "skills" range from internal development utilities (like adding feature flags or writing specs) to user-facing capabilities like modifying settings or interacting with the Model Context Protocol (MCP).

Skills Framework Architecture

The core of the skills system resides in app/src/ai/skills/. It manages the lifecycle of skills, including discovery via file watchers, resolution of skill definitions, and execution within the agent's context.

Skill Management and Resolution

The SkillManager is the central authority for loading and caching skills. It monitors specific directories for SKILL.md files, which serve as the definition and documentation for each skill.

  • Discovery: The system watches resources/bundled/skills/ for built-in capabilities and .agents/skills/ for repository-specific development skills.
  • Definition: Each skill is defined by a directory containing a SKILL.md file with YAML frontmatter (metadata like name and description) and a Markdown body (instructions for the AI) .agents/skills/update-skill/SKILL.md12-18
  • Resolution: When an agent needs a tool, the SkillManager resolves the natural language request to a specific skill implementation based on the metadata and descriptions provided in these files.

Data Flow: From Request to Execution

The following diagram illustrates how a natural language intent is transformed into a skill execution.

Skill Resolution and Execution Flow

"FileSystem (resources/bundled/skills/)""FileWatcher (app/src/ai/skills/watcher.rs)""SkillManager (app/src/ai/skills/manager.rs)""Agent (app/src/ai/agent/)""FileSystem (resources/bundled/skills/)""FileWatcher (app/src/ai/skills/watcher.rs)""SkillManager (app/src/ai/skills/manager.rs)""Agent (app/src/ai/agent/)""Skill file change/init""Notify and Reload""Parse SKILL.md Frontmatter""Request Skill by Name/Intent""Return Skill Definition & Prompt""Generate Tool Call""Execute(SkillArgs)"

Sources:.agents/skills/update-skill/SKILL.md, .agents/skills/update-skill/references/best-practices.md

Skill Structure and Progressive Disclosure

Skills use a tiered loading system to manage context window efficiency, ensuring the agent only processes necessary information .agents/skills/update-skill/references/best-practices.md5-11

  1. Metadata: The name (kebab-case) and description are always loaded to enable discovery .agents/skills/update-skill/SKILL.md34-45
  2. SKILL.md Body: The core instructions and workflows are loaded when the skill is triggered. These are ideally kept under 200 lines .agents/skills/update-skill/SKILL.md84-85
  3. Reference Files: Detailed technical references, schemas, or large examples are stored in a references/ subdirectory and loaded only when explicitly needed .agents/skills/update-skill/SKILL.md91-97
Component Requirement Purpose
name Kebab-case (lowercase, numbers, hyphens) Unique identifier for tool calling .agents/skills/update-skill/SKILL.md38-39
description Action verb, specific context Critical for agent-side skill discovery .agents/skills/update-skill/SKILL.md43-48
SKILL.md Markdown with YAML frontmatter Primary entry point and workflow guide .agents/skills/update-skill/SKILL.md12-15
references/ Subdirectory for complex skills Context management for domain-specific details .agents/skills/update-skill/references/best-practices.md29-40

Sources:.agents/skills/update-skill/SKILL.md, .agents/skills/update-skill/references/best-practices.md

Bundled and Development Skills

Warp utilizes two primary locations for skills depending on their target audience and purpose.

Bundled Resources

Located in resources/bundled/skills/, these are distributed with the Warp binary. They include:

  • add-mcp-server: Installs and configures new MCP servers.
  • modify-settings: Allows agents to adjust user preferences.
  • create-skill: Enables the agent to generate new skill definitions.

Agent-Assisted Development Skills

Located in .agents/skills/, these are used by the internal AI agents to manage the Warp codebase itself. Key examples include:

Skill-to-Code Mapping

Implementation Space

Skill Entity (.agents/skills/)

modifies

organizes

instruments

validates

update-skill

add-feature-flag

rust-unit-tests

SKILL.md (YAML Frontmatter)

references/*.md

app/src/ (Rust Codebase)

Sources:.agents/skills/update-skill/SKILL.md, .agents/skills/update-skill/references/best-practices.md

Specialized AI Capabilities

Beyond the standard skills framework, Warp integrates specialized crates for multimodal interaction.

Computer Use and Voice

  • computer_use: A crate dedicated to screenshot-based automation, allowing the agent to "see" the terminal state and interact with UI elements.
  • Voice Transcription: Located in app/src/ai/voice/, this handles the processing of audio input into text for natural language interaction with the agent.

Execution and Safety

When an agent executes a skill:

  1. Validation: The SkillManager validates the arguments against the schema defined in the skill's metadata.
  2. Context Injection: The skill is provided with access to AppContext and specific allowed subsystems (e.g., FileSystem, TerminalModel).
  3. Linearization: The steps taken by the skill are recorded in the AIConversation for transparency and to allow the user to audit the agent's actions.
  4. Channel Gating: Skills can be restricted based on the application's release channel (Dev, Dogfood, Preview, Stable). Most skills in .agents/skills/ are only active in the Dev channel.

Sources:.agents/skills/update-skill/SKILL.md, .agents/skills/update-skill/references/best-practices.md