convez.ai
AgenteProdutividadeAvançado
mcrilo33

AI Toolkit

mcrilo33/ai-toolkit

Gerenciador centralizado de configs de agentes IA multiplataforma

Ver no GitHub
InicialPluginScore · de 0 a 100

Centraliza configurações de agentes de IA para Cursor, Claude Code e GitHub Copilot em uma única fonte de verdade. Fornece rules, skills, prompts e agents reutilizáveis em Markdown, sincronizando automaticamente para o formato específico de cada ferramenta via scripts.

Instalação

$npx convez-ai mcrilo33/ai-toolkit

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
2
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 dias
Versão
—
Issues abertas
2
Contribuidores
3

Casos de uso

  • Manter consistência de regras de coding entre GitHub Copilot, Cursor e Claude
  • Reutilizar skills e prompts em múltiplas ferramentas de IA
  • Implementar workflow de parallel-worktrees com assistentes de IA

Veredito

Solução sofisticada para times que usam múltiplos assistentes IA e precisam de sincronização centralizada. Exige comfort com scripts shell e estrutura de projeto bem definida, mas elimina duplicação de configurações entre ferramentas.

README

A tradução para o português deste README ainda está na fila.

ai-toolkit

Centralized AI agent configs for GitHub Copilot, Cursor, and Claude Code.

Overview

Single source of truth for AI agent rules, skills, prompts, and settings across multiple AI-powered development tools. Everything lives in shared/ — the sync script generates tool-specific formats (frontmatter, file extensions) on demand.

Structure

ai-toolkit/
├── shared/                   # Single source of truth
│   ├── rules/                # Coding guidelines, conventions, style guides
│   ├── skills/               # Reusable agent skills (land, TDD, etc.)
│   ├── prompts/              # Reusable prompts (commit-msg, etc.)
│   ├── agents/               # Agent definitions
│   └── hooks/                # Lifecycle hook scripts (pre/post tool use)
│
├── claude/                   # Claude Code settings (tool-specific only)
│   └── settings.json
│
├── copilot/                  # Copilot placeholder (agents)
│   └── agents/
│
├── settings/                 # IDE/CLI settings (LLM-related only)
│   ├── vscode/               # Copilot settings, MCP servers, custom models
│   ├── cursor/               # MCP servers
│   └── claude/               # Claude Code settings
│
├── docs/                     # Frontmatter references, sync model, workflow guides
│
├── scripts/
│   ├── install.sh            # Symlinks tool settings to expected locations
│   └── sync-to-repo.sh       # Generates tool configs from shared/ into a repo
│
└── tests/                    # pytest unit + integration suites

How it works

shared/ = source of truth

All rules, skills, prompts, and agents live in shared/ as plain Markdown — no tool-specific frontmatter, no vendor lock-in.

sync-to-repo.sh = generates tool configs

The sync script reads from shared/ and generates the correct format for each tool:

