Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Configuration in the AI Dev Atelier project allows for the customization of agent capabilities, integration with external services via Multi-Capability Providers (MCPs), and enforcement of specific development workflows through hooks. The primary configuration files include skills-config.json for skill filtering, mcp.json for defining MCP servers, and hooks.json for workflow guardrails. Environment variables, typically managed in a .env file, are used for API keys.
The overall configuration process is initiated during setup and installation, where scripts read these files to tailor the agent's environment.
This diagram shows the relationship between the core configuration files and the agent's environment.
Sources: README.md:19-22, AGENTS.md:18-26
Agent Skill Filtering
The skills-config.json file provides a mechanism to enable or disable specific skills for different AI agents. This allows for creating tailored environments where an agent only has access to the tools relevant to its designated role.
Sources: README.md:58, AGENTS.md:12-16, AGENTS.md:126-127
Structure
The file is a JSON object where keys are agent identifiers (e.g., "OpenCode") and values are objects mapping skill names to a boolean (true for enabled, false for disabled).
{
"OpenCode": {
"code-quality": true,
"docs-check": true,
"docs-write": true,
"git-commit": true,
"code-review": true,
"resolve-pr-comments": true,
"search": true,
"research": true,
"ui-animation": true,
"use-graphite": true
}
}
Sources: skills-config.json:1-14
The install.sh script uses this file to determine which skills to install for a given agent.
Sources: README.md:22
MCP Configuration
Multi-Capability Providers (MCPs) extend the agent's abilities by connecting to external services for tasks like web search, documentation lookup, and academic research. The configuration is split between mcp.json for server definitions and a .env file for API keys.
Sources: README.md:62-73, AGENTS.md:86-99
MCP Server Definitions (mcp.json)
This file defines the available MCP servers that the agent can connect to. The install.sh script processes this file to set up the MCPs.
Sources: AGENTS.md:18-26, README.md:22
{
"mcp_servers": [
{
"name": "tavily-remote-mcp",
"url": "https://github.com/LukasStrickler/tavily-remote-mcp.git%22
},
{
"name": "context7",
"url": "https://github.com/context-labs/context7-mcp.git%22
},
{
"name": "grep",
"url": "https://github.com/OpenCode-OpenSource/Grep-MCP.git%22
},
{
"name": "openalex-research",
"url": "https://github.com/LukasStrickler/openalex-research-mcp.git%22
},
{
"name": "pdf-reader",
"url": "https://github.com/LukasStrickler/pdf-reader-mcp.git%22
},
{
"name": "paper-search",
"url": "https://github.com/LukasStrickler/paper-search-mcp.git%22
},
{
"name": "zai-zread",
"url": "https://github.com/z-ai-company/zread-mcp.git%22
},
{
"name": "zai-vision",
"url": "https://github.com/z-ai-company/vision-mcp.git%22
}
]
}
Sources: mcp.json:1-30
API Keys and Environment Variables
API keys for MCP services are managed via a .env file at the project root. This file should be created from .env.example before running the installation script.
Sources: README.md:19, AGENTS.md:113
The following table summarizes the MCP servers and their required environment variables for authentication.
| MCP Server | Purpose | Required Key / Env Var |
|---|---|---|
tavily-remote-mcp | Web search and research | TAVILY_API_KEY |
context7 | Library documentation | CONTEXT7_API_KEY (Optional) |
grep | GitHub code search | None |
openalex-research | Academic papers and citations | OPENALEX_EMAIL |
pdf-reader | PDF extraction | None |
paper-search | Multi-platform paper search | Optional keys |
zai-zread | GitHub repo semantic search | Z_AI_API_KEY |
zai-vision | Image/video analysis, UI code gen | Z_AI_API_KEY |
Sources: README.md:64-73, AGENTS.md:88-99
Z.AI MCP Tool Filtering
For agents like OpenCode, specific tools provided by the Z.AI MCPs can be disabled to save API quota or avoid redundancy with native tools. This is configured in the agent's own configuration file (e.g., ~/.opencode/opencode.json).
Sources: AGENTS.md:101-104
To disable certain tools, add a "tools" key to the agent's configuration file:
{
"tools": {
"zai-zread_read_file": false,
"zai-zread_get_repo_structure": false,
"zai-vision_image_analysis": false,
"zai-vision_extract_text_from_screenshot": false
}
}
Sources: AGENTS.md:106-112
The recommendation is to disable these because free alternatives exist, such as using webfetch for reading files or the native look_at tool for image analysis.
Sources: AGENTS.md:115-120
Workflow Hooks (hooks.json)
PreToolUse hooks act as workflow guardrails by intercepting tool calls before they are executed. This prevents common mistakes, such as using conflicting git commands in a Graphite-managed repository. The hooks.json file defines these hooks, which are installed by install.sh.
Sources: AGENTS.md:65-67, README.md:82-84
Hook Definitions
| Hook ID | Matcher | Purpose |
|---|---|---|
graphite-block | Bash | Blocks git push, git checkout -b, and gh pr create in Graphite-enabled repositories to enforce the stacked PR workflow. |
pr-comments-block | Bash | Blocks gh api calls that fetch PR comments, encouraging the use of the more efficient resolve-pr-comments skill instead. |
Sources: AGENTS.md:69-73, hooks.json:2-20
This is the structure of hooks.json:
{
"hooks": [
{
"id": "graphite-block",
"matcher": {
"tool_name": "bash"
},
"script_path": "skills/use-graphite/scripts/graphite-block-hook.sh"
},
{
"id": "pr-comments-block",
"matcher": {
"tool_name": "bash"
},
"script_path": "skills/resolve-pr-comments/scripts/pr-resolver-block-hook.sh"
}
]
}
Sources: hooks.json:1-21
Optional Configuration
Some skills may support their own optional configuration files. For example, the docs-check skill can load an optional .docs-check-config.json file if it exists in the project root. The presence of this file allows for future extensions, although its implementation is currently a placeholder.