AI Agent Workflow Skills
Relevant source files
The following files were used as context for generating this wiki page:
AI Agent Workflow Skills are discrete, versioned capabilities that agents use to perform specific tasks within the Coral ecosystem. These skills allow agents to search for operations, execute sandboxed TypeScript programs, and save successful logic as reusable functions.
Overview of Skills Architecture
Coral manages skills through a centralized locking mechanism and an Model Context Protocol (MCP) interface. Agents interact with these skills by creating tasks, searching for relevant capabilities, and executing code in an isolated environment.
Skill Management and Locking
The project uses a skills-lock.json file to track available skills, their sources, and their integrity hashes. This ensures that agents use consistent versions of tools for tasks like code review, TDD (Test-Driven Development), and codebase design.
Sources: skills-lock.json:1-125, README.md:16-24
Core Skill Components
The workflow follows a structured progression from task initiation to function persistence.
The diagram shows the lifecycle of a skill-based workflow, from task creation to saving new functions.
Sources: crates/coral-mcp/src/arguments.rs:218-261, README.md:126-150
Skill Tooling and API
The coral-mcp crate defines the specific tools available to agents. Each tool corresponds to a stage in the workflow and enforces domain-specific constraints on inputs like intent, path, and source code.
Primary Workflow Tools
| Tool Name | Purpose | Key Constraints |
|---|---|---|
start_task | Initiates a unit of work. | Intent length capped at TASK_INTENT_MAX_CHARS. |
search | Locates operations or saved functions. | Filters by provider or keywords. |
describe | Retrieves detailed schemas for a path. | Supports type expansion for complex objects. |
exec | Runs a TypeScript async-function body. | Max 64 KiB source; 15-minute timeout. |
save_function | Persists a program as a reusable skill. | Requires unique path and description. |
Sources: crates/coral-mcp/src/arguments.rs:35-180, crates/coral-mcp/tests/credential_free_tracer/input_contracts.rs:136-160
Execution Sandbox
Programs run in an isolated sandbox with the following properties:
- No Network Access: Code cannot make outbound requests directly.
- No Secrets: Agents never hold credentials; Coral adds them to calls at the gateway.
- No Imports: The TypeScript module must have one default export and no external dependencies.
Sources: README.md:25-30, crates/coral-mcp/src/arguments.rs:104-108
Domain Rules and Validations
Coral enforces strict validation rules for identifiers and code content to maintain security and stability across the workflow.
Path and Identifier Standards
Identifiers for tasks and runs use a specific format: either four or five lowercase words joined by hyphens, or a standard UUID.
The flow describes how Coral validates identifiers before processing any MCP tool call.
Sources: crates/coral-mcp/src/arguments.rs:271-285, crates/coral-mcp/tests/credential_free_tracer/input_contracts.rs:270-305
Function Persistence Logic
When an agent saves a function, Coral validates the SavedFunctionPath. The path must be a dotted string under coral.functions (e.g., reports.summarize). Certain names like prototype, constructor, and then are reserved to prevent prototype pollution in the execution environment.
Sources: crates/coral-mcp/src/arguments.rs:19-25, crates/coral-mcp/tests/credential_free_tracer/input_contracts.rs:163-185
Persistence and Lifecycle
Every skill execution (Run) is coordinated by a Run Owner. This owner manages state transitions, events, and database commits.
Run Coordination
- Atomic Writes: Domain code owns transaction choreography, while repository facets handle locking and conditional writes.
- Lease Management: A worker lease ensures only one process writes to a specific Run at a time.
- Cleanup: Runs are recorded for review in the UI, but terminal runs are eventually subject to retention policies.
Sources: AGENTS.md:15-55, README.md:31-35
Summary
AI Agent Workflow Skills provide a secure, sandboxed framework for agents to build and reuse logic. By combining MCP-based tool discovery with strict TypeScript execution rules and atomic persistence, Coral allows agents to perform complex multi-service operations while the human operator maintains control over policy and credentials.
Sources: README.md:11-45, AGENTS.md:1-10