ToolOutput locationWhat it generates
Copilot<repo>/.github/copilot-instructions.md, instructions/*.instructions.md (with applyTo), skills/, prompts/*.prompt.md, agents/
Cursor<repo>/.cursor/rules/*.mdc (with description/globs/alwaysApply), skills/
Claude<repo>/.claude/ + CLAUDE.mdCLAUDE.md (guidelines), skills/
Shared<repo>/.ai-toolkit/mcp/review-stamp/ server + scripts/ (the parallel-worktrees worktree-*.sh + hub-status.sh helpers)

The .ai-toolkit/scripts/ install makes the hub/spoke/land parallel-worktrees workflow usable in any synced repo with no manual setup — the hub, start-task, and land skills reference the helpers there.

Setup

1. Clone the repo

git clone https://github.com/mcrilo33/ai-toolkit.git ~/Repos/ai-toolkit
cd ~/Repos/ai-toolkit

2. Install settings

./scripts/install.sh

This symlinks tool settings (MCP configs, Claude settings) to their expected locations:

ToolWhat gets linked
Cursorsettings/cursor/mcp.json → ~/.cursor/mcp.json
Claudeclaude/settings.json → ~/.claude/settings.json

[!NOTE] VS Code settings can't be symlinked (partial settings.json). Copy keys manually from settings/vscode/copilot-settings.jsonc.

3. Sync configs to a project

# Sync all tools
./scripts/sync-to-repo.sh ~/Repos/my-project

# Sync a specific tool
./scripts/sync-to-repo.sh ~/Repos/my-project copilot
./scripts/sync-to-repo.sh ~/Repos/my-project cursor
./scripts/sync-to-repo.sh ~/Repos/my-project claude

4. Configure environment variables

Secrets (store in macOS Keychain)

VariablePurposeUsed by
LITELLM_MASTER_KEYLiteLLM proxy API keyVS Code (Copilot custom models)
OPENAI_API_KEYOpenAI API keyGeneral LLM access
GITHUB_MCP_TOKENGitHub personal access tokenCursor MCP server
TAVILY_API_KEYTavily search API keyVS Code & Cursor MCP servers
JIRA_API_TOKENJira API tokenVS Code & Cursor MCP servers
CONFLUENCE_API_TOKENConfluence API tokenVS Code & Cursor MCP servers
# Store each secret in macOS Keychain:
security add-generic-password -a "$USER" -s "LITELLM_MASTER_KEY" -w "your-key"
security add-generic-password -a "$USER" -s "GITHUB_MCP_TOKEN" -w "your-token"

Configuration (non-secret, user-specific)

VariablePurposeUsed by
JIRA_URLJira instance URLVS Code & Cursor MCP servers
JIRA_USERNAMEJira username / emailVS Code & Cursor MCP servers
CONFLUENCE_URLConfluence instance URLVS Code & Cursor MCP servers
CONFLUENCE_USERNAMEConfluence username / emailVS Code & Cursor MCP servers
ANTHROPIC_VERTEX_PROJECT_IDGCP project ID for Vertex AIClaude Code
CLOUD_ML_REGIONGCP region for Vertex AIClaude Code

Agents

Eleven specialized agents are defined in shared/agents/. Each has a dedicated persona, tool restrictions, handoff chains, and (where relevant) scoped hooks.

AgentRoleEdits code?
architectSystem design, ADRs, diagrams❌
plannerDecompose tasks into ordered steps❌
tdd-redWrite failing pytest tests✅
tdd-greenMake failing tests pass✅
tdd-refactorImprove code quality, tests green✅
code-reviewReview changes, report findings❌
debugReproduce, diagnose, fix bugs✅
refactorCross-cutting renames/restructures✅
security-reviewerSecurity audit❌
devopsCI/CD, infrastructure, deployment✅
documentationWrite/update docs✅

Handoffs

Agents chain together via handoffs — buttons that transition to the next agent with context. Deterministic transitions (send: true) auto-submit; decision points let the user choose.

# TDD full cycle (auto)
architect → planner → tdd-red → tdd-green → tdd-refactor → code-review

# Code review with findings (manual)
code-review → { debug | refactor | security-reviewer } → code-review

Agent-scoped hooks

Code-editing agents run PostToolUse hooks (post-edit-format.sh, quality-gate.sh) to auto-format and lint after every edit. debug also runs console-log-warn.sh. devops runs PreToolUse hooks (secrets-scan.sh, config-protection.sh) to guard infrastructure files.

See docs/agents-frontmatter.md for the full configuration reference.

Hooks

Hooks execute shell scripts at key lifecycle points during agent sessions. They enforce security policies, automate code quality, and validate operations. All hooks live in shared/hooks/ and are synced to platform-specific formats.

HookEventEnforcementPurpose
block-no-verifyPreToolUsehardBlock git --no-verify and improper force pushes
secrets-scanPreToolUsehardBlock hardcoded secrets in file writes
config-protectionPreToolUsehardBlock modification of CI/linter config files
commit-qualityPreToolUsehardValidate conventional-commit format + issue-anchor
commit-gauntletPreToolUsehardLint/typecheck staged files; block on failure
git-push-reviewPreToolUseadvisoryShow diff summary before git push
red-proof-warnPreToolUseadvisoryWarn on push when source commits lack Tested-RED:
reviewer-sep-warnPreToolUseadvisoryWarn on push when commits lack Reviewed-by:
post-edit-formatPostToolUseadvisoryAuto-format edited files (ruff, prettier, biome)
quality-gatePostToolUseadvisoryRun linter + typechecker on edited files
console-log-warnPostToolUseadvisoryWarn when debug statements are left behind

Hard vs advisory gates

  • Hard gates (deny, exit 2) abort the operation: the commit/write does not proceed. These are the deterministic cage — commit-quality and commit-gauntlet block bad commits; block-no-verify, secrets-scan, and config-protection block dangerous writes.
  • Advisory gates print a warning and always exit 0 — they never block. red-proof-warn and reviewer-sep-warn surface TDD/review gaps at push time but cannot (and do not) stop the push.

The cage's behavior is fully deterministic given the same command: piping an identical {"tool_input":{"command":"..."}} payload into a script always yields the same verdict. See tests/unit/test_commit_hooks.py.

Enforcement caveats

  • Tooling must be on PATH. commit-gauntlet detects the project's linter and typechecker (ruff, eslint/biome; pyright, mypy, tsc). If none is installed or configured, the check degrades gracefully and SKIPS — meaning it enforces nothing. For real enforcement in a target repo, ensure ruff/pyright (or your stack) are installed and resolvable.

  • TDD carve-out. commit-gauntlet skips the typecheck stage on commits carrying a Tested-RED: trailer (an unresolved import is the expected state of a red-before-green test commit); lint still runs. Lint is scoped to changed lines, so pre-existing debt on untouched lines never blocks a clean addition.

  • Agent-runtime dependency. PreToolUse hooks only fire if the agent runtime invokes them. To enforce the blocking gates on real git commit/git push regardless of runtime (or for human-driven git), install them as native git hooks:

    scripts/install-git-hooks.sh [target-repo]   # wires commit-msg + pre-push
    scripts/install-git-hooks.sh --uninstall [target-repo]
    

    This reuses the same scripts (single source of truth), mapping commit-quality + commit-gauntlet to commit-msg and, on pre-push, the advisory warnings plus test-select — a tiered, diff-aware test gate that is the single owner of test execution ("one push = one run"). It classifies the pushed diff and runs nothing / pytest --testmon / the full suite accordingly, blocking the push when the selected tests fail (and falling back to the full suite when pytest-testmon is absent). See docs/test-gate.md.

Hooks run globally via workspace-level config files. Some are also scoped to specific agents (see Agent-scoped hooks above).

See docs/hooks-frontmatter.md for the full configuration reference, platform mapping, and script contract.

Adding new content

New rule

  1. Create shared/rules/<name>.md
  2. Add frontmatter mappings in sync-to-repo.sh (Copilot applyTo, Cursor description/globs/alwaysApply)
  3. Run sync-to-repo.sh on your repos

New skill

  1. Create shared/skills/<name>/SKILL.md
  2. Add frontmatter mappings in sync-to-repo.sh (Copilot and Cursor skill metadata)
  3. Run sync-to-repo.sh on your repos

New prompt

  1. Create shared/prompts/<name>.md
  2. Run sync-to-repo.sh — Copilot prompts get *.prompt.md format automatically

New agent

  1. Create shared/agents/<name>.agent.md
  2. Run sync-to-repo.sh — agents are copied to <repo>/.github/agents/

Environment variables

All secrets are referenced via ${ENV_VAR} placeholders. Never commit actual secrets. Store them in macOS Keychain:

security add-generic-password -a "$USER" -s "KEY_NAME" -w "value"

Load in shell:

export KEY_NAME=$(security find-generic-password -a "$USER" -s "KEY_NAME" -w 2>/dev/null)

License

Private — personal use only.

Ver o original no GitHub

Bom para

Relacionados