5.0.0-beta.1 · Published beta · b06750c5. Published on npm. Match your installed version.

Set up an agent#

Use the installed package's documentation and a small application instruction file first. The optional Marionette skill helps an agent select those documents and apply their lifecycle and integration rules. None of these resources requires an account, network access, hosted model, or shared API key to read.

Install the consumer skill#

Builds containing these resources ship dist/agent-skill/ and dist/docs/ inside the marionette package. Check that both exist in your installed package before following these steps; earlier artifacts do not contain them. Do not upgrade an application just to install instructions.

Copy the whole dist/agent-skill/ directory, including scripts/, into the skill location supported by your agent client, naming the copied folder marionette. Use the client's documented installation mechanism; installing an npm dependency does not automatically activate an agent skill. For a source checkout, the same skill lives in skills/marionette/. Use the checkout matching the package's known source revision.

For a client configured to read project skills from .agents/skills, run this from your application directory when that destination does not already exist:

mkdir -p .agents/skills
cp -R node_modules/marionette/dist/agent-skill .agents/skills/marionette

Adapt the source path for a hoisted dependency or package manager without node_modules. When updating an existing copy, review its local changes and replace it deliberately; do not create nested copies. Keep the skill in the application's repository if the team should share it. Update it alongside the package, reviewing any project-specific edits. Agent clients differ in discovery and reload behavior; follow the client's setup instructions and confirm that it lists marionette before relying on automatic selection.

In a client supporting named skill invocation, try:

Use $marionette to inspect this application's installed version and integrations.
Find the matching routing guide and explain which component owns cancellation.
Do not change the application yet.

A successful activation identifies the installed package, reports its documentation revision, reads the relevant page, and distinguishes the router from Marionette's lifecycle. A response that only repeats the prompt has not demonstrated retrieval. If the client cannot load skills, give it Build with Marionette and the matching task guide directly; the skill is an optional entry point.

Read matching docs locally#

The skill bundles a read-only helper requiring Node 24 or later. It addresses a specific retrieval problem: the copied skill must locate the application's installed docs, including hoisted dependencies, without importing application code. It does not add a server, registry, or production dependency.

node .agents/skills/marionette/scripts/docs.mjs --project . --list
node .agents/skills/marionette/scripts/docs.mjs --project . --page docs/routing.md

--list returns JSON with absolute page paths, version, source revision, local change status, and content digest. --page accepts an exact source path from that list and prints one provenance record followed by the page's Markdown. Run from the application workspace, not a neighboring package with a different Marionette dependency. --project defaults to the current directory.

For a package manager without a physical node_modules tree, find that application's physical package directory using its package manager and supply --package-root /path/to/marionette. The helper does not execute resolver hooks or install packages to guess that path. Exit status 1 indicates missing docs, invalid arguments, a version mismatch, or inconsistent files; it does not silently switch to a different source.

The helper validates documentation hashes and their package version. This proves that the files agree with their manifest, not that an arbitrary custom runtime was built from that revision. Check installed exports and test uncertain behavior. For local builds, the version alone cannot identify a source commit; sourceDirty: true means local changes are included. Older packages without docs require an exact release or known source checkout, not an automatic fallback to today's website.

Record the application decisions#

Adapt the application instruction template. Record actual integration choices, initialization points, resource owners, and working test commands. Keep those decisions in the application. The library's maintainer AGENTS.md describes changing Marionette itself and should not be copied into a consumer application.

Choose an optional service only for a specific need#

For Context7, use the public marionettejs/marionette library and the client's Context7 setup instructions. Each developer uses their own account and limits. Do not put a maintainer's API key in a website, repository, or shared public proxy. If a free quota is exhausted, read the static or installed docs directly; do not enable paid overages. Check the current Context7 plans and documentation before configuring an account. Public indexing does not prove that the latest source configuration is active.

Marionette does not require a custom MCP server, a hosted AI chat, or a WebMCP connection to build an application. A future local MCP wrapper would need to solve a demonstrated client integration gap beyond reading these files. Keep tooling outside the production import graph and avoid duplicating the contract in tool prompts. The same documentation remains available to human readers.