Metadata-Version: 2.4
Name: imfusion-agent-skills
Version: 0.2.1
Summary: Install ImFusion SDK rules and skills for AI coding agents.
Author: ImFusion GmbH
License-Expression: MIT
Project-URL: Homepage, https://github.com/ImFusionGmbH/imfusion-agent-skills
Project-URL: Repository, https://github.com/ImFusionGmbH/imfusion-agent-skills
Project-URL: Issues, https://github.com/ImFusionGmbH/imfusion-agent-skills/issues
Keywords: imfusion,cursor,claude-code,opencode,agent-skills
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# ImFusion Agent Skills

Install project-level rules and skills that help AI coding agents build plugins and applications based on the ImFusion SDK.

Rules provide focused coding guidance when relevant files are open. Skills provide reusable workflows for tasks such as creating a plugin, configuring CMake, and working with image data.

## Install

The recommended installation uses [uv](https://docs.astral.sh/uv/getting-started/installation/) to install the CLI in an isolated environment:

```sh
uv tool install imfusion-agent-skills
```

[pipx](https://pipx.pypa.io/) does the same thing if you already have it:

```sh
pipx install imfusion-agent-skills
```

Without either, install it with standard pip. Prefer a virtual environment, because many Linux distributions refuse a system-wide install:

```sh
python -m pip install imfusion-agent-skills
```

Python 3.10 or newer is required.

Until the first PyPI release, install straight from the repository instead:

```sh
uv tool install git+https://github.com/ImFusionGmbH/imfusion-agent-skills
```

## Install into a project

Run the command from the root of your ImFusion SDK project:

```sh
imfusion-agent-skills init
```

To run it once without installing the CLI permanently, use `uvx imfusion-agent-skills init` or `pipx run imfusion-agent-skills init`.

Without `--agent`, the command detects which agents to install for. If `.imfusion-agent-skills/manifest.json` exists it wins outright, so re-running `init` refreshes exactly what is already installed. Otherwise the command combines two signals: agent files in the project (`.cursor/`, `.claude/`, `CLAUDE.md`, `.opencode/`, or an `AGENTS.md` that already contains this package's section) and the environment of the agent running the command, which covers a project that has no agent files yet.

A bare `AGENTS.md` is deliberately ignored, because several tools read that file and its presence identifies none of them.

If nothing is detected the command exits without writing anything and asks you to pass `--agent`. Name the agents explicitly whenever you want to control the result:

```sh
# Cursor
imfusion-agent-skills init --agent cursor

# Claude Code
imfusion-agent-skills init --agent claude

# OpenCode
imfusion-agent-skills init --agent opencode

# A project other than the current directory
imfusion-agent-skills init path/to/project --agent cursor,claude
```

The command installs native project files:

- Cursor: `.cursor/rules/` and `.cursor/skills/`
- Claude Code: `.claude/rules/` and `.claude/skills/`
- OpenCode: `.opencode/skills/`, `.opencode/references/`, and a managed section in `AGENTS.md`

The rules directories also receive the C++ template files that some rules reference, so `.cursor/rules/` and `.claude/rules/` contain a few `.h` and `.cpp` files next to the rules themselves. OpenCode keeps those in `.opencode/references/`.

Because the three tools scope guidance differently, the same source rules behave slightly differently once installed:

- Cursor and Claude Code attach file-scoped rules only when the agent touches matching files.
- OpenCode has no scoped-rule mechanism, so all rules live in the `AGENTS.md` section and are always in context. Each one is labelled with its name and the file patterns it applies to.

Use `--dry-run` to inspect changes. Use `--force` only when you intend to replace files that conflict with managed paths.

## Safe updates

The installer merges into existing agent directories. It records installed file hashes in `.imfusion-agent-skills/manifest.json` and follows these rules on later runs:

- unchanged managed files are updated to the installed package version;
- unrelated project files and existing `AGENTS.md` content are preserved;
- user-modified or unknown same-named files stop the installation before any changes are written;
- `--force` explicitly replaces those conflicts;
- managed files that the package no longer ships are removed if unchanged, and kept but no longer managed if you edited them;
- files keep the line endings they already had, so an update does not rewrite every line of a CRLF checkout.

To update:

```sh
uv tool upgrade imfusion-agent-skills
imfusion-agent-skills init
```

The second command needs no `--agent`, because the manifest already records which agents the project uses.

With a regular Python environment, replace `uv tool upgrade` with `python -m pip install --upgrade imfusion-agent-skills`.

## Remove installed guidance

There is no automatic uninstall command in the initial release. Remove the installed ImFusion files listed in `.imfusion-agent-skills/manifest.json`, then remove `.imfusion-agent-skills/`. For OpenCode, remove only the section between:

```text
<!-- imfusion-agent-skills:start -->
<!-- imfusion-agent-skills:end -->
```

Do not remove an entire `.cursor`, `.claude`, `.opencode`, or `AGENTS.md` path if it also contains project-owned content.

Leaving an agent out of `--agent` does not uninstall it: the installer only manages the agents you pass on that run, so files for other agents stay untouched. `AGENTS.md` itself is never deleted — when a managed section becomes obsolete, only the section is stripped out.

## Give the agent access to the SDK and demos

The installed rules and skills describe ImFusion APIs, but they do not contain the SDK headers or complete example implementations. Several rules and skills tell the agent to consult working examples, so make these available in every project where you install this package:

1. Your local ImFusion SDK installation.
2. The [ImFusion public demos](https://github.com/ImFusionGmbH/public-demos) checked out at the tag matching your SDK version, such as `imfusion-sdk-v4.4`.

With Claude Code, add both directories to the session (for example with `/add-dir`) or keep the demos checkout inside the project tree. With OpenCode, run the agent from a directory that contains both, or point it at the checkout when you ask for an example. In Cursor, use a multi-root workspace as described below.

### Cursor workspace recommendation

Create a multi-root workspace file such as `your-project.code-workspace` in your project root:

```json
{
	"folders": [
		{ "name": "Project", "path": "." },
		{
			"name": "ImFusion SDK",
			"path": "C:/Program Files/ImFusion/ImFusion Suite"
		},
		{ "name": "ImFusion public demos", "path": "C:/Dev/public-demos" }
	],
	"settings": {}
}
```

Adjust the paths for your system, then open the `.code-workspace` file in Cursor.
Cursor can then inspect SDK declarations and matching working examples when applying the installed guidance.
The SDK and demos remain external dependencies; they are not copied into your project.

### Optional: make the SDK documentation available

Headers and demos cover most coding tasks, but conceptual guides and fuller API reference live in the official documentation at [docs.imfusion.com](https://docs.imfusion.com) (C++ and Python SDK developer docs).

In Cursor, add that site under **Settings → Indexing & Docs → Docs** so the agent can look up topics the installed rules and skills deliberately do not duplicate. Claude Code and OpenCode can reach the same pages with their web fetch tools when those are enabled.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, content guidelines, testing, and release preparation.

## License

Licensed under the [MIT License](LICENSE).
