AGENTS.md

This file provides guidance to AI agents when working with code in this repository.

Repository Overview

This is Atelier - a personal development toolkit for spec-driven development, deep thinking, and code quality.

Skills Structure

Skills are located in the skills/ directory. Each skill is a self-contained module with:

skills/{category}-{name}/
├── SKILL.md           # Main skill definition
└── references/        # Optional additional context
    ├── topic-a.md
    └── topic-b.md

Skill File Format

Skills use YAML frontmatter for metadata:

---
name: skill-name
description: When to use this skill (AI reads this to auto-load)
user-invocable: false  # or true if user can call directly
---

Skills are auto-invoked based on description match to current context.

Subagent Dispatch in Skills

Skills describe the work a subagent does; they never name a specific agent. Runtime agent selection is defined once in the Delegation section of atelier-orchestrator. Other skills point to it rather than restating it.

Namespace Philosophy

Skills are organized into three namespaces based on their role:

spec: - Workflow Skills

Sequential, state-transforming steps that produce an approved plan and may produce artifacts.

• Process-oriented: Each skill is a step in a workflow
• User-invoked: Called explicitly by user or previous skill
• Output-producing: Each produces conversational or persisted output
• Disciplined: Must be followed exactly, not adapted

oracle: - Thinking Skills

Analytical, knowledge-providing skills that inform decisions.

• Knowledge-oriented: Provide patterns, principles, guidance
• Context-driven: Auto-invoked when relevant context detected
• Adaptable: Principles adapted to specific situation
• Supportive: Inform workflow decisions, don't produce artifacts

code: - Utility Skills

Tools and helpers for specific tasks.

• Task-oriented: Solve specific problems
• User-invoked: Called when needed
• Standalone: Can be used independently or within workflow

Namespace Semantics

Development

For local development with Claude Code:

claude --plugin-dir ./atelier

Restart Claude Code after making changes to reload skills.