Authoring Code Skills

This chapter explains how a cskill should be structured if the goal is to match the current discovery, generation, and execution contract of the Code Skills subsystem.

Descriptor Contract

The source descriptor for this family is cskill.md. It is parsed through the generic skill document parser, so ordinary markdown sections are preserved as descriptor sections. In the current Code Skills subsystem, the one section that is enforced directly at execution time is Input Format. If that section is missing, the subsystem throws an error and refuses to execute the skill.

Other sections such as Description, Summary, Output Format, Constraints, or examples remain useful because they document the public contract of the capability and can also guide generation workflows. They should not, however, be presented as mandatory runtime switches unless the code actually enforces them. The subsystem itself does not currently require a fixed list beyond the presence of Input Format.

This means that the descriptor should be written as an interface contract rather than as implementation prose. It should explain what the skill expects, what it returns, and which constraints the executable module is meant to respect.

Two Valid Layouts

The first valid layout is the specification-driven layout. In this form, the skill contains cskill.md, a specs/ directory, and the generated or regenerated runtime module under src/.

Specification-driven layout

  • skills/
    • file-system/
      • cskill.md
      • specs/
        • index.mjs.md
      • src/
        • index.mjs

The second valid layout is a maintained runtime layout in which the module under src/ already exists and is intentionally maintained directly. In that case, the skill may still be executed as a Code Skill even if the generation pass has nothing to produce.

Direct runtime layout

  • skills/
    • local-formatter/
      • cskill.md
      • src/
        • index.mjs

The practical distinction is therefore not whether the subsystem can load the module. It can do so in either case. The distinction is where maintainers are expected to apply changes: in specs/ for generation-driven skills, or in src/ for intentionally maintained direct modules.

Minimal Descriptor Example

A minimal descriptor that satisfies the current execution checks is shown below.

# file-system

## Description
Executes bounded file-system operations through a stable module.

## Input Format
- First token: operation name.
- Second token: target path.
- Remaining text: optional operation-specific parameters.

## Output Format
- Type: string or JSON string.

## Constraints
- Paths must remain inside the project workspace.

This is sufficient for discovery and for the Code Skills subsystem check that Input Format exists. A richer descriptor may add more examples or stronger constraints, but the entrypoint behavior is still defined by the runtime module under src/.