Creating a New Skill

Relevant source files

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

• skills/README.md
• AGENTS.md
• README.md
• SETUP.md
• INSTALL.md
• skills/docs-write/SKILL.md
• skills/resolve-pr-comments/references/documentation-guide.md
• skills/research/references/guides/guide-workflow.md

Skills are specialized, self-contained capabilities that AI agents can discover and use to perform complex tasks related to software development. This project utilizes the Anthropic Agent Skills standard, where each skill is an organized directory containing instructions, executable scripts, and reference materials. This allows for a modular and extensible system for enhancing agent abilities in areas like code quality, documentation, and research.

Creating a new skill involves defining its purpose and trigger conditions, providing detailed instructions for the agent, and packaging any necessary scripts or reference guides. All skills are installed into a central directory (e.g., ~/.opencode/skill) where they can be automatically discovered and loaded by a compatible agent like OpenCode.

Sources: skills/README.md:3-5, AGENTS.md:5-6, SETUP.md:10-12

Skill Architecture

A skill is a directory that follows a standardized structure. This ensures that agents can reliably parse and execute them.

Sources: AGENTS.md:14-21, skills/README.md:141-144

Directory Structure

Each skill must be a directory containing a SKILL.md file and optional subdirectories for scripts and references.

This diagram illustrates the standard directory structure for a skill.

• SKILL.md (Required): The core file that defines the skill's metadata and provides instructions for the AI agent.
• scripts/ (Optional): Contains executable scripts (e.g., bash) that the agent can run to perform the skill's actions.
• references/ (Optional): Holds supplementary materials like documentation guides, templates, or examples that the agent should consult.

Sources: AGENTS.md:14-21, skills/README.md:141-144, skills/docs-write/SKILL.md

The SKILL.md File

The SKILL.md file is the entry point for any skill. It must start with a YAML frontmatter block containing the skill's name and description. The body of the file, written in Markdown, contains detailed instructions for the agent.

Sources: AGENTS.md:118-123, skills/README.md:152-157

---
name: skill-name
description: "Purpose and triggers (max 1024 chars)"
---

# Skill Title

## Workflow
Detailed instructions for the agent on how to use the skill.

## When to Use
Trigger conditions and scenarios.

## Examples
Example invocations or use cases.

Sources: AGENTS.md:119-122, skills/README.md:153-156

The description field is critical, as it's used by the agent to discover the skill and decide when to use it. It should be a concise, one-line summary of the skill's purpose and triggers.

Sources: skills/README.md:154, AGENTS.md:120

Skill Types

Skills can be categorized into two main types based on their execution model.

Type	Description	Examples
Script-based	The skill's primary action is to execute one or more scripts located in its scripts/ directory.	code-quality, docs-check, code-review
Workflow	The skill provides a detailed set of instructions and mental models for the agent to follow, without relying on executable scripts.	docs-write, git-commit, ui-animation

Sources: README.md:36-49, skills/README.md:10-21

Agent Interaction and Execution

The process from skill discovery to execution follows a standard flow defined by the Anthropic Agent Skills specification.

Sources: SETUP.md:65-76, skills/README.md:128-139

Discovery and Execution Flow

This sequence diagram shows how an agent discovers, loads, and executes a skill.

1. Discovery: The agent scans a designated skill directory (e.g., ~/.opencode/skill) for subdirectories containing a SKILL.md file.
2. Loading: For each skill found, the agent reads SKILL.md to load its name, description, and instructions into its context.
3. Execution: When a user's request matches a skill's description or triggers, the agent follows the instructions in the SKILL.md body. If it's a script-based skill, it executes the relevant script via a bash command.

Sources: SETUP.md:66-74, INSTALL.md:275-283

Installation and Validation

For a skill to be usable, it must be placed in the agent's skill directory and validated.

Installation

The install.sh script handles the deployment of skills from the repository to the local agent's configuration.

This flowchart shows the skill installation process.

The script copies the skill directories to ~/.opencode/skill, preserving any existing configurations. It can be re-run to update skills.

Sources: INSTALL.md:154-164, SETUP.md:46-54

Validation

Human contributors must validate the structure and integrity of any new or modified skills before committing changes. The project provides a script for this purpose.

bash .test/scripts/validate-skills.sh

This script verifies that:

• The skills/ directory exists.
• Core skills are present.
• Each skill has a valid SKILL.md file.

Sources: AGENTS.md:131-132, SETUP.md:60-63

Conclusion

Creating a new skill for the AI Dev Atelier involves adhering to the Anthropic Agent Skills standard. A developer must define the skill's purpose in a SKILL.md file, provide clear instructions, and optionally include executable scripts and reference materials. By following the established directory structure and validation process, new skills can be seamlessly integrated into an agent's capabilities, extending its utility for complex software development tasks.

Sources: skills/README.md:3-5, AGENTS.md:134-138