> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0).
> Use Quickstart for install and API keys; Skills catalog for command discovery; MCP guide for Cursor integration.
> Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka.

# Installing and building Arka plugins

> Extend Arka by installing third-party plugin skills into ~/.config/arka/skills/ with skill.json trigger files that hook into the router.

Extend Arka with third-party skills installed to `~/.config/arka/skills/`.

Arka also provides a universal plugin registry. Existing Arka manifests remain
supported, while Claude/Codex-style folders, MCP-backed plugins, and executable
plugin repositories are normalized into the same catalog and execution path.

## Install a plugin

```bash theme={null}
arka skills install https://github.com/user/my-skill.git
arka skills refresh
arka skills list
arka plugin doctor
arka plugin inspect my_skill
arka plugin search browser
```

`plugin` and `plugins` are lifecycle aliases; `skills` remains compatible with
older installations.

## Plugin compatibility

| Source                                            | Detection                                      | Default adapter  |
| ------------------------------------------------- | ---------------------------------------------- | ---------------- |
| Arka `skill.json`, `manifest.json`, `plugin.json` | manifest in a plugin directory                 | Arka manifest    |
| Claude/Codex skill                                | `SKILL.md` or `README.md`                      | external skill   |
| Executable repository                             | `run.py`, `main.py`, `run.sh`, or `index.js`   | executable       |
| MCP server                                        | MCP server entry in the configured MCP catalog | MCP tool adapter |

Inspect the normalized descriptor before enabling an unfamiliar plugin:

```bash theme={null}
arka plugin inspect my_skill
arka plugin doctor
```

The descriptor reports its adapter, source, entrypoint, capabilities,
requirements, permissions, health, and any trigger conflicts. Conflicting or
unavailable plugins are not routed.

## Security defaults

Third-party plugins pass Arka’s security and hosted-mode gates. Permissions can
declare `read`, `write`, `network`, `shell`, or `install`; risky operations need
interactive approval, and hosted/user-disabled skills remain unavailable.
Command plugins receive structured arguments and are not evaluated through a
shell string. Unsafe argument syntax, missing dependencies, invalid manifests,
and failed health checks block activation. Plugin installation is always
explicit; discovery never executes code.

## skill.json format

Every plugin needs a `skill.json` manifest:

```json theme={null}
{
  "name": "my_skill",
  "description": "What it does",
  "type": "python",
  "entry": "run.py",
  "triggers": ["my skill", "do the thing"],
  "voice_ack": "Running my skill."
}
```

### Supported types

| Type      | Entry        | Runs as        |
| --------- | ------------ | -------------- |
| `python`  | `run.py`     | Python script  |
| `fish`    | `skill.fish` | Fish function  |
| `shell`   | `run.sh`     | Shell script   |
| `command` | `echo hello` | Direct command |

## How triggers work

Arka matches plugin triggers **before** AI routing. When you say something that matches a trigger, Arka runs the plugin immediately with zero LLM tokens.

```json theme={null}
"triggers": ["weather in", "forecast for"]
```

Triggers are case-insensitive substring matches against the full user request.

## Directory structure

```text theme={null}
~/.config/arka/skills/
└── my_skill/
    ├── skill.json
    ├── run.py
    └── README.md
```

## Voice acknowledgment

Set `voice_ack` to speak a confirmation when the plugin runs from voice:

```json theme={null}
"voice_ack": "Checking the weather for you."
```

## Profession plugins

Arka supports profession-domain plugins with curated source registries. See `src/arka/professions/examples/` in the repo for an architect example.

## Refresh after changes

```bash theme={null}
arka skills refresh
arka reload
```

<Tip>
  Keep triggers specific enough to avoid false matches. Test with `arka route "your trigger phrase"` before deploying.
</Tip>


## Related topics

- [Arka — AI terminal agent documentation](/index.md)
- [Life sciences (Anthropic marketplace)](/guides/life-sciences.md)
- [Session memory, heartbeat, and skill gates](/guides/openclaw-features.md)
- [MCP integration for Cursor and Claude](/guides/mcp.md)
- [Arka Ideate](/guides/ideate.md)