Code Skills

Code skills generate executable JavaScript code from detailed specifications and execute it safely. This subsystem is designed for skills that require dynamic code generation based on comprehensive functional and technical specifications, enabling complex logic without manual coding.

Descriptor Snapshot

Every code skill lives in .AchillesSkills/<domain>/<skill_name>/cskill.md. The descriptor defines the skill's purpose, input/output formats, and references the specifications folder: 

# User Profile Formatter

Formats a user's data into a readable string based on external functional specifications.

## Summary
Formats a user's data into a readable string based on external functional specifications.

## Input Format
- **user**: An object representing the user.
  - `firstName` (string): The user's first name.
  - `lastName` (string): The user's last name.
  - `age` (number): The user's age.

## Output Format
- **Type**: `string`
- **Success Example**: "Full Name: Jane Doe, Age: 25 (Adult)"
- **Error Example**: "Error: Incomplete user data provided."

## Constraints
- The generated code must handle cases where the 'user' object or its properties are null or undefined.

The cskill.md file focuses on the high-level interface while detailed implementation specifications are kept in the specs/ folder.

Note: Code skills receive only the raw prompt text at runtime. The Input Format section documents the expected structure, but the skill must parse any structured data from the prompt text itself.

Repository Layout

Code skills mirror the specs/ tree directly into runnable code under the skill root: 

my-cskill/
 ├── cskill.md           # Main skill definition
 ├── specs/              # Specification files
 │   ├── index.mjs.md     # Spec for index.mjs (main entrypoint)
 │   ├── core.js.md       # Spec for core.js (core logic)
 │   └── utils.js.md      # Spec for utils.js (utility functions)
 ├── index.mjs           # Generated entrypoint (from specs/index.mjs.md)
 ├── core.js             # Generated core module (from specs/core.js.md)
 └── utils.js            # Generated utility module (from specs/utils.js.md)

Key conventions:

Specification Files

Specification files in the specs/ folder describe the code to be generated. Each file corresponds to a JavaScript module and uses a structured format. Specifications should contain only descriptions, requirements, and examples - not actual implementation code. 

# Specification for index.js

## Function: action(context)

### Description
Formats a user object into a standardized string.

### Input
- promptText: Natural language instruction containing the user data

### Processing Logic
1. Parse the user data from promptText
2. Validate that the required fields are present
3. If validation fails, return error string
4. If validation succeeds, process data and return formatted result

### Example
```javascript
// Input:
"Format user data for Jane Doe, age 25"

// Output:
"Full Name: Jane Doe, Age: 25 (Adult)"
```

The LLM uses these specifications to generate complete, self-contained JavaScript modules. The specification describes what the code should do, not how to do it.

Important: Specification files should never contain actual JavaScript implementation code. They should only describe requirements, logic, and provide examples of expected inputs and outputs.

Code Generation Lifecycle

Code skills follow a two-phase lifecycle that separates code generation from execution:

Phase 1: Code Generation

When RecursiveSkilledAgent discovers a code skill (cskill.md), it automatically generates the executable code from your specifications using the mirror code generator and writes it directly under the skill directory.

For detailed information about how RecursiveSkilledAgent handles code skill discovery and generation, see the Agent Runtime documentation.

Phase 2: Skill Execution

When you execute a code skill, the subsystem:

  1. Passes the raw prompt text directly to the skill action
  2. Dynamically imports and executes index.mjs at the skill root
  3. Wraps primitive results in { result: value } format
  4. Returns the execution result

The generated action receives an object with promptText, plus injected llmAgent and recursiveAgent references for advanced workflows.

Key Features:
  • Automatic generation: Code is generated automatically during skill discovery
  • Single-step generation: All specs and sections combined in one LLM prompt
  • Timestamp-based caching: Only regenerates when specs change
  • Multi-file support: Can generate multiple modules from multiple spec files
  • Primitive result wrapping: Ensures consistent return format

Public API

prepareSkill(skillRecord)

Prepares the skill by generating code from specifications if needed.

executeSkillPrompt(options)

Executes the pre-generated code with the prompt text.

Example:

await subsystem.executeSkillPrompt({
    skillRecord,
    recursiveAgent,
    promptText: 'Format user data for John Doe, age 30'
});

checkIfRegenerationNeeded(skillRecord, currentSignature)

Determines if code regeneration is needed based on current state.

Error Handling

The subsystem handles various error conditions gracefully:

When to Use Code Skills

Code skills are ideal for:

Consider other skill types for:

See Also