capa clean

Remove every artifact CAPA installed for this project: skill directories, rule files, agent instruction snippets, sub-agent endpoints, MCP client registrations, the lockfile, and the project's DB row.

Usage

capa clean

Description

Walks every active provider and removes everything CAPA wrote for this project, including:

  • Skill directories in each provider's skills folder (.cursor/skills/, .claude/skills/, .codex/..., etc.).
  • Rule files written into per-provider rules directories (.cursor/rules/*.mdc, .windsurf/rules/*.md, .github/instructions/*.instructions.md), plus any <!-- capa:start:rule:... --> blocks that were folded into AGENTS.md or CLAUDE.md.
  • CAPA-managed snippets from AGENTS.md and CLAUDE.md (when the agents section is configured).
  • Sub-agent definition files and per-sub-agent MCP entries.
  • The main capa MCP server entry in each provider's MCP config (.cursor/mcp.json, .mcp.json, .codex/config.toml, and so on).
  • The capabilities.lock file. CAPA generated it, so CAPA deletes it.
  • The project's row in the local capa database.

What Gets Cleaned

Skill Directories

Whatever skills directory each active provider uses, for example:

  • .cursor/skills/ (Cursor)
  • .claude/skills/ (Claude Code)
  • .agents/skills/ (Codex, OpenCode, Amp, Gemini CLI, Replit, GitHub Copilot)
  • .windsurf/skills/, .augment/skills/, .roo/skills/, and one per supported provider.

Only directories CAPA explicitly tracked in its managed-files database are removed. Skills you authored by hand alongside them are left alone.

Rules

For directory-based providers (Cursor, Windsurf, GitHub Copilot), every rule file CAPA wrote ({id}{extension}) is deleted from the provider's rules directory. For instruction-folded providers (Claude Code, Codex, OpenCode, and others), every <!-- capa:start:rule:{id} --> marker block is stripped from AGENTS.md or CLAUDE.md. See the Rules page for the full mapping.

Agent Instructions Files

When the capabilities file has an agents section, CAPA removes all capa-owned blocks (wrapped in <!-- capa:start:id --> markers) from AGENTS.md and CLAUDE.md. If a file is entirely empty after removing capa blocks, it is deleted. Content you wrote outside the markers is preserved.

Sub-Agents

Per-sub-agent MCP entries are unregistered from each provider's MCP config, and the corresponding sub-agent definition files (for example, .claude/agents/{id}.md or .codex/agents/{id}.toml) are removed.

MCP Configuration

The main capa MCP server entry is removed from each provider's MCP config file (.cursor/mcp.json, .mcp.json, .codex/config.toml, .opencode/opencode.json, .vscode/mcp.json, etc.).

Lockfile

capabilities.lock is deleted because it is generated by CAPA, not authored by the user. Future capa install runs will rewrite it from scratch.

What Does NOT Get Cleaned

  • The capabilities.yaml or capabilities.json file in your project.
  • Content in AGENTS.md or CLAUDE.md written outside capa markers.
  • Rule files in provider rules directories that CAPA did not write. Anything not registered in its managed-files DB is left alone.
  • The CAPA server. It keeps running until you use capa stop.
  • The on-disk repository cache at ~/.capa/cache/. Use capa cache clean for that.
  • Credentials stored in ~/.capa/capa.db.
  • Server logs in ~/.capa/logs/.

When to Use

  • Before reinstalling with capa install to start fresh
  • When removing CAPA from a project
  • To resolve issues with stale skill installations
  • When changing MCP client providers

Typical Workflow

Clean and reinstall:

capa clean
capa install

Notes

  • The command is safe to run and won't delete your project files.
  • You'll need to run capa install again to restore functionality.
  • Your MCP client may need to be restarted after cleaning.

Related Commands

  • capa install: reinstall capabilities after cleaning.
  • capa cache clean: wipe the on-disk repository cache (separate from capa clean).
  • Rules: what rule artifacts CAPA writes, and therefore cleans.
  • Agent Instructions: how AGENTS.md and CLAUDE.md are managed.
  • Lockfile: capabilities.lock is removed by capa clean and rewritten by the next install.
  • capa stop: stop the server.