vintasoftware__django-ai-plugins/docs/installation.md

# Installation and lifecycle

Choose exactly one installation channel for each skill ID. Installing the same
ID through a native marketplace and a generic skills directory can create a
duplicate; remove the shadow copy and retain the channel recommended below.

Replace `django-expert` in the examples with any catalog ID:
`django-celery-expert`, `cdrf-expert`, `django-safe-migration`, or
`django-reviewer`.

## Migrating from flat 1.0 packages

Earlier package checkouts exposed these skills at a flat
`plugins/<id>/skills/SKILL.md` path. The normalized package layout moves each
skill into its own named directory:

| ID | Former path | Current path |
| --- | --- | --- |
| `django-expert` | `plugins/django-expert/skills/SKILL.md` | `plugins/django-expert/skills/django-expert/SKILL.md` |
| `django-celery-expert` | `plugins/django-celery-expert/skills/SKILL.md` | `plugins/django-celery-expert/skills/django-celery-expert/SKILL.md` |
| `cdrf-expert` | `plugins/cdrf-expert/skills/SKILL.md` | `plugins/cdrf-expert/skills/cdrf-expert/SKILL.md` |

If you copy packages directly, replace the complete package directory so its
skill references move with it. Do not retain both the former and current
discoverable paths: hosts can register the same skill ID twice. Native
marketplace installations should use the host-specific update steps below.

## Claude Code

Claude uses `.claude-plugin/marketplace.json`.

```text
/plugin marketplace add vintasoftware/django-ai-plugins
/plugin install django-expert@django-ai-plugins
```

Update and uninstall with Claude's plugin lifecycle:

```text
/plugin update django-expert@django-ai-plugins
/plugin uninstall django-expert@django-ai-plugins
```

Restart Claude after an update so its cache loads the new package version.

## Codex

Codex uses `.agents/plugins/marketplace.json`.

```bash
codex plugin marketplace add vintasoftware/django-ai-plugins
codex plugin add django-expert@vinta-django-ai-plugin
```

Refresh the Git snapshot before updating an installed plugin:

```bash
codex plugin marketplace upgrade vinta-django-ai-plugin
codex plugin remove django-expert@vinta-django-ai-plugin
codex plugin add django-expert@vinta-django-ai-plugin
```

Uninstall with:

```bash
codex plugin remove django-expert@vinta-django-ai-plugin
```

For local development, replace the repository slug in `marketplace add` with
the checkout path. Use an isolated Codex profile when testing; do not change a
real user's configuration.

## Cursor

Cursor uses `.cursor-plugin/marketplace.json` and package-local generated skill
copies. In Cursor Agent chat, add a local checkout or the GitHub repository:

```text
/add-plugin ./plugins/django-expert
```

For a marketplace-backed install, search for the configured team marketplace
entry and select the plugin ID. To update, refresh the marketplace and
reinstall the plugin after its version changes. To uninstall, remove it from
Cursor's Installed Plugins view. Reload the Cursor window after either action
to clear its plugin cache.

## OpenCode

OpenCode automatically loads `.opencode/plugins/django-ai-skills.js` from a
checkout. The dependency-free adapter registers only the root `skills/` path.
Keep `.opencode/`, `package.json`, and `skills/` at their repository-relative
locations.

To update, pull or replace the checkout and restart OpenCode. To uninstall,
remove the checkout or remove the copied adapter and skills together. Do not
also copy these IDs into `.opencode/skills/` or `.agents/skills/`.

OpenCode skill permissions can be configured in `opencode.json`. If a skill is
hidden or denied, allow its ID under the `permission.skill` rules; this project
does not bypass host permissions.

## Skills.sh and generic Agent Skills

The [`skills` CLI](https://skills.sh/vintasoftware/django-ai-plugins) is the
recommended portable installer for hosts that support Agent Skills. It detects
compatible agents and installs from the canonical `skills/` collection.

List the skills available in this repository without installing them:

```bash
npx skills add vintasoftware/django-ai-plugins --list
```

Start an interactive installation for the collection:

```bash
npx skills add vintasoftware/django-ai-plugins
```

Install one skill, optionally targeting specific agents:

```bash
npx skills add vintasoftware/django-ai-plugins --skill django-expert
npx skills add vintasoftware/django-ai-plugins --skill django-expert --agent codex --agent cursor
```

Use `--global` to make a skill available outside the current project:

```bash
npx skills add vintasoftware/django-ai-plugins --skill django-expert --global
```

Update or remove an installation with the same CLI:

```bash
npx skills update django-expert
npx skills remove django-expert
```

Skills.sh is a generic Agent Skills channel. Do not install the same skill ID
through Skills.sh and a native Claude, Codex, or Cursor marketplace at the same
time; keep one channel and remove any shadow copy.

Agent Skills consumers can read `skills/<id>/SKILL.md` directly. For a
manual user-level installation, copy one complete canonical directory:

```bash
cp -R skills/django-expert ~/.agents/skills/django-expert
```

Update by replacing that one directory; uninstall by removing it. Preserve
references and assets inside the skill directory. Check the target host's
permission model before granting a skill access to tools.

## Cache, duplicate, and permission troubleshooting

- If an update still shows old behavior, refresh the marketplace or checkout,
  confirm the catalog version changed, then restart the host to clear its cache.
- If an ID appears twice, list its provenance and keep only one of the native
  marketplace, OpenCode adapter, or direct Agent Skills installation.
- If discovery succeeds but invocation is denied, inspect the host's skill or
  plugin permission settings. The adapters never relax permissions.
- Run `python scripts/smoke_plugins.py --target <host>` from the checkout to
  verify the package without modifying a real home directory.