SuperAPI AI Directory

calavera

Coding & development

View repository

Updated 10-16 08:45

About this skill

Calavera

Use Calavera to compose and apply project tooling through its MCP tools whenever they are available. This skill guides the active agent; it is not a subagent by itself.

Start Here

  1. Confirm whether Calavera MCP tools are available. Look for tools named list_profiles, list_integrations, list_ai_artifacts, compose_recipe, dry_run_apply, and apply_recipe.
  2. Inspect the project for existing tooling and likely conflicts before composing a recipe. Check files such as package.json, calavera.config.json, .editorconfig, eslint.config.js, oxlint.json, .prettierrc.json, .stylelintrc.json, and tsconfig.json. If likely conflicts exist, pause before applying changes. List each conflict as a hard stop or a migration decision the user can approve, and use dry_run_apply to show concrete impact when adoption still looks possible.
  3. Use AskUserTool or the agent client's equivalent when available to clarify profile preferences, framework needs, conflict decisions, and apply approval. If no such tool exists, ask the user directly.
  4. List choices with list_profiles, list_integrations, and list_ai_artifacts. Use describe_integration when the user asks for more information or when you need to compare options.
  5. Once the profile and requirements are clear, compose the recipe with compose_recipe.
  6. Validate and explain it with validate_recipe and explain_recipe.
  7. Present dry_run_apply output to the user before changing files.
  8. Call apply_recipe only after the user explicitly approves the dry run.
  9. If the MCP transport closes or reports -32000 during or immediately after apply_recipe, treat the outcome as unknown instead of failed. Inspect calavera.config.json, .calavera/state.json, generated files, and package metadata before retrying the apply.

Do not hand-author calavera.config.json when the Calavera MCP server is available. Let Calavera compose, validate, dry-run, and apply the recipe so generated files, package scripts, dependencies, AI artifacts, and managed state stay consistent.

Treat files listed by dry_run_apply, including .calavera/run-if-files.mjs, as Calavera-managed outputs. Do not hand-write or edit them; let apply_recipe or create-project-calavera apply create them after approval.

MCP Setup

If the Calavera MCP tools are not available, help the user register this server from the project root. Check the target project's package.json first and use the package manager declared by packageManager or devEngines.packageManager.

{
  "mcpServers": {
    "calavera": {
      "command": "npx",
      "args": ["--package", "create-project-calavera@<version>", "create-project-calavera-mcp"]
    }
  }
}

For manual MCP setup, use npx --package create-project-calavera@<version> create-project-calavera-mcp for npm-managed projects, pnpm dlx --package create-project-calavera@<version> create-project-calavera-mcp for pnpm, yarn dlx --package create-project-calavera@<version> create-project-calavera-mcp for Yarn, and bunx --package create-project-calavera@<version> create-project-calavera-mcp for Bun. In JSON-based MCP configs, put the first word in command and the remaining words in args. Matching the project package manager prevents package-manager preflight failures before Calavera can start, such as npm rejecting a Bun-managed project. Keep an explicit version so package-manager launchers resolve the create-project-calavera-mcp bin reliably without making the persistent MCP registration float to a later package release.

If this project was bootstrapped with create-project-calavera --init, also check .agents/calavera/mcp.md for local setup notes.

For Claude Code, prefer a project-scoped .mcp.json in the project root when the team should share the Calavera server registration. Do not put the server under .claude/settings.json; Claude Code does not load MCP servers from that file. You can also use claude mcp add to register the same package-manager-specific command.

Registering the Calavera MCP server is a persistent code-execution change that runs an external package, so ask for explicit user approval before creating .mcp.json, running claude mcp add, or approving the first server launch.

Fallbacks

If the MCP server cannot be registered, use the hosted Calavera Web UI to compose and download a recipe:

https://calavera.schalkneethling.com

After a recipe exists, preview local changes with the package-manager-specific apply dry-run command: npm create project-calavera apply -- --dry-run for npm, pnpm dlx create-project-calavera apply --dry-run for pnpm, yarn dlx create-project-calavera apply --dry-run for Yarn, or bunx create-project-calavera apply --dry-run for Bun. Ask the user to approve the preview before running the matching apply command.

User Prompt

When the user wants to start from a scaffolded or existing project, suggest:

Use Calavera for this project. Inspect the current project for existing tooling and possible config conflicts, then list the available profiles, integrations, and AI artifacts. Once the profile and requirements are clear, compose a recipe, show me the dry-run result, and apply it only after I approve.