convez.ai
MCP ServerIntegração & APIsIntermediário
specivo

Specivo Agent Skills

specivo/specivo-agent-skills

Convenções MCP reutilizáveis para agentes de IA dominar Specivo

Ver no GitHub
InicialPluginScore · de 0 a 100

Conjunto 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-skills

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
1

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:

  1. Reference codex/AGENTS.md from your project's AGENTS.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.
    
  2. Or paste the body of codex/AGENTS.md directly into your AGENTS.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.

  1. Run a Specivo instance.
  2. Create a service-account user per agent — e.g. claude-code, codex, cursor — and grant each only the project access (role) it needs.
  3. Sign in as that account (or have an admin manage it) and generate its API key from that account's profile.
  4. Point each agent's MCP config at https://<your-specivo>/mcp/ with that account's Authorization: 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_id from specivo_whoami and 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.

Ver o original no GitHub

Bom para

Relacionados