Skill Library System
Relevant source files
The following files were used as context for generating this wiki page:
- design/skills.md (Note: While requested, the full content of this specific design file was not in the provided context; information was derived from design/evolution.md and design/integrations.md)
- src/skills/runner.ts
- src/skills/types.ts
- src/skills/manifest.ts
- src/skills/skill-tool-builder.ts (Referenced via src/skills/index.ts and src/skills/skill-tool-builder.test.ts)
- src/skills/git-ops.ts (Referenced via src/skills/runner.ts)
The Skill Library System is a modular architecture within Cogmo that enables the agent to extend its own capabilities by writing and executing reusable code tools. It represents Stage 2 of the project's Self-Evolution ladder, moving beyond simple instruction evolution to autonomous code creation and tool registration. This system allows the agent to handle repeated multi-step tasks by authoring scripts that are then registered as first-class tools available in the agentic loop.
The system is built around a "Git-backed" library where skills are stored as code and descriptive manifests. It employs a two-tier runtime environment supporting both lightweight WebAssembly (WASM) execution and full-featured containerized sandboxes for higher-risk or resource-intensive tasks.
Sources: design/evolution.md:20-24, src/skills/runner.ts:133-145, design/integrations.md:38-42
System Architecture
The Skill Library architecture manages the lifecycle of a skill from authoring and registration to execution and auditing. It utilizes a Git repository (typically a bare repo at $COGMO_SKILLS_PATH) as the authoritative source of truth for skill code and metadata.
Data Flow and Components
The system follows a structured pipeline:
- Authoring: The agent or user writes
SKILL.md(manifest) andskill.py(logic). - Registration: The
SkillRunnerparses the manifest, classifies the risk tier, and merges the branch into the main skills repository. - Discovery: During the agent's turn,
SkillRunner.listToolDefs()reads live manifests to buildToolSpecobjects for the LLM. - Invocation: When triggered, the runner validates inputs against the manifest's JSON Schema and dispatches the task to the appropriate runtime tier.
The following diagram illustrates the lifecycle of a skill deployment and execution:
Skill Manifests and Types
Every skill must include a SKILL.md file featuring a YAML frontmatter block. This manifest defines the skill's identity, execution requirements, and security constraints.
Manifest Schema
The SkillManifestSchema enforces the structure of the YAML frontmatter:
| Field | Type | Description |
|---|---|---|
name | string | Lowercase name (max 64 chars) starting with a letter. |
tier | enum | wasm (Tier-1) or container (Tier-2). |
inputs | object | JSON Schema defining the tool's parameters. |
effects | array | Declared side effects (e.g., writes_memory, sends_message). |
resources | object | Optional limits for memory_mb, cpu_shares, and wall_clock_s. |
Sources: src/skills/types.ts:131-158, src/skills/manifest.ts:25-56
Input and Output Validation
The system uses Ajv to compile and execute JSON Schema validation for both inputs and outputs.
- Inputs: Validated before the skill starts to prevent malformed data from reaching the runtime.
- Outputs: Validated after execution to ensure the skill adheres to its contract before the result is returned to the agent.
Sources: src/skills/runner.ts:742-762, src/skills/runner.ts:1090-1115
Runtime Tiers
Cogmo implements a two-tier execution model to balance performance, isolation, and capability.
Tier-1: WASM (Pyodide)
Used for lightweight, stateless Python logic. It runs within a WebAssembly-based CPython environment (Pyodide).
- Isolation: Single-heap WASM.
- Characteristics: Zero idle cost, fast cold starts (~1-5ms).
- Limitation: No subprocess spawning or direct network access without host capabilities.
Tier-2: Container (Sysbox)
Used for resource-intensive tasks or those requiring full OS access. It utilizes a sysbox-runc runtime for enhanced isolation.
- Isolation: Full container sandbox.
- Pool Management: Uses a
SysboxWorkerPoolto maintain warm containers, reducing cold starts. - Resource Control: Supports specific CPU and memory limits defined in the manifest.
Sources: src/skills/types.ts:122-126, src/skills/runner.ts:80-92, design/integrations.md:46-52
Security and Permission Tiers
The system uses a risk classifier to determine the riskTier of a skill based on its declared effects and runtime requirements.
| Risk Tier | Requirement | Examples |
|---|---|---|
| auto | No destructive effects | reads_memory, reads_filesystem |
| notify | Idempotent writes | writes_memory, writes_filesystem |
| approve | Destructive/External | sends_message, financial, tier: container |
Skills in the approve tier require a human-in-the-loop gate via waitForEvent() (e.g., a Telegram callback button) before they can be promoted to live status.
Sources: src/skills/types.ts:5-18, src/skills/types.ts:178-185, changelog.d/2026-04-30-skills-hardening-eight-review-comment.md
Exactly-Once Invocation (Idempotency)
The SkillRunner implements a Stripe-pattern state machine to handle retries and prevent double-execution of non-idempotent side effects.
Recovery State Machine
The recovery_point field on a skill run tracks its progress:
- started: Execution has begun.
- executed: Execution finished; output is captured but not yet returned.
- finished: Terminal state; result is validated and finalized.
Conclusion
The Skill Library System provides a robust framework for agentic self-extension. By combining Git-based version control, multi-tier execution environments, and a strict human-in-the-loop approval process for high-risk actions, it allows Cogmo to evolve its capabilities safely and effectively. The integration of JSON Schema validation and idempotency keys ensures that dynamically authored tools maintain high reliability and predictable behavior within the agent's cognitive loop.