> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuralcleave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Skills are Python modules NeuralCleave can write, review, and hot-load at runtime — the assistant extends itself, with a human in the loop.

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.

```python theme={null}
# ~/.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

```bash theme={null}
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](/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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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.

```bash theme={null}
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](/skills-gallery) for the full list (calendar, GitHub, Jira, Linear, Notion, weather, and more).