Skill & Agent Management
Relevant source files
The following files were used as context for generating this wiki page:
Skill & Agent Management is the core pillar of the bl1nk platform, providing a specialized environment for creating, orchestrating, and testing AI capabilities. Skills serve as modular, self-contained prompt templates that extend an agent's specialized knowledge and workflows, effectively transforming a general-purpose model into a domain expert.
The system supports a hierarchical structure where Skills (structured prompt definitions) are composed into Agents (orchestrated workflows with tool access and decision-making logic). This management system handles the full lifecycle of these artifacts, from initialization using standard templates to version-controlled persistence and multi-provider testing.
Sources: skill/skill-creator/SKILL.md:10-15, specs/002-skill-ide-core/spec.md:20-35, Comprehensive.md:73-77
Skill Architecture and Anatomy
A Skill in the bl1nk platform is defined by a specific directory structure. The mandatory entry point is a SKILL.md file containing YAML frontmatter for metadata and a Markdown body for instructions. Optional bundled resources allow for deterministic scripts, reference documentation, and output assets.
File Structure Layout
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter (name, description, etc.)
│ └── Markdown instructions
├── scripts/ - Executable code (Python/Bash)
├── references/ - Knowledge loaded into context
└── assets/ - Output templates/icons
Sources: skill/skill-creator/SKILL.md:21-35, skill/agent_skills_spec.md:5-15
Progressive Disclosure Principle
The system utilizes a three-level loading system to manage the context window efficiently during AI interactions:
- Metadata: The
nameanddescriptionare always in context to trigger selection. - SKILL.md Body: Loaded only when the specific skill is triggered.
- Bundled Resources: Scripts and references are loaded on-demand as needed by the model.
Sources: skill/skill-creator/SKILL.md:85-95
Skill Lifecycle and Management
The management system provides standardized workflows for creating, validating, and versioning skills.
Creation and Packaging Flow
The platform provides automation scripts to ensure skills meet the required specifications before distribution.
The packaging process automatically validates YAML frontmatter format, required fields, and directory structure.
Sources: skill/skill-creator/SKILL.md:139-150, skill/skill-creator/SKILL.md:183-200
Versioning and Persistence
Skills are persisted in a database (SQLite in Phase 1) with full version history tracking. Each save operation creates a new version, allowing users to view history and restore previous states.
| Entity | Description | Fields |
|---|---|---|
| Skill | Primary skill record | id, name, description, currentVersion |
| SkillVersion | Specific snapshot of a skill | id, skillId, content, createdAt |
Sources: Comprehensive.md:73-77, specs/001-skill-builder-core/tasks.md:23-35
Agent Orchestration
Agents represent a higher level of orchestration, combining multiple skills with execution parameters and Model Context Protocol (MCP) tool access.
Agents are configured via YAML and can include references to available skills, allowing them to leverage specific procedural knowledge across different domains.
Sources: specs/002-skill-ide-core/spec.md:95-105, Comprehensive.md:73-77
API and Schema Definition
The management of skills is exposed through a tRPC API (handled by skill.router.ts) and validated using Zod schemas.
Core API Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
skill.list | Query | Retrieves all skills for the current workspace |
skill.getById | Query | Fetches a specific skill and its content |
skill.create | Mutation | Initializes a new skill record |
skill.update | Mutation | Saves changes and increments version |
skill.delete | Mutation | Removes the skill from the database |
skill.getVersions | Query | Retrieves the version history for a skill |
skill.restoreVersion | Mutation | Reverts a skill to a previous state |
Sources: apps/server/src/routers/skill.router.ts:28-45, specs/001-skill-builder-core/tasks.md:105-115
Data Validation Schema
// Simplified Skill Schema
const SkillSchema = z.object({
id: z.string().uuid(),
name: z.string().regex(/^[a-z0-9-]+$/),
description: z.string().min(1),
content: z.string(),
version: z.number().int().default(1)
});
Sources: packages/shared/src/schemas/skill.schema.ts:1-20, skill/agent_skills_spec.md:25-35
Categorization Standards
To maintain organization within the IDE, the system categorizes artifacts into functional groups. Pre-built agents are organized into several target states:
- Development: Coding and testing agents.
- Writing: Content and translation agents.
- Business: Marketing and consulting agents.
- Education: Tutoring agents.
- Creative: Art and design agents.
Sources: Comprehensive.md:235-245, specs/002-skill-ide-core/spec.md:55-70
The Skill & Agent Management system ensures that AI specialized capabilities are not just prompts, but managed software assets with defined structures, rigorous validation, and clear execution paths. This structured approach allows the bl1nk platform to maintain high reliability and context efficiency when deploying AI agents to complex tasks.