Skills

Skills are the extension mechanism that makes NeuralCleave self-modifying. Each skill is a Python module at ~/.neuralcleave/skills/<name>/skill.py.

Anatomy of a skill

A skill module contains either plain functions, auto-wrapped as tools, or an explicit Plugin subclass for full control over metadata and lifecycle hooks.

# ~/.neuralcleave/skills/celsius_to_fahrenheit/skill.py

def celsius_to_fahrenheit(celsius: float) -> str:
    """Convert a Celsius temperature to Fahrenheit."""
    fahrenheit = celsius * 9 / 5 + 32
    return f"{celsius}°C is {fahrenheit}°F"

Every top-level, non-underscore-prefixed callable becomes a tool the agent can invoke. The function’s docstring becomes the tool description. Blocked imports (subprocess, ctypes, winreg, msvcrt, pty, tty, termios, fcntl) are rejected at write/proposal time.

Two ways a skill gets written

1. You write it — immediate, trusted

neuralcleave skills write celsius_to_fahrenheit --file code.py
neuralcleave skills validate code.py   # check syntax + blocked imports first, without writing

Writes to disk and hot-loads immediately. This is the trusted path — for code you wrote yourself, or installed from the Skills Gallery.

2. The agent writes it — proposed for review

When the agent itself calls the write_skill tool during a conversation, the code is validated and queued as a pending proposal — not written to disk or loaded. A human decides:

neuralcleave skills review pending
neuralcleave skills review show <id>
neuralcleave skills review approve <id>    # now writes to disk, loads, and wires its tools in
neuralcleave skills review reject <id>     # never written to disk

or via REST:

curl http://localhost:7432/api/v1/skills/review/pending
curl -X POST http://localhost:7432/api/v1/skills/review/<id>/approve
curl -X POST http://localhost:7432/api/v1/skills/review/<id>/reject

This review gate exists because agent-authored code running immediately, with no review step, is a real trust boundary — not a hypothetical one.

Managing installed skills

neuralcleave skills list
neuralcleave skills show <name>
neuralcleave skills delete <name>            # removes the file permanently
neuralcleave skills quarantine <name>        # unloads without deleting — file stays for inspection

A quarantined skill can be restored by re-running skills write with the same name — that clears the quarantine flag.

curl -X POST http://localhost:7432/api/v1/skills/<name>/quarantine

Multi-step tool chains

Skills participate the same way any tool does in multi-step tool chains — the pipeline calls a tool, feeds the result back to the LLM, which can call another tool, up to max_tool_steps (default 5) per turn.

Example conversation

User: Create a skill that converts Celsius to Fahrenheit.
NeuralCleave: I've proposed the skill 'celsius_to_fahrenheit' for review
              (id=a1b2c3d4). A human must approve it before it can run.

Approving it (neuralcleave skills review approve a1b2c3d4) writes the file, loads it, and makes celsius_to_fahrenheit callable in the very next turn.

Skills gallery

~/.neuralcleave/skills/ can also be seeded from the bundled example skills — see Skills Gallery for the full list (calendar, GitHub, Jira, Linear, Notion, weather, and more).

Getting Started

Core Concepts

Voice

Operations

Changelog

Anatomy of a skill

Two ways a skill gets written

1. You write it — immediate, trusted

2. The agent writes it — proposed for review

Managing installed skills

Multi-step tool chains

Example conversation

Skills gallery

​Anatomy of a skill

​Two ways a skill gets written

​1. You write it — immediate, trusted

​2. The agent writes it — proposed for review

​Managing installed skills

​Multi-step tool chains

​Example conversation

​Skills gallery

Anatomy of a skill

Two ways a skill gets written

1. You write it — immediate, trusted

2. The agent writes it — proposed for review

Managing installed skills

Multi-step tool chains

Example conversation

Skills gallery