Skill System Overview

This overview explains how Achilles Agents organises skills, repositories, and execution layers into a coherent orchestration platform.

Design Philosophy

The library embraces a declarative skill graph approach: skills declare their capabilities, orchestration scripts or planners compose them, and agents interpret user intent through iterative, human-in-the-loop conversations.

Composability: Skills may invoke other skills or MCP tools through LightSOPLang.
Auditability: Plans are explicit (scripts or JSON), enabling deterministic replays.
LLM-Augmented Determinism: Language models handle fuzzy interpretation, while the execution environment enforces type safety, validation, and access control.
Skill Families: Each class of skill (interactive, orchestration, MCP, code) focuses on a particular way of helping the user.

High-Level Architecture

The ecosystem revolves around four collaborating layers:

Skill Registry: Maintains metadata, argument schemas, enumerators, and access policies.
Interactive Skill Flow: Guides conversational argument acquisition and validation.
Orchestration Skills: Translate LightSOPLang scripts or LLM plans into sequenced actions.
Execution Agents: LLMAgent mediates with language models; RecursiveSkilledAgent supervises nested plans and cancellations.

The flow aligns with the runtime architecture:

RecursiveSkilledAgent
  ├─ Skill Discovery: scan .AchillesSkills/* for skill.md, cgskill.md, iskill.md, mskill.md, oskill.md, tskill.md
  ├─ Subsystem Router: claude | code | interactive | mcp | orchestrator | dbtable
  ├─ LLMAgent: shared completion/review + session memory
  └─ Execution: plan (LightSOPLang or LLM) → run skill → record history

Skill Repository Conventions

Achilles Agents skills are stored as Markdown descriptors inside a .AchillesSkills/ directory. Each skill lives in its own folder and is identified by the folder name:

.AchillesSkills/<domain>/<skill_name>/
    ├── skill.md | iskill.md | oskill.md | mskill.md | cgskill.md | tskill.md   (descriptor)
    └── <skill_name>.mjs / .js                          (entrypoint when the family supports it)

The descriptor suffix maps to the skill family:

skill.md — Claude (static) skills that surface metadata only.
iskill.md — interactive conversational skills.
tskill.md — DBTable skills that describe CRUD workflows over structured tables.
oskill.md — orchestration planners that may embed LightSOPLang scripts.
mskill.md — MCP skills with allowed tool lists and optional scripts.
cgskill.md — code-generation skills with detailed prompts and LLM guidance.

Interactive skills require a JavaScript module exporting specs and action; other families may provide optional modules (for example, cgskill modules supply an action executor, while tskill code is generated into tskill.generated.mjs). Modules can also export a roles array which is recorded for future policy hooks, but it is not enforced by the runtime today.

Skill Lifecycle

Declaration: Skill descriptors capture arguments, hints, and optional LightSOPLang sections; modules add executable hooks and optional (currently informational) roles metadata.
Registration: Metadata is normalised; enumerators, validators, and resolvers are bound.
Selection: Requests route to orchestration scripts, static mappings, or LLM planners.
Execution: Skill engines govern runtime behaviour (interactive prompts, MCP tool invocations, code evaluation).
Post-processing: Presenters shape confirmations, and results feed session memories or review pipelines.

Skill Families

Each family focuses on a distinct flavour of work:

Claude Skills: Static descriptors (skill.md) that surface summaries and body content without LLM execution.
Interactive Skills: Conversational flows with validation, placeholder detection, and natural language extraction.
DBTable Skills: Table-centric CRUD operations defined in tskill.md, with automatic argument collection and Persisto integration.
Orchestration Skills: LightSOPLang-driven script execution for high-level plans, including fallback behaviour.
MCP Skills: Tool-centric skills that interface with external Model Context Protocol servers.
Code Skills: Evaluate snippets or pipelines under strict sandboxing with deterministic feedback.

These components are composable—an orchestration script may trigger interactive skills for data gathering, then execute MCP skills for external calls or code skills for verification.

Dive deeper into each family: explore Interactive Skills, learn how table descriptors become CRUD workflows in DBTable Skills, continue with Orchestration Skills, review MCP Skills, and finish with the Code Generation Skills guide.

ReAct-Aligned Planning

The system embraces the ReAct pattern (Reasoning + Acting) by isolating reasoning inside LightSOPLang or LLM plan selection, then performing atomic actions via explicit commands. This separation makes debugging easier, ensures deterministic replay, and keeps all external calls auditable.