Installation Guide

Relevant source files

The following files were used as context for generating this wiki page:

• INSTALL.md
• install.sh
• SETUP.md
• README.md
• AGENTS.md
• skills/docs-write/SKILL.md

This guide provides comprehensive instructions for installing the AI Dev Atelier skill pack. The installation process equips an AI agent, specifically OpenCode, with a suite of production-grade skills for development tasks such as code quality analysis, documentation, code review, and research. The process involves setting up dependencies, cloning the repository, and running scripts to deploy skills, Message Passing Channels (MCPs), and workflow hooks to the agent's environment.

The core of the installation is the install.sh script, which automates the deployment of skills to the ~/.opencode/skill directory. This allows the OpenCode agent to automatically discover and utilize them. For a faster, more condensed guide, refer to the SETUP.md.

Sources: README.md:1-19, INSTALL.md:1-3, SETUP.md:1-12

System Requirements and Dependencies

Before proceeding with the installation, ensure your system meets the following requirements. The installation process relies on several tools for both core functionality and optional features.

Sources: INSTALL.md:5-7

Required Dependencies

These tools are essential for the installation and basic operation of the skills.

Tool	Purpose	Verification Command
Git	Version control for cloning the repository.	git --version
Node.js 18+ or Bun	JavaScript runtime for code quality and other tools.	node --version or bun --version
OpenCode Agent	The target AI agent for skill installation.	Check for ~/.opencode directory.

Sources: INSTALL.md:9-41, SETUP.md:14-18

Optional Dependencies

These tools are required for specific skills or advanced features, such as automatic configuration and PR reviews.

Tool	Purpose	Required by Skill(s)	Verification Command
jq	JSON processor for automatic MCP configuration.	install.sh script	jq --version
GitHub CLI (gh)	Manages GitHub interactions.	resolve-pr-comments	gh --version
CodeRabbit CLI	Powers automated code reviews.	code-review	coderabbit --version
TypeScript	Project-specific type checking.	code-quality	npx tsc --version
ESLint	Project-specific linting.	code-quality	npx eslint --version
Prettier	Project-specific code formatting.	code-quality	npx prettier --version

Sources: INSTALL.md:43-111

Installation Process

The installation is a three-step process: cloning the repository, verifying the skill structure, and running the installation script. The install.sh script is the central component, handling the deployment of all necessary assets to the OpenCode agent's configuration directories.

Sources: README.md:21-25, SETUP.md:5-12

This diagram illustrates the high-level installation flow for a user.

Step 1: Clone the Repository

First, clone the ai-dev-atelier repository to your local machine. The recommended location is your home directory, but any path is acceptable as the scripts are location-aware.

git clone https://github.com/LukasStrickler/ai-dev-atelier.git ~/ai-dev-atelier

Sources: INSTALL.md:114-116

Step 2: Verify Skill Structure

Before installing, run the setup.sh script to ensure the repository's skill structure is intact. This script validates that all core skills and their SKILL.md definition files are present.

bash ~/ai-dev-atelier/setup.sh

Sources: SETUP.md:41-48

Step 3: Install Skills, MCPs, and Hooks

The install.sh script deploys all components to the OpenCode agent's environment. It is designed to be non-destructive, preserving existing configurations and providing a "smart diff" before overwriting any existing skills.

bash ~/ai-dev-atelier/install.sh

You can bypass the confirmation prompts by using the --yes or -y flag.

Sources: SETUP.md:50-59, INSTALL.md:128-136

The install.sh script performs the following actions:

1. Copies skill directories to ~/.opencode/skill.
2. Reads mcp.json and, if jq is installed, adds the defined MCP servers to the agent's configuration at ~/.opencode/opencode.json.
3. Copies hook definitions from hooks.json to ~/.opencode/hook/.

This diagram shows the logic of the install.sh script.

Installed Components

The installation script deploys three types of components: Skills, MCPs, and Hooks.

Skills

Skills are the primary component, providing the agent with new capabilities. They follow the Anthropic Agent Skills standard, where each skill is a self-contained directory.

Sources: SETUP.md:20-24, AGENTS.md:19-21

Available Skills:

Skill	Purpose
code-quality	Runs type checking, linting, and formatting.
docs-check	Detects documentation impact from git diffs.
docs-write	Writes or updates documentation based on project standards.
git-commit	Writes Conventional Commits formatted commit messages.
code-review	Performs code reviews using CodeRabbit.
resolve-pr-comments	Manages and resolves PR review comments.
search	Searches the web and library documentation.
research	Conducts academic research and creates evidence cards.
ui-animation	Guides implementation of UI animations.

Sources: README.md:30-44, SETUP.md:26-35

Skill Architecture and Agent Interaction:

An agent discovers and executes a skill by reading its SKILL.md file, which contains metadata and instructions, and then running the associated scripts.

MCP Integration

Message Passing Channels (MCPs) extend the agent's capabilities by connecting it to external services for tasks like web search and research. The install.sh script automatically configures these from the mcp.json file.

Configured MCP Servers:

MCP Server	Purpose	API Key Required
tavily-remote-mcp	Web search and research	TAVILY_API_KEY
context7	Library documentation search	Optional
openalex-research	Academic paper search	OPENALEX_EMAIL
pdf-reader	PDF text extraction	None
paper-search	Multi-platform academic paper search	Optional
grep	GitHub code search	None
zai-zread	GitHub repo semantic search	Z_AI_API_KEY
zai-vision	Image/video analysis and UI code generation	Z_AI_API_KEY

Sources: README.md:46-58, INSTALL.md:170-205, [AGENTS.md:51-64]

PreToolUse Hooks

Hooks are guardrails that intercept tool calls before execution to enforce specific workflows. The install.sh script deploys them to ~/.opencode/hook/.

Hook ID	Purpose
graphite-block	Blocks git push and gh pr create in Graphite-enabled repositories to enforce stacked PR workflows.
pr-comments-block	Blocks direct gh api calls for fetching PR comments, encouraging the use of the resolve-pr-comments skill.

Sources: AGENTS.md:41-49

Verification and Troubleshooting

After installation, verify that the agent recognizes the new skills. The most common issues relate to missing dependencies or incorrect paths.

Sources: INSTALL.md:244-245

Verification

1. Check Agent's Skill List: Ask your OpenCode agent, "What skills are available?". It should list the newly installed skills.
2. Verify Directory: Confirm that the skill directories exist in ~/.opencode/skill.
3. Run Validation Script: For a thorough check, run the project's validation script:

   bash .test/scripts/validate-skills.sh
   

Sources: SETUP.md:61-64, INSTALL.md:267-270

Troubleshooting

Issue	Solution
Skills not appearing in OpenCode	Verify skills are in ~/.opencode/skill and restart the agent.
permission denied on scripts	Run chmod +x ~/ai-dev-atelier/install.sh.
gh: command not found	Install the GitHub CLI and authenticate with gh auth login.
coderabbit: command not found	Install the CodeRabbit CLI globally (npm install -g @coderabbitai/cli).
MCP configuration failed	Install jq (brew install jq or sudo apt-get install jq).

Sources: INSTALL.md:247-265

Next Steps

With the installation complete, the AI agent is now equipped with the AI Dev Atelier skill pack. To learn more about how to use these skills and integrate them into your workflow, consult the following resources:

• SETUP.md: For quick setup, configuration, and usage examples.
• Individual Skill Documentation: Each skill's SKILL.md file (e.g., skills/code-quality/SKILL.md) contains detailed instructions and usage patterns.

Sources: INSTALL.md:272-278, SETUP.md:92-101