Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides a comprehensive overview of the ai-dev-atelier project, including setup, installation, core components, and basic usage. The project is a production-grade skill pack for AI agents, designed to enhance development workflows with tools for code quality, documentation, code review, and research. It follows the Anthropic Agent Skills standard and integrates with Multi-Capability Providers (MCPs).
The primary goal is to equip AI agents with a suite of executable skills that can be used to perform common development tasks. These skills are installed into the agent's environment and can be invoked to analyze code, check for required documentation updates, write commits, and more.
Sources: README.md:15-17, AGENTS.md:5-6
Installation and Setup
The setup process involves cloning the repository, verifying its structure, and running an installation script that deploys the skills and configures MCPs for your agent.
Sources: README.md:21-25
Prerequisites
Before installation, you must copy the .env.example file to .env and populate it with the API keys for any MCPs you intend to use, such as TAVILY_API_KEY or OPENALEX_EMAIL.
Sources: README.md:19-20, README.md:50-51, AGENTS.md:82-89
Installation Flow
The installation is a two-step process handled by shell scripts. First, setup.sh verifies the repository structure. Then, install.sh copies the skills and configurations to the appropriate agent directory (e.g., ~/.opencode/skill for OpenCode).
This diagram illustrates the setup and installation workflow.
Sources: README.md:21-25, AGENTS.md:29-32, setup.sh, install.sh
The installation commands are as follows:
git clone https://github.com/LukasStrickler/ai-dev-atelier.git ~/ai-dev-atelier
bash ~/ai-dev-atelier/setup.sh
bash ~/ai-dev-atelier/install.sh
Sources: README.md:22-24
After running install.sh, you can verify the installation by asking your agent "What skills are available?" or by checking the contents of the agent's skill directory (e.g., ~/.opencode/skill).
Sources: README.md:27-29
Project Structure
The repository is organized into several key directories, with skills/ containing the core agent capabilities and .ada/ serving as the output directory for runtime data.
This diagram shows the high-level directory structure.
Sources: AGENTS.md:12-23
Key Directories
| Path | Description |
|---|---|
skills/ | Contains the 9 skill directories, each with a SKILL.md, scripts/, and references/. |
.ada/ | Git-ignored directory for all runtime data outputs, such as code reviews and research reports. |
.test/ | Contains validation and integration tests for the skills. |
hooks.json | Defines PreToolUse hooks that enforce workflow guardrails. |
install.sh | Script to deploy skills, MCPs, and hooks to the agent's environment. |
setup.sh | Script to verify the repository and skill structure before installation. |
mcp.json | Defines the MCP (Multi-Capability Provider) servers used by the skills. |
Sources: AGENTS.md:12-23, README.md:61-66
Core Components
The ai-dev-atelier is composed of skills, MCP integrations, and workflow hooks.
Skills
Skills are the primary components, providing specific capabilities to the AI agent. Each skill is defined by a SKILL.md file and may include executable scripts.
| Skill | Purpose | Entry Point |
|---|---|---|
code-quality | Typecheck, lint, format, and validate markdown. | skills/code-quality/scripts/finalize.sh |
docs-check | Detect documentation impact from git diffs. | skills/docs-check/scripts/check-docs.sh |
docs-write | Write or update documentation using project standards. | Workflow skill (no script) |
git-commit | Write clear commits in Conventional Commits format. | Workflow skill (no script) |
code-review | Run CodeRabbit-style reviews on tasks or PRs. | skills/code-review/scripts/review-run.sh |
resolve-pr-comments | A multi-agent workflow to resolve PR comments. | skills/resolve-pr-comments/scripts/pr-resolver*.sh |
search | Perform web and library documentation searches. | MCP-based (no script) |
research | Conduct academic research and generate evidence cards. | skills/research/scripts/research-*.sh |
ui-animation | Guide the implementation of tasteful UI animations. | Workflow skill (no script) |
Sources: README.md:33-48, AGENTS.md:26-38
MCPs (Multi-Capability Providers)
MCPs provide external capabilities like web search, academic paper retrieval, and code search. They are defined in mcp.json and often require API keys set in the .env file.
| MCP Server | Purpose | API Key / Env Var |
|---|---|---|
tavily-remote-mcp | Web search and research | TAVILY_API_KEY |
context7 | Library documentation search | CONTEXT7_API_KEY (optional) |
openalex-research | Academic papers and citations | OPENALEX_EMAIL |
pdf-reader | PDF content extraction | None |
paper-search | Search across multiple academic platforms | Optional keys |
grep | GitHub code search | None |
zai-zread | Semantic search for GitHub repos (issues, PRs, docs) | Z_AI_API_KEY |
zai-vision | Image/video analysis and UI code generation | Z_AI_API_KEY |
Sources: README.md:50-60, AGENTS.md:82-89
PreToolUse Hooks
The project uses hooks defined in hooks.json to intercept tool calls and enforce workflow guardrails. For example, they can prevent direct git push commands in a Graphite-enabled repository or block redundant API calls to fetch PR comments. These hooks are installed by install.sh.
Sources: AGENTS.md:70-79
Basic Workflow Example
Once installed, the skills can be used to automate parts of the development workflow. A common use case is checking for documentation impact after making code changes.
The following sequence diagram shows how a developer or agent might use the docs-check skill.
The docs-check.sh script analyzes the output of git diff to categorize code changes (e.g., schema, API, UI) and suggests relevant documentation files that may need updating. This helps ensure that documentation stays synchronized with the codebase.
Sources: skills/docs-check/scripts/check-docs.sh:65-79, AGENTS.md:34
Conclusion
The ai-dev-atelier project provides a powerful, extensible framework for enhancing AI-assisted development. By following the setup instructions, developers can equip their agents with a robust set of skills for improving code quality, maintaining documentation, and streamlining research. The modular structure, based on the Anthropic Agent Skills standard, allows for easy integration and customization within supported agent environments like OpenCode.
Sources: README.md:15-17, AGENTS.md:5-6