# Agent skill

> Install the Maru skill for your coding agent and use it to create plugins, sample kits and banks.

Canonical: https://maruaudio.com/docs/skill
Documentation index: https://maruaudio.com/llms.txt

The Maru agent skill gives your coding agent a workflow for creating
plugins, sample kits and banks, generating audio, and turning recordings into
MIDI. It guides the agent through the existing SDKs and tool catalogue while
you direct the musical result.

The skill is a folder of instructions. Your project supplies the SDKs, tools
and runtime; installing the skill does not install those packages or model
weights. A supported starter or framework checkout is required to run the
development tools. For developer access, see
[Build with Maru](https://maruaudio.com/build).

## Install from GitHub

The public distribution repository is
<a href="https://github.com/maru-audio/maru-skill" target="_blank" rel="noopener noreferrer">maru-audio/maru-skill</a>. Its first skill release is being
prepared; the repository currently contains the license. Once the skill files
are published, install them with the <a href="https://github.com/vercel-labs/skills" target="_blank" rel="noopener noreferrer">Skills CLI</a>:

```bash
npx skills add maru-audio/maru-skill --skill maru-agent
```

The installer lets you choose your coding agent. Add `--global` to install for
your user account instead of the current project, or select an agent explicitly
with `--agent codex` or `--agent claude-code`.

Skill releases contain the instructions and references together. The framework
SDKs, CLI/MCP tools and inference services are installed or configured separately.
While the first release is being prepared, developers with a supplied checkout
can use the fallback below.

## Install from a framework checkout

Find `packages/maru-skill/skills/maru-agent/` in your supplied checkout. Copy the complete folder
into the skills directory used by your coding agent, including `SKILL.md` and
the `references/` directory. Keep the folder name `maru-agent`.

For example, from the framework repository root, replace the destination below
with your agent's skills directory:

```bash
MARU_SKILLS_DIR="/path/to/your/agent/skills"
mkdir -p "$MARU_SKILLS_DIR"
cp -R packages/maru-skill/skills/maru-agent "$MARU_SKILLS_DIR/"
```

Use a new destination when installing; when updating, replace the previously
installed skill folder with the complete current version. Reload your agent's
skill discovery or start a new session as required by that agent.

Ask it to load `maru-agent`. In a runtime that supports `$skill-name` invocation,
use `$maru-agent` in your prompt. Confirm that it can read the skill and its
references before asking it to modify a project.

## Try it on a local project

Open your existing module project and give the agent a bounded request:

```text
Use the maru-agent skill. Inspect this project and its available scripts.
Make the delay repeats darker as they fade, using the existing DSP leaves.
Open the development workbench, check the controls and saved state, and run
the project's checks. Summarize the changed files and verified targets.
```

Use the [Quickstart](https://maruaudio.com/docs/quickstart.md) to open a supplied starter and
[Development workbench](https://maruaudio.com/docs/dev.md) to iterate on sound and interface.
The skill supports the same local development loop; your agent still needs
access to the project files and commands.

## Choose the workflow

- **Plugins:** inspect a module's declaration, processing code, controls and
  resources, then develop and check the targets supported by that project.
- **Sample kits and banks:** extract or organize sounds, preserve their source
  information, and prepare the appropriate playable bank. A diagnostic kit
  archive and a playable sampler bank serve different purposes.
- **Audio generation:** use an available SDK connector with explicit prompts,
  seeds and settings. The host needs the configured service or local runtime.
- **Audio to MIDI:** use the SDK's finite-clip transcription APIs. The local
  Pitchy path follows one melody; it does not separate chords.

Inference, downloads and publication follow your authorization and the host's
available services. The skill does not supply credentials or make unavailable
CLI/MCP bindings executable.

## Discover the installed tools

In a framework checkout, inspect the shared operation catalogue:

```bash
node packages/agent-tools/bin/tools.mjs --help
node packages/agent-tools/bin/tools.mjs --describe
```

The CLI, MCP and programmatic tool client derive their operations from the same
definitions. Use their advertised schemas and inspect host availability before
calling an operation. Generation and transcription SDK APIs can be used
programmatically; their portable CLI/MCP inference bindings are still being
prepared.

Read [Working with coding agents](https://maruaudio.com/docs/working-with-coding-agents.md) for the
collaboration loop and [CLI](https://maruaudio.com/docs/cli.md) for local project operations.