Extending with Skills
Relevant source files
The following files were used as context for generating this wiki page:
Skills in Flow are reusable instruction modules designed to extend the capabilities of AI agents. They function as versioned system prompt fragments that can be auto-created by the system's reflector node or manually authored by users. Each skill encapsulates specific behavioral rules, allowed tools, and trigger phrases, allowing agents to handle specialized tasks without bloating the primary system prompt.
The skill system follows an idempotent, append-only versioning strategy. When a skill is updated, a new version is created in the database while the previous version is deactivated, ensuring a clear historical record and the ability to roll back to prior configurations.
Sources: README.md:95-101, apps/web/src/app/(app)/agents/[id]/skills/page.tsx:143-145, services/api/scripts/seed_skills.py:10-12
Skill Architecture and Format
Skills are defined using the SKILL.md format, which combines YAML frontmatter for metadata and Markdown for the instruction body. This structure allows for both machine-readable configuration and human-readable guidance.
The SKILL.md Structure
The structure of a skill file is divided into two primary blocks:
- YAML Frontmatter: Contains administrative data such as the skill name, description, version string, allowed tools, and trigger phrases.
- Markdown Body: Contains the actual instructions, context, and examples that guide the agent's behavior.
The ParsedSkill dataclass handles the representation of these components within the application logic.
Sources: services/api/flow/application/skill_parser.py:27-41, apps/web/src/components/agents/SkillEditor.tsx:13-33
Frontmatter Fields
| Field | Type | Description |
|---|---|---|
name | String | Unique identifier for the skill. |
description | String | Explains when and how the agent should apply this skill. |
version | String | Display label for the version (e.g., "1.0"). |
allowed-tools | List | Tools the agent is permitted to use when this skill is active (e.g., retrieve, sandbox). |
triggers | List | Phrases or keywords that signal the relevance of the skill to a user query. |
metadata | Object | Arbitrary data such as author or domain. |
Sources: services/api/flow/application/skill_parser.py:27-41, services/api/scripts/seed_skills.py:26-31
Skill Parsing and Matching
The skill_parser.py module is responsible for converting raw SKILL.md strings into structured ParsedSkill objects and determining when a skill should be activated based on user input.
Activation logic uses "progressive disclosure":
- Trigger Matching: Checks if any words in the query match the defined trigger phrases.
- Name Matching: Checks if the skill name appears in the query.
- Description Matching: Checks if the first five words of the description appear in the query.
Sources: services/api/flow/application/skill_parser.py:58-96
Skill Life Cycle and Improvement
Skills are managed through a continuous improvement loop that includes manual editing, automated rewriting, and version history management.
Automated Skill Rewriting
The skill_rewriter.py module facilitates an automated loop for improving skills based on failed evaluation cases (golden sets). The rewriter uses an LLM to perform "surgical edits" to the Markdown body while preserving the YAML frontmatter and bumping the version number.
Versioning and Persistence
Every save operation on a skill creates a new version entry in the agent_skills table. The system tracks:
version: An integer incremented viaMAX(version) + 1.active: A boolean flag; only one version of a specific skill name is active per agent at a time.content_md: The full text of the skill.
Sources: services/api/scripts/seed_skills.py:756-787, apps/web/src/app/(app)/agents/[id]/skills/page.tsx:23-36
Manual Editing and UI
The SkillEditor provides a monospaced text environment for authoring skills. It includes features for overriding the frontmatter name and syntax-aware line numbering. Users can also view a SkillDiffView to compare differences between version v(n) and v(n-1).
Sources: apps/web/src/components/agents/SkillEditor.tsx:49-110, apps/web/src/app/(app)/agents/[id]/skills/page.tsx:123-140
Summary
The skill system provides a modular way to expand agent intelligence. By using the SKILL.md format, Flow ensures that instructions are both manageable for users and interpretable by the system. The integration of automated rewriting via skill_rewriter.py and structured parsing via skill_parser.py creates a robust framework for agents to learn and specialize over time.