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

# AI-assisted development

## AI-assisted development

Qomicex gives AI agents (Claude / opencode / Cursor and so on) a **plugin development Skill package** that gathers every fact needed to produce a compliant plugin (manifest validation, the permission catalog, the bridge API, theme tokens, signing, and debugging) into one directory, so the AI does not invent fields. Combined with the CLI's `create` / `dev` / `verify` / `pack` / `publish` flow, an AI can produce a publishable plugin end to end.

## Skill package repository

The Skill package (Skill package)is maintained separately in the **[qomicex-plugin-skills](https://github.com/Qomicex-Public/qomicex-plugin-skills)** repository (`skills/qomicex-plugin-dev/`):

```text theme={null}
skills/qomicex-plugin-dev/
├── SKILL.md           # entry point: when to use, file map, full workflow, starter prompt
├── refs/              # 12 topic references (loaded on demand)
│   ├── cli.md         # CLI command reference (create/dev/verify/pack/publish)
│   ├── manifest.md    # manifest.json all fields + layers + dependencies + contributes
│   ├── plugin-api.md  # bridge API (__PLUGIN_API__) signature reference
│   ├── theme.md       # three-tier theme tokens + var() consumption rules
│   ├── publishing.md  # Ed25519 signing flow (generate key → pack --key → publish)
│   ├── debugging.md   # harness hot-reload debugging
│   └── ...            # other topics
└── templates/         # 13 reusable templates (React, manifest, overlay, and more)
```

These files track the code (`src/plugins/types.ts`, the CLI's `src/lib/*`, and the public docs). **When field meanings are in doubt, the code wins; if you are unsure, flag it rather than inventing an API.**

## Install the Skill package

### Option 1: copy the install prompt to your AI (recommended)

Copy the following to any AI assistant and it will complete the installation:

```text theme={null}
Please install the Qomicex plugin development skill for me. Steps:
1. run `git clone https://github.com/Qomicex-Public/qomicex-plugin-skills.git /tmp/qomicex-plugin-skills` (or any temporary directory)
2. create the directory `~/.agents/skills/` (if missing)
3. Copy the whole `skills/qomicex-plugin-dev/` directory into `~/.agents/skills/`
4. Verify `~/.agents/skills/qomicex-plugin-dev/SKILL.md` exists, then delete the temporary clone
5. Tell me installation is done; it takes effect after restarting the AI tool (opencode / Claude Code)
```

On Windows (PowerShell):

```text theme={null}
Please install the Qomicex plugin development skill for me. Steps:
1. run `git clone https://github.com/Qomicex-Public/qomicex-plugin-skills.git $env:TEMP\qomicex-plugin-skills`
2. create the directory `$HOME\.agents\skills\` (if missing)
3. Copy the `skills\qomicex-plugin-dev\` directory into `$HOME\.agents\skills\`
4. Verify `$HOME\.agents\skills\qomicex-plugin-dev\SKILL.md` exists, then delete the temporary clone directory
5. Tell me installation is done; it takes effect after restarting the AI tool
```

### Option 2: run the install script manually

```bash theme={null}
# macOS / Linux
git clone https://github.com/Qomicex-Public/qomicex-plugin-skills.git /tmp/qomicex-plugin-skills
bash /tmp/qomicex-plugin-skills/install.sh

# Windows (PowerShell)
git clone https://github.com/Qomicex-Public/qomicex-plugin-skills.git $env:TEMP\qomicex-plugin-skills
& "$env:TEMP\qomicex-plugin-skills\install.ps1"
```

The install script copies to `~/.agents/skills/` by default (the user-level directory of the open Agent Skills standard, **recognized by both opencode and Claude Code**). Override the target directory with the `QOMICEX_SKILLS_DIR` environment variable (such as `~/.config/opencode/skills/` or `~/.claude/skills/`).

### Manual placement

| Platform | Where to put it |
| - | - |
| **Claude Code** | Copy `skills/qomicex-plugin-dev/` into the project's `.claude/skills/` |
| **Cursor** | Put the skill files in `.cursor/rules/` |
| **opencode** | Register the skill directory in the skills configuration, or paste SKILL.md directly |
| **Any tool (simplest)** | Paste SKILL.md and the relevant reference volumes straight into the conversation |

Restart your AI tool after installing. The AI loads the skill automatically for tasks related to "developing a Qomicex plugin".

### Uninstall

```bash theme={null}
rm -rf ~/.agents/skills/qomicex-plugin-dev
```

## Starter prompt

> You are a Qomicex plugin development engineer. Start by reading SKILL.md under `~/.agents/skills/qomicex-plugin-dev/` and each of its reference files (especially `cli.md`, `manifest.md`, and `plugin-api.md` under `refs`), then work through the flow: `qomicex create <id>` to generate the project → implement the feature → `qomicex verify` until it reports 0 errors → `qomicex pack` to produce the package. Trust the documentation inside the skill package for manifest fields, permissions, and API signatures, and never invent them.

## End-to-end CLI flow (AI-driven development)

Used together with the CLI, the Skill package lets an AI produce a publishable plugin end to end:

```bash theme={null}
qomicex create com.example.myplugin   # 1. scaffold the project
cd com.example.myplugin
pnpm install                          # 2. install dependencies
qomicex dev                           # 3. hot-reload debugging (use the harness inside the repo)
# ... AI implements the feature ...
qomicex verify                        # 4. static validation (manifest, permissions, long loops), 0 errors
qomicex pack --key ./dev-key.pem      # 5. build + package (can be signed)
qomicex publish --changelog "..."     # 6. publish to the store (device flow sign-in → signing → upload)
```

For the full command reference, see [CLI reference](https://docs.qomicex.top/en/plugins/cli.md).

## Summary of hard rules (Skill package `refs/pitfalls`)

An AI generating or modifying a plugin must follow every rule; violating any one of them can make `qomicex verify` fail or cause runtime errors. Core excerpts:

| Category | Hard rule |
| - | - |
| **manifest** | `id` in reverse-domain format (`^[a-z0-9]+([.-][a-z0-9]+)*$`, 3-128 characters, must contain a dot); `version` strictly semver; `minLauncherVersion` required; declaring `entry.frontend` requires `layers` to include `l2`/`l3` (otherwise the UI cannot render) |
| **Permission** | Least privilege: `verify` scans the source, and both declared-but-unused and used-but-undeclared **raise errors**; `shell:execute`, `filesystem:write`, and `plugin:install` are danger permissions — do not declare them unless necessary |
| **Code** | TS imports must include extensions (`./api.ts`); `vite.config.ts` must set `base: './'`; use `<Link>` rather than `<a>` for internal navigation; do not use `window.open` in the sandbox; use `proxyFetch` / `proxyFetchStream` for external network access (they include SSRF protection) |
| **Theme** | Use `var(--*)` for all CSS; `#hex` / `rgb()` / `hsl()` literals are forbidden; with Tailwind, use semantic class names (`bg-primary` and so on) |
| **Security** | Never hardcode secrets (use `setSettings`/`getSettings` for user configuration); do not abuse `shell:execute`; file reads and writes go through the authorization system |
| **Process** | Generate the project with `qomicex create` rather than hand-writing the skeleton; always run `qomicex verify` (0 error) before packaging; do not touch launcher core code; do not commit during plugin development |

The complete rules are in the Skill package's `refs/pitfalls.md`; the above is only a summary.

## Validating AI-generated code

An AI-generated plugin **must pass `qomicex verify`** (0 error counts as passing):

```bash theme={null}
qomicex verify                        # directory mode: manifest + permission minimality + long loops
qomicex verify --package ./release/xxx.qplugin   # package mode: manifest + signature verification
```

Validation covers manifest validity, least privilege (comparing against the bridge methods the source actually calls), and long-loop warnings (`while(true)` / unbounded `setInterval`). Warnings are acceptable but should ideally be removed.

Once it passes, package with `qomicex pack --version x.y.z`, sign with `qomicex pack --key`, and publish with `qomicex publish`. For the complete flow, see [CLI reference](https://docs.qomicex.top/en/plugins/cli.md) and [Publishing guidelines](https://docs.qomicex.top/en/plugins/publishing.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.