AGENTS.md · diff
git:20260728.b1fb1f7 to git:20261017.81dd276
6 added, 0 removed. Audit A to A.
# 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:
```yaml
---
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
| Namespace | Type | Invocation | Output | Flexibility |
|-----------|------|------------|--------|-------------|
| spec: | Process | User/previous skill | Plan/artifact | Follow exactly |
| oracle: | Knowledge | Context-driven | Guidance | Adapt to context |
| code: | Utility | User | Result | Use as needed |
## Development
For local development with Claude Code:
```bash
claude --plugin-dir ./atelier
```
Restart Claude Code after making changes to reload skills.