Specivo Agent Skills
specivo/specivo-agent-skills
Convenções MCP reutilizáveis para agentes de IA dominar Specivo
Ver no GitHubConjunto de instruções reutilizáveis que ensinam agentes de IA (Claude, Cursor, Codex) a usar o MCP server do Specivo de forma eficiente. Fornece convenções padronizadas para trabalhar com issues, wiki, busca híbrida e metadados, com wrappers específicos para cada cliente MCP.
Instalação
npx convez-ai specivo/specivo-agent-skills1 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
- Instruir agentes de código a navegar e manipular issues e wiki do Specivo
- Padronizar comportamento de múltiplos clientes MCP (Claude, Cursor, Codex, Windsurf)
- Ensinar buscas híbridas e queries de metadados sem reaprendizado a cada sessão
Veredito

Solução técnica sólida e bem arquitetada para normalizar interações entre agentes e o Specivo via MCP. O padrão de wrappers por cliente e source-of-truth único em convenções.md reduz duplicação e facilita manutenção — essencial para equipes que usam múltiplos agentes de código.
README
A tradução para o português deste README ainda está na fila.
Specivo Agent Skills
Drop-in instructions that teach AI coding agents how to use Specivo — the self-hosted project tracker, wiki, and knowledge base — through its built-in MCP server. Load it once and your agent stops re-learning the conventions every session.
The guidance is project-agnostic (issues, wiki, search, metadata, relations, sprints, versions, time logging) and the same body ships in several formats, one per agent ecosystem.
The integration is the MCP server — these files are just wrappers
Specivo exposes an HTTP MCP server (tools mcp__specivo__* / specivo_*). That protocol is client-agnostic: Claude Code, Codex, Cursor, Windsurf, Cline, and anything else that speaks MCP can talk to it with Authorization: Bearer <key>. The files in this repo are thin, per-client wrappers around one shared set of conventions — they don't add capability, they make agents use the tools well.
The server also serves its own live, version-matched guidance: call specivo_setup_guide(format="claude"|"cursor"|"generic"). When it disagrees with anything here, trust the server — it knows what tools it ships today.
Layout
shared/conventions.md ← single source of truth (vendor-neutral body)
claude/SKILL.md ← Claude Agent Skills (YAML frontmatter + body)
cursor/.cursorrules ← Cursor rules
codex/AGENTS.md ← Codex / generic AGENTS.md
scripts/build.py ← regenerates the three wrappers from shared/conventions.md
Edit shared/conventions.md, then run python scripts/build.py to regenerate the wrappers. python scripts/build.py --check fails if they're out of date (handy in CI).
Install
Claude Code / Claude apps
Claude auto-discovers a skill as a folder whose SKILL.md sits at its root. Link (or copy) the claude/ folder into a skills directory:
# global
ln -s "$(pwd)/claude" ~/.claude/skills/specivo
# or per-project
ln -s "$(pwd)/claude" /path/to/project/.claude/skills/specivo
Claude decides when to load it from the description in the frontmatter — nothing else to configure.
GitHub Copilot CLI
Copilot CLI uses the same Agent Skills format, so the claude/ folder works there too — install it as a plugin skill or drop it into Copilot's skills directory (see the Copilot CLI docs for the current path).
Codex CLI
Codex has no skill-triggering system; it loads AGENTS.md every turn. Either:
- Reference
codex/AGENTS.mdfrom your project'sAGENTS.md(recommended — no duplication):## Specivo When working with Specivo issues, wiki, search, or any `specivo_*` MCP tool, follow the conventions in /absolute/path/to/specivo-agent-skills/codex/AGENTS.md. - Or paste the body of
codex/AGENTS.mddirectly into yourAGENTS.md(always on, costs context every turn).
Cursor
Copy cursor/.cursorrules to the root of your project (or paste its body into your existing .cursorrules). Cursor includes it on every turn in that workspace.
Windsurf / Gemini CLI / generic LLMs
Paste the body of shared/conventions.md into whatever instruction or system-prompt mechanism your agent supports. It's vendor-neutral — it's about how to use the tools, not about any specific model.
Connecting the MCP server
Give each agent its own service account — don't hand out your personal key. Specivo has no per-seat pricing, so a dedicated account per agent is the recommended setup, not an optimization.
- Run a Specivo instance.
- Create a service-account user per agent — e.g.
claude-code,codex,cursor— and grant each only the project access (role) it needs. - Sign in as that account (or have an admin manage it) and generate its API key from that account's profile.
- Point each agent's MCP config at
https://<your-specivo>/mcp/with that account'sAuthorization: Bearer <key>.
Why one account per agent:
- Separable audit trail — the activity feed shows exactly which agent did what, and distinguishes every agent from you and from each other.
- Independent revocation — kill one agent's key without touching your login or the other agents.
- Scoped permissions — give each agent only the roles/projects it needs; a read-only research agent and a write-access dev agent stay distinct.
- Self-assignment still works — each agent reads its own
user_idfromspecivo_whoamiand assigns issues to itself.
A single shared or personal key does work, but it's discouraged: every action is attributed to you, and you can't revoke or scope one agent without affecting the rest.
Example (Codex CLI, ~/.codex/config.toml) — using the codex service account's key:
[mcp_servers.specivo]
enabled = true
url = "https://your-specivo.example.com/mcp/"
[mcp_servers.specivo.http_headers]
Authorization = "Bearer spv_your_api_key_here"
Updating
Specivo adds tools often. The skill handles that by telling agents to call specivo_setup_guide once per session, which returns the live tool list from your server — so you rarely need to update these files when Specivo ships features. Pull the latest when you want refreshed conventions or anti-patterns.
Contributing
Found a pattern that trips agents up, or a convention worth codifying? Open an issue or PR against shared/conventions.md (then run scripts/build.py). One rule: keep it project-agnostic — the skill intentionally knows nothing about any specific deployment.
License
MIT. Use it, fork it, ship it.