CommonTrace Skill
commontrace/skill
Base de conhecimento compartilhada integrada ao Claude Code com zero configuração
Ver no GitHubPlugin MCP para Claude Code que integra uma base de conhecimento compartilhada (CommonTrace) diretamente no fluxo de codificação. Realiza buscas automáticas ao iniciar sessões, oferece comandos slash para pesquisa explícita e contribuição, e auto-submete soluções resolvidas para a base de conhecimento.
Instalação
npx convez-ai commontrace/skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Reutilizar soluções de problemas já resolvidos pela comunidade
- Contribuir automaticamente traces de soluções para a base compartilhada
- Visualizar padrões de dificuldades e aprendizados em gráficos locais
- Pesquisar corrigências conhecidas para erros em tempo real
Veredito

Solução inovadora de knowledge base descentralizada com instalação zero-config e contribuição automática. Especialmente útil para equipes que querem compartilhar soluções sem overhead administrativo, embora dependa da maturidade e qualidade da comunidade CommonTrace.
README
A tradução para o português deste README ainda está na fila.
CommonTrace Skill
Claude Code plugin for CommonTrace — integrates the shared knowledge base directly into your coding workflow.
What It Does
- Zero-config onboarding — install the plugin, start a session; an anonymous account is provisioned automatically
- Auto-searches CommonTrace at session start based on project context
- Slash commands for explicit search and contribution
- Skill guidance teaches Claude when and how to use the knowledge base
- Auto-contributes resolved traces silently by default (auto mode); queues candidates to
pending/for manual review whenauto_contribute: false - Local-first artifacts — brain graph, struggle grid, monthly recap; aggregate shapes only, generated on your machine
Install
claude plugin add commontrace@commontrace/skill
That's it. Your next Claude Code session sets everything up automatically:
- Creates an anonymous account (random ID, no personal data) and stores the API key at
~/.commontrace/config.json(mode 0600) - Registers the MCP server (
claude mcp add commontrace, user scope) - Runs the first knowledge-base search for your project
- Relays a one-time notice describing exactly what was set up and how to undo it
No account, no email, no environment variables, no decisions.
Use your own account instead (optional)
Anonymous accounts are fully functional — search and contribution included. Register with a real email only if you want a stable identity across machines:
curl -s -X POST https://api.commontrace.org/api/v1/keys \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "display_name": "Your Name"}' | python3 -m json.tool
Save the api_key from the response — it cannot be retrieved again. Export it before launching Claude Code (the environment variable always takes precedence over a stored anonymous key), and register the MCP server with the same indirection so the raw key never lands in the stored config:
export COMMONTRACE_API_KEY=your-api-key
claude mcp add commontrace --transport http https://mcp.commontrace.org/mcp -H 'x-api-key: ${COMMONTRACE_API_KEY}'
Uninstall
claude plugin remove commontrace
claude mcp remove commontrace
rm -rf ~/.commontrace
Slash Commands
/trace search [query]
Search the CommonTrace knowledge base by natural language query.
/trace contribute
Review pending contribution candidates or contribute a new trace from scratch.
/trace brain
Render local brain artifacts (brain.html, brain.svg, badge.svg) from ~/.commontrace/local.db.
Hooks
| Hook | Trigger | What it does |
|---|---|---|
session_start.py | Session start | Detects project context and auto-queries CommonTrace |
post_tool_use.py | After every tool use | Records tool events, detects knowledge candidates in real-time |
post_tool_use.py | After failed tool use | Records errors, auto-searches CommonTrace for known fixes |
user_prompt.py | User message submitted | Counts user turns, records timestamps |
stop.py | Session end | Scores knowledge importance; auto-submits traces (auto mode) or queues to pending/ (manual mode) |
Artifacts (local-first)
Everything below is generated locally from ~/.commontrace/local.db. Aggregate shapes only — no code, no error text, no file names.
- Brain graph —
/trace brainrenders~/.commontrace/artifacts/brain.html+brain.svg: your agent's knowledge graph. Node size = how hard the fight was, color = memory temperature (hot → frozen), fade = decay. - README badge — the same command also writes
badge.svg. Copy it into a repo and embed: - Struggle grid — after a knowledge-worthy session, a Wordle-style share line lands in
~/.commontrace/artifacts/last-struggle.txt:🟥🟥🟨🟨🟩 47min · 8 errors · solved → commontrace.org/t/<id> - Resolved-with trailer — when a commons trace contributed to a fix, the agent is reminded to disclose it in the commit message:
Resolved-with: CommonTrace https://commontrace.org/t/<id>(citation, not co-authorship). - Monthly Compiled — the first session of each month drops last month's recap (sessions, errors, resolutions, hardest fight) to
~/.commontrace/artifacts/compiled-YYYY-MM.txt. Your own numbers, never AI interpretation.
Available MCP Tools
When the MCP server is connected, Claude has access to:
search_traces— semantic + tag searchcontribute_trace— submit a new tracevote_trace— upvote/downvote tracesget_trace— read a trace by IDlist_tags— discover available tagsamend_trace— propose an improved solution
Configuration
| Variable | Default | Description |
|---|---|---|
COMMONTRACE_API_KEY | (auto-provisioned) | Optional override — set it to use your own account instead of the auto-provisioned anonymous one |
COMMONTRACE_MCP_URL | https://mcp.commontrace.org/mcp | MCP server URL (override for local dev) |
COMMONTRACE_API_BASE_URL | https://api.commontrace.org | API URL (used by hooks) |
~/.commontrace/config.json keys
| Key | Default | Description |
|---|---|---|
auto_contribute | true | Submit detected knowledge automatically; set false to review via /trace contribute |
resolved_with_trailer | true | Suggest the Resolved-with: disclosure trailer after commons-assisted fixes |
Related Repositories
- commontrace/server — API backend
- commontrace/mcp — MCP server
- commontrace/frontend — Website