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.

Repository Layout

Code skills follow a simplified folder structure that separates specifications from generated code: 

my-cskill/
├── cskill.md           # Main skill definition
├── specs/              # Specification files
│   ├── index.js.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)
└── src/                # Generated code (auto-created)
    ├── index.mjs        # Generated entrypoint
    ├── core.js          # Generated core module
    └── utils.js         # Generated utility module

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(args)

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

### Input
- args: Object containing user data
  - user: Object representing the user
    - firstName (string, mandatory): The user's first name
    - lastName (string, mandatory): The user's last name
    - age (number, mandatory): The user's age

### Processing Logic
1. Receive the user object from args.user
2. Validate that the user object and all its mandatory properties are present
3. If validation fails, return error string
4. If validation succeeds, process data and return formatted result

### Example
```javascript
// Input:
{
  "user": {
    "firstName": "Jane",
    "lastName": "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 and writes it to the src/ folder.

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. Extracts arguments from your prompt (or uses pre-provided arguments)
  2. Dynamically imports and executes src/index.mjs
  3. Wraps primitive results in { result: value } format
  4. Returns the execution result
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
  • Pre-provided args support: Can skip argument extraction when called programmatically
  • 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 provided arguments.

Example with pre-provided args:

await subsystem.executeSkillPrompt({
    skillRecord,
    recursiveAgent,
    promptText: 'Format this user',
    options: {
        args: {
            user: { firstName: 'John', lastName: '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