The Skill Framework
Relevant source files
The following files were used as context for generating this wiki page:
The AI Dev Atelier Skill Framework provides a production-grade suite of specialized capabilities for AI agents, focusing on tasks like code quality, documentation, code review, and research. It is designed to be used with AI agents that support the Anthropic Agent Skills standard, enabling them to perform complex development workflows by executing scripts, following instructional workflows, and integrating with external services via MCP (Multi-Capability Provider) servers.
The framework is structured to be modular and discoverable. Each skill is self-contained within a directory, providing instructions, executable scripts, and reference materials. This allows agents to dynamically load and utilize capabilities as needed, guided by clear instructions and guardrails embedded within the skills themselves.
Sources: README.md:18, AGENTS.md:5, skills/README.md:3-5
Architecture and Core Concepts
The framework is built around a standardized structure for defining and organizing skills, ensuring consistency and ease of use for AI agents.
Sources: AGENTS.md:11-17, skills/README.md:3-5
Skill Directory Structure
Each skill resides in its own directory within the skills/ folder. This directory encapsulates all necessary components for the skill to function, following the Anthropic Agent Skills standard.
The diagram below illustrates the standard directory structure for a skill.
SKILL.md: The core definition file for the skill. It contains YAML frontmatter and detailed markdown instructions for the agent.scripts/: A subdirectory containing executable bash scripts that the skill uses to perform its tasks.references/: A subdirectory holding supporting materials like guides, templates, and examples that the agent can load for additional context.
Sources: AGENTS.md:11-17, skills/README.md:133-138
SKILL.md Format
The SKILL.md file is the entry point for an agent to understand and use a skill. It follows a specific format:
---
name: skill-name
description: "Purpose and triggers (max 1024 chars)"
---
# Skill Name
## Instructions
...
## Workflow
...
## Examples
...
- YAML Frontmatter:
name: A unique identifier for the skill.description: A concise, one-line summary of the skill's purpose and trigger phrases, used by the agent for discovery.
- Markdown Body:
- Contains detailed instructions, workflows, examples, and references to scripts or other materials. This guides the agent on how and when to use the skill.
Sources: AGENTS.md:115-121, skills/README.md:3-5, 147-153
Agent Interaction with Skills
The interaction between an AI agent and a skill follows a discover-load-execute pattern.
This sequence diagram shows how an agent like OpenCode finds and executes a skill.
- Discovery: The agent scans a designated path (e.g.,
~/.opencode/skill) for directories containing aSKILL.mdfile. - Loading: For each skill found, the agent reads the
SKILL.mdfile, parsing the frontmatter and instructions to understand its capabilities. - Execution: When a task matches a skill's purpose, the agent follows the instructions in the
SKILL.mdfile. This may involve executing a bash script from thescripts/directory, following a workflow, or using an MCP tool.
Sources: skills/README.md:119-131, AGENTS.md:32-34
Available Skills
The framework includes a range of skills for various development tasks. They can be categorized into three main types: script-based, workflow-based, and MCP-based.
| Skill | Description | Type |
|---|---|---|
code-quality | Run comprehensive code quality checks including typecheck, lint, format, and markdown validation. | Script-based |
docs-check | Analyze git diff to identify code changes requiring documentation updates. | Script-based |
docs-write | Write or update documentation with clear style, structure, visuals, and standard patterns. | Workflow-based |
git-commit | Write clear git commits with Conventional Commits format. | Workflow-based |
code-review | Review code changes using CodeRabbit for uncommitted files or full PRs. | Script-based |
resolve-pr-comments | Multi-agent PR comment resolution for bot reviews. | Script-based |
search | Search the web and library documentation using Tavily and Context7 MCPs. | MCP-based |
research | Conduct academic research using OpenAlex and other MCPs, producing evidence cards. | Script-based & MCP-based |
ui-animation | Guide tasteful UI animation implementation with a focus on accessibility. | Workflow-based |
Sources: skills/README.md:8-23, README.md:30-43
Script-Based Skills
These skills are centered around one or more executable scripts. The agent's primary role is to invoke the correct script with the right parameters.
Example: docs-check Workflow
The docs-check skill analyzes git changes to suggest which documentation files may need updates.
Sources: skills/docs-check/SKILL.md:10-21
Workflow-Based Skills
These skills do not have a primary script. Instead, the SKILL.md provides a detailed, step-by-step process for the agent to follow. The agent executes a series of actions, often involving reading reference files and then generating content.
Example: docs-write Workflow
The docs-write skill guides an agent to write documentation according to project standards.
A critical instruction for documentation skills is to always load and adhere to the references/documentation-guide.md file before writing.
Sources: skills/docs-write/SKILL.md:15-53, AGENTS.md:103-105
MCP-Based Skills
These skills rely on Multi-Capability Provider (MCP) servers to interact with external APIs and services. The SKILL.md instructs the agent on which MCP tools to use for tasks like web search or academic research.
Example: research Skill
The research skill uses a combination of MCPs (OpenAlex, Tavily, PDF reader) and a structured workflow to produce comprehensive research reports with evidence cards. A mandatory "Write-First Pattern" is enforced to prevent context loss, requiring the agent to save its findings after processing only 1-2 sources.
Sources: skills/research/SKILL.md:1-6, 31-48, AGENTS.md:65-77
Supporting Components
Reference Guides
Many skills depend on shared reference guides located in their references/ subdirectories. The most prominent is the documentation-guide.md, which is a required dependency for all documentation-related skills (docs-check, docs-write, etc.). It provides standards on style, structure, and content.
Sources: skills/docs-write/SKILL.md:56-57, skills/docs-check/SKILL.md:32-35, skills/resolve-pr-comments/references/documentation-guide.md
Data Outputs
Skills are designed to be stateless, but they produce outputs in a designated, git-ignored directory: .ada/. This keeps the project root clean and separates runtime data from source code.
- Code reviews:
.ada/data/reviews/ - PR comment resolution:
.ada/data/pr-resolver/ - Research artifacts:
.ada/data/research/{topic}/
Sources: AGENTS.md:86-91, skills/README.md:155-159
Guardrails and Safety
The framework includes several mechanisms to ensure agents operate safely and follow established workflows.
- PreToolUse Hooks: Defined in
hooks.json, these hooks intercept tool calls to prevent unintended actions. For example, thegraphite-blockhook prevents directgit pushorgh pr createcommands in repositories managed by Graphite. - Skill Instructions: Each
SKILL.mdcontains explicit instructions and anti-patterns. For instance, theresearchskill mandates a "Write-First Pattern" to avoid context overload. - Configuration: The
skills-config.jsonfile allows for disabling specific skills on a per-agent basis.
Sources: AGENTS.md:29, 43-53, 103-113
Summary
The AI Dev Atelier Skill Framework is a robust and modular system for extending the capabilities of AI agents in software development. By standardizing skill definition, discovery, and execution, it allows agents to perform complex, multi-step tasks reliably. The framework's emphasis on explicit instructions, reference guides, and safety guardrails ensures that agents adhere to project conventions and best practices, making them effective collaborators in the development lifecycle.
Sources: README.md:18-20, AGENTS.md:5