AI Toolkit
mcrilo33/ai-toolkit
Gerenciador centralizado de configs de agentes IA multiplataforma
Ver no GitHubCentraliza 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-toolkit1 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
- 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:
| Tool | Output location | What 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.md | CLAUDE.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:
| Tool | What gets linked |
|---|---|
| Cursor | settings/cursor/mcp.json → ~/.cursor/mcp.json |
| Claude | claude/settings.json → ~/.claude/settings.json |
[!NOTE] VS Code settings can't be symlinked (partial
settings.json). Copy keys manually fromsettings/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)
| Variable | Purpose | Used by |
|---|---|---|
LITELLM_MASTER_KEY | LiteLLM proxy API key | VS Code (Copilot custom models) |
OPENAI_API_KEY | OpenAI API key | General LLM access |
GITHUB_MCP_TOKEN | GitHub personal access token | Cursor MCP server |
TAVILY_API_KEY | Tavily search API key | VS Code & Cursor MCP servers |
JIRA_API_TOKEN | Jira API token | VS Code & Cursor MCP servers |
CONFLUENCE_API_TOKEN | Confluence API token | VS 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)
| Variable | Purpose | Used by |
|---|---|---|
JIRA_URL | Jira instance URL | VS Code & Cursor MCP servers |
JIRA_USERNAME | Jira username / email | VS Code & Cursor MCP servers |
CONFLUENCE_URL | Confluence instance URL | VS Code & Cursor MCP servers |
CONFLUENCE_USERNAME | Confluence username / email | VS Code & Cursor MCP servers |
ANTHROPIC_VERTEX_PROJECT_ID | GCP project ID for Vertex AI | Claude Code |
CLOUD_ML_REGION | GCP region for Vertex AI | Claude Code |
Agents
Eleven specialized agents are defined in shared/agents/. Each has a dedicated
persona, tool restrictions, handoff chains, and (where relevant) scoped hooks.
| Agent | Role | Edits code? |
|---|---|---|
| architect | System design, ADRs, diagrams | ❌ |
| planner | Decompose tasks into ordered steps | ❌ |
| tdd-red | Write failing pytest tests | ✅ |
| tdd-green | Make failing tests pass | ✅ |
| tdd-refactor | Improve code quality, tests green | ✅ |
| code-review | Review changes, report findings | ❌ |
| debug | Reproduce, diagnose, fix bugs | ✅ |
| refactor | Cross-cutting renames/restructures | ✅ |
| security-reviewer | Security audit | ❌ |
| devops | CI/CD, infrastructure, deployment | ✅ |
| documentation | Write/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.
| Hook | Event | Enforcement | Purpose |
|---|---|---|---|
block-no-verify | PreToolUse | hard | Block git --no-verify and improper force pushes |
secrets-scan | PreToolUse | hard | Block hardcoded secrets in file writes |
config-protection | PreToolUse | hard | Block modification of CI/linter config files |
commit-quality | PreToolUse | hard | Validate conventional-commit format + issue-anchor |
commit-gauntlet | PreToolUse | hard | Lint/typecheck staged files; block on failure |
git-push-review | PreToolUse | advisory | Show diff summary before git push |
red-proof-warn | PreToolUse | advisory | Warn on push when source commits lack Tested-RED: |
reviewer-sep-warn | PreToolUse | advisory | Warn on push when commits lack Reviewed-by: |
post-edit-format | PostToolUse | advisory | Auto-format edited files (ruff, prettier, biome) |
quality-gate | PostToolUse | advisory | Run linter + typechecker on edited files |
console-log-warn | PostToolUse | advisory | Warn 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-qualityandcommit-gauntletblock bad commits;block-no-verify,secrets-scan, andconfig-protectionblock dangerous writes. - Advisory gates print a warning and always exit 0 — they never block.
red-proof-warnandreviewer-sep-warnsurface 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-gauntletdetects 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-gauntletskips the typecheck stage on commits carrying aTested-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 pushregardless 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-gauntlettocommit-msgand, onpre-push, the advisory warnings plustest-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 whenpytest-testmonis absent). Seedocs/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
- Create
shared/rules/<name>.md - Add frontmatter mappings in
sync-to-repo.sh(CopilotapplyTo, Cursordescription/globs/alwaysApply) - Run
sync-to-repo.shon your repos
New skill
- Create
shared/skills/<name>/SKILL.md - Add frontmatter mappings in
sync-to-repo.sh(Copilot and Cursor skill metadata) - Run
sync-to-repo.shon your repos
New prompt
- Create
shared/prompts/<name>.md - Run
sync-to-repo.sh— Copilot prompts get*.prompt.mdformat automatically
New agent
- Create
shared/agents/<name>.agent.md - 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.