@samitouri / QOSami_Agents_Zero-2 / commits / 99d5bf6f

feat: add development framework support with skill system and UI

Add a framework selection system that lets users choose structured development workflows. Frameworks provide curated skills that guide the agent through established methodologies. Features: - Framework registry with 11 frameworks: GSD, Superpowers, BMAD, BMAD Builder, BMAD Creative Intelligence Suite, BMAD Game Dev Studio, Spec Kit, PRP, AgentOS, AMPLIHACK, and Agent Zero Dev - 62 workflow skills organized by framework - Global framework selection in Settings > Agent > Framework - Per-project framework override (Settings > Projects > Edit) - Framework-aware skill discovery prioritizes active framework's skills - System prompt injection provides workflow context to the agent - Skills Import moved to dedicated Settings tab Backend: - python/helpers/frameworks.py: Framework registry and utilities - python/api/frameworks.py: Framework list/get API endpoint - python/helpers/settings.py: Added dev_framework setting - python/helpers/projects.py: Added dev_framework to project config - python/helpers/skills.py: Framework-aware get_skill_roots() - python/tools/skills_tool.py: Pass framework_id to skill helpers - python/extensions/message_loop_prompts_after/_55_recall_skills.py: Framework context in skill recall - python/extensions/system_prompt/_10_system_prompt.py: Framework prompt Frontend: - webui/components/settings/agent/framework.html: Framework selector - webui/components/settings/frameworks/: Framework details modal + store - webui/components/settings/skills/skills-settings.html: Skills tab Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

TerminallyLazy committed Jan 29, 2026 at 18:25 UTC 99d5bf6f057d3cf6a4bd976b0c394f5fc16df7f8
139 files changed +19791 -111
.dockerignore
+4 -4
@@ -15,10 +15,10 @@ knowledge/**
15 !knowledge/default/
16 !knowledge/default/**
17
18 -# Instruments directory – keep only default/
19 -instruments/**
20 -!instruments/default/
21 -!instruments/default/**
18 +# Skills directory – keep only builtin/
19 +skills/**
20 +!skills/builtin/
21 +!skills/builtin/**
22
23 # Keep .gitkeep markers anywhere
24 !**/.gitkeep
.gitignore
+8 -6
@@ -33,12 +33,12 @@ knowledge/**
33 !knowledge/default/
34 !knowledge/default/**
35
36 -# Handle instruments directory
37 -instruments/**
38 -!instruments/**/
39 -# Explicitly allow the default folder in instruments
40 -!instruments/default/
41 -!instruments/default/**
36 +# Handle skills directory (SKILL.md standard)
37 +skills/**
38 +!skills/**/
39 +# Explicitly allow the builtin folder in skills
40 +!skills/builtin/
41 +!skills/builtin/**
42
43 # Global rule to include .gitkeep files anywhere
44 !**/.gitkeep
@@ -46,3 +46,5 @@ instruments/**
46 # for browser-use
47 agent_history.gif
48
49 +.agent/**
50 +.claude/**
README.md
+1 -1
@@ -63,7 +63,7 @@ Agent Zero now supports **Projects** – isolated workspaces with their own prom
63 - Tool usage functionality has been developed from scratch to be the most compatible and reliable, even with very small models.
64 - **Default Tools:** Agent Zero includes tools like knowledge, code execution, and communication.
65 - **Creating Custom Tools:** Extend Agent Zero's functionality by creating your own custom tools.
66 -- **Instruments:** Instruments are a new type of tool that allow you to create custom functions and procedures that can be called by Agent Zero.
66 +- **Skills (SKILL.md Standard):** Skills are contextual expertise loaded dynamically when relevant. They use the open SKILL.md standard (developed by Anthropic), making them compatible with Claude Code, Cursor, Goose, OpenAI Codex CLI, and GitHub Copilot.
67
68 3. **Multi-agent Cooperation**
69
docs/CONTRIBUTING-SKILLS.md new
+468
@@ -0,0 +1,468 @@
1 +# Contributing Skills to Agent Zero
2 +
3 +Welcome to the Agent Zero Skills ecosystem! This guide will help you create, test, and share skills with the community.
4 +
5 +## Table of Contents
6 +
7 +- [What is a Skill?](#what-is-a-skill)
8 +- [Quick Start](#quick-start)
9 +- [SKILL.md Standard](#skillmd-standard)
10 +- [Creating Your First Skill](#creating-your-first-skill)
11 +- [Best Practices](#best-practices)
12 +- [Testing Skills](#testing-skills)
13 +- [Sharing Skills](#sharing-skills)
14 +- [Community Guidelines](#community-guidelines)
15 +
16 +---
17 +
18 +## What is a Skill?
19 +
20 +A **Skill** is a contextual expertise module that provides the AI agent with specialized knowledge and procedures for specific tasks. Unlike tools (which are always loaded), skills are **semantically recalled** when relevant, making them token-efficient and context-aware.
21 +
22 +### Skills vs Tools vs Knowledge
23 +
24 +| Aspect | Skills | Tools | Knowledge |
25 +|--------|--------|-------|-----------|
26 +| **Loading** | Semantic recall | Always in prompt | Semantic recall |
27 +| **Purpose** | Procedures & expertise | Actions & functions | Facts & data |
28 +| **Format** | SKILL.md (YAML + Markdown) | Python/code | Text/documents |
29 +| **When to use** | "How to do X" | "Do X now" | "What is X" |
30 +
31 +### Cross-Platform Compatibility
32 +
33 +The SKILL.md standard is compatible with:
34 +- **Agent Zero** (this project)
35 +- **Claude Code** (Anthropic)
36 +- **Cursor** (AI IDE)
37 +- **OpenAI Codex CLI**
38 +- **GitHub Copilot**
39 +- **Goose** (Block)
40 +
41 +Skills you create here can be used in any of these platforms!
42 +
43 +---
44 +
45 +## Quick Start
46 +
47 +### Using the CLI (Recommended)
48 +
49 +```bash
50 +# Create a new skill interactively
51 +python -m python.helpers.skills_cli create my-skill-name
52 +
53 +# List all available skills
54 +python -m python.helpers.skills_cli list
55 +
56 +# Validate a skill
57 +python -m python.helpers.skills_cli validate my-skill-name
58 +
59 +# Search skills
60 +python -m python.helpers.skills_cli search "keyword"
61 +```
62 +
63 +### Manual Creation
64 +
65 +1. Create a folder in `skills/custom/` with your skill name
66 +2. Add a `SKILL.md` file with YAML frontmatter
67 +3. Optionally add supporting scripts (`.py`, `.sh`, `.js`)
68 +
69 +---
70 +
71 +## SKILL.md Standard
72 +
73 +Every skill must have a `SKILL.md` file with this structure:
74 +
75 +```markdown
76 +---
77 +name: "skill-name"
78 +description: "A clear, concise description of what this skill does and when to use it"
79 +version: "1.0.0"
80 +author: "Your Name <email@example.com>"
81 +license: "MIT"
82 +tags: ["category", "purpose", "technology"]
83 +triggers:
84 + - "keyword that activates this skill"
85 + - "another trigger phrase"
86 +allowed_tools:
87 + - tool_name
88 + - another_tool
89 +metadata:
90 + complexity: "beginner|intermediate|advanced"
91 + category: "development|devops|data|productivity|creative"
92 + estimated_time: "5 minutes"
93 +---
94 +
95 +# Skill Name
96 +
97 +## Overview
98 +
99 +Brief description of what this skill accomplishes.
100 +
101 +## When to Use
102 +
103 +- Situation 1 where this skill applies
104 +- Situation 2 where this skill applies
105 +
106 +## Instructions
107 +
108 +### Step 1: First Step
109 +
110 +Detailed instructions...
111 +
112 +### Step 2: Second Step
113 +
114 +More instructions...
115 +
116 +## Examples
117 +
118 +### Example 1: Basic Usage
119 +
120 +\`\`\`python
121 +# Code example
122 +\`\`\`
123 +
124 +### Example 2: Advanced Usage
125 +
126 +\`\`\`python
127 +# Advanced code example
128 +\`\`\`
129 +
130 +## Common Pitfalls
131 +
132 +- Pitfall 1 and how to avoid it
133 +- Pitfall 2 and how to avoid it
134 +
135 +## Related Skills
136 +
137 +- [related-skill-1](../related-skill-1/SKILL.md)
138 +- [related-skill-2](../related-skill-2/SKILL.md)
139 +```
140 +
141 +### Required Fields
142 +
143 +| Field | Description |
144 +|-------|-------------|
145 +| `name` | Unique identifier (lowercase, hyphens allowed) |
146 +| `description` | What the skill does (used for semantic matching) |
147 +
148 +### Optional Fields
149 +
150 +| Field | Description |
151 +|-------|-------------|
152 +| `version` | Semantic version (e.g., "1.0.0") |
153 +| `author` | Your name and email |
154 +| `license` | License (MIT, Apache-2.0, etc.) |
155 +| `tags` | Categories for discovery |
156 +| `triggers` | Phrases that activate this skill |
157 +| `allowed_tools` | Tools this skill can use |
158 +| `metadata` | Additional structured data |
159 +
160 +---
161 +
162 +## Creating Your First Skill
163 +
164 +### Step 1: Identify the Need
165 +
166 +Ask yourself:
167 +- What expertise would help the agent?
168 +- When should this skill be activated?
169 +- What steps should the agent follow?
170 +
171 +### Step 2: Create the Structure
172 +
173 +```bash
174 +# Using CLI
175 +python -m python.helpers.skills_cli create my-awesome-skill
176 +
177 +# Or manually
178 +mkdir -p skills/custom/my-awesome-skill
179 +touch skills/custom/my-awesome-skill/SKILL.md
180 +```
181 +
182 +### Step 3: Write the SKILL.md
183 +
184 +```markdown
185 +---
186 +name: "my-awesome-skill"
187 +description: "Helps with [specific task] when [specific situation]"
188 +version: "1.0.0"
189 +author: "Your Name"
190 +tags: ["category"]
191 +---
192 +
193 +# My Awesome Skill
194 +
195 +## When to Use
196 +
197 +Use this skill when you need to [specific task].
198 +
199 +## Instructions
200 +
201 +1. First, do this...
202 +2. Then, do that...
203 +3. Finally, verify by...
204 +
205 +## Examples
206 +
207 +### Example: Basic Case
208 +
209 +[Show a complete example]
210 +```
211 +
212 +### Step 4: Add Supporting Files (Optional)
213 +
214 +If your skill needs scripts:
215 +
216 +```
217 +my-awesome-skill/
218 +├── SKILL.md # Required
219 +├── helper.py # Optional Python script
220 +├── setup.sh # Optional shell script
221 +└── templates/ # Optional templates folder
222 + └── config.json
223 +```
224 +
225 +Reference them in your SKILL.md:
226 +
227 +```markdown
228 +## Scripts
229 +
230 +This skill includes helper scripts:
231 +- `helper.py` - Does X
232 +- `setup.sh` - Sets up Y
233 +```
234 +
235 +### Step 5: Test Your Skill
236 +
237 +```bash
238 +# Validate the skill
239 +python -m python.helpers.skills_cli validate my-awesome-skill
240 +
241 +# Test in Agent Zero
242 +# Start the agent and ask it to perform the task your skill handles
243 +```
244 +
245 +---
246 +
247 +## Best Practices
248 +
249 +### Writing Effective Descriptions
250 +
251 +The `description` field is crucial for semantic matching. Make it:
252 +
253 +**Good:**
254 +```yaml
255 +description: "Guides systematic debugging of Python applications using print statements, debugger, and logging to identify root causes"
256 +```
257 +
258 +**Bad:**
259 +```yaml
260 +description: "Helps with debugging"
261 +```
262 +
263 +### Structuring Instructions
264 +
265 +1. **Be Specific** - Avoid vague instructions
266 +2. **Use Steps** - Number your steps clearly
267 +3. **Include Examples** - Show, don't just tell
268 +4. **Anticipate Errors** - Include troubleshooting
269 +
270 +### Semantic Triggers
271 +
272 +Design your description and content so the skill is recalled when relevant:
273 +
274 +```yaml
275 +# Include synonyms and related terms
276 +description: "Helps create REST APIs, web services, HTTP endpoints, and backend routes using FastAPI, Flask, or Express"
277 +```
278 +
279 +### Keep Skills Focused
280 +
281 +One skill = one expertise area. If your skill is getting too long, split it:
282 +
283 +- `api-design` - API structure and patterns
284 +- `api-security` - API authentication and authorization
285 +- `api-testing` - API testing strategies
286 +
287 +---
288 +
289 +## Testing Skills
290 +
291 +### Local Testing
292 +
293 +1. **Validate Structure:**
294 + ```bash
295 + python -m python.helpers.skills_cli validate my-skill
296 + ```
297 +
298 +2. **Test Semantic Recall:**
299 + Start Agent Zero and ask questions that should trigger your skill.
300 +
301 +3. **Verify Instructions:**
302 + Follow your own instructions manually to ensure they work.
303 +
304 +### Automated Testing
305 +
306 +Create a test file `test_skill.py` in your skill folder:
307 +
308 +```python
309 +"""Tests for my-awesome-skill"""
310 +import pytest
311 +from python.helpers.skills import SkillManager
312 +
313 +def test_skill_loads():
314 + manager = SkillManager()
315 + skill = manager.get_skill("my-awesome-skill")
316 + assert skill is not None
317 + assert skill.name == "my-awesome-skill"
318 +
319 +def test_skill_has_required_fields():
320 + manager = SkillManager()
321 + skill = manager.get_skill("my-awesome-skill")
322 + assert skill.description
323 + assert len(skill.description) > 20
324 +```
325 +
326 +---
327 +
328 +## Sharing Skills
329 +
330 +### Contributing to Agent Zero
331 +
332 +1. **Fork the Repository:**
333 + ```bash
334 + git clone https://github.com/agent0ai/agent-zero.git
335 + cd agent-zero
336 + ```
337 +
338 +2. **Create Your Skill:**
339 + ```bash
340 + python -m python.helpers.skills_cli create my-skill
341 + # Edit skills/custom/my-skill/SKILL.md
342 + ```
343 +
344 +3. **Move to Builtin (for contribution):**
345 + ```bash
346 + mv skills/custom/my-skill skills/builtin/my-skill
347 + ```
348 +
349 +4. **Create a Pull Request:**
350 + - Branch: `feat/skill-my-skill-name`
351 + - Title: `feat(skills): add my-skill-name skill`
352 + - Description: Explain what the skill does and why it's useful
353 +
354 +### Publishing to Skills Marketplace
355 +
356 +Share your skills on [skillsmp.com](https://skillsmp.com):
357 +
358 +1. Create a GitHub repository for your skill
359 +2. Ensure it follows the SKILL.md standard
360 +3. Submit to the marketplace via their contribution process
361 +
362 +### Creating a Skills Collection
363 +
364 +For multiple related skills, create a repository:
365 +
366 +```
367 +my-skills-collection/
368 +├── README.md
369 +├── skills/
370 +│ ├── skill-1/
371 +│ │ └── SKILL.md
372 +│ ├── skill-2/
373 +│ │ └── SKILL.md
374 +│ └── skill-3/
375 +│ └── SKILL.md
376 +└── LICENSE
377 +```
378 +
379 +---
380 +
381 +## Community Guidelines
382 +
383 +### Quality Standards
384 +
385 +- **Tested** - Skills must be tested before submission
386 +- **Documented** - Clear instructions and examples
387 +- **Focused** - One expertise per skill
388 +- **Original** - Don't duplicate existing skills
389 +
390 +### Naming Conventions
391 +
392 +- Use lowercase with hyphens: `my-skill-name`
393 +- Be descriptive: `python-debugging` not `debug`
394 +- Avoid generic names: `fastapi-crud` not `api`
395 +
396 +### License
397 +
398 +- Include a license (MIT recommended for maximum compatibility)
399 +- Respect licenses of any code you include
400 +- Don't include proprietary or copyrighted content
401 +
402 +### Code of Conduct
403 +
404 +- Be respectful in all interactions
405 +- Provide constructive feedback
406 +- Help newcomers learn
407 +- Report issues responsibly
408 +
409 +---
410 +
411 +## Resources
412 +
413 +### Official Documentation
414 +
415 +- [Agent Zero Documentation](./README.md)
416 +- [Architecture Guide](./architecture.md)
417 +- [Skills System](./architecture.md#skills-system)
418 +
419 +### Community
420 +
421 +- [GitHub Issues](https://github.com/agent0ai/agent-zero/issues)
422 +- [Discussions](https://github.com/agent0ai/agent-zero/discussions)
423 +
424 +### External Resources
425 +
426 +- [Skills Marketplace](https://skillsmp.com)
427 +- [Awesome Agent Skills](https://github.com/skillmatic-ai/awesome-agent-skills)
428 +- [Anthropic Skills Repository](https://github.com/anthropics/skills)
429 +
430 +---
431 +
432 +## FAQ
433 +
434 +### Q: Where should I put my skills?
435 +
436 +**A:** During development, use `skills/custom/`. For contribution, move to `skills/builtin/`.
437 +
438 +### Q: How are skills discovered?
439 +
440 +**A:** Skills are indexed in a vector database. When you ask the agent something, it searches for relevant skills based on semantic similarity to your query.
441 +
442 +### Q: Can I use skills from other platforms?
443 +
444 +**A:** Yes! The SKILL.md standard is cross-platform. Skills from Claude Code, Cursor, or other compatible platforms can be copied directly to `skills/shared/`.
445 +
446 +### Q: How do I update a skill?
447 +
448 +**A:** Edit the SKILL.md file and increment the version number. Changes take effect on agent restart.
449 +
450 +### Q: Can skills call other skills?
451 +
452 +**A:** Skills don't directly call each other, but the agent may combine multiple skills when appropriate for a task.
453 +
454 +---
455 +
456 +## Example Skills to Learn From
457 +
458 +Check out these well-structured skills in `skills/builtin/`:
459 +
460 +- `brainstorming/` - Requirements exploration workflow
461 +- `debugging/` - Systematic debugging methodology
462 +- `tdd/` - Test-driven development process
463 +- `code_review/` - Comprehensive review checklist
464 +- `create_skill/` - Meta-skill for creating new skills
465 +
466 +---
467 +
468 +Happy skill building! 🚀
docs/README.md
+1 -1
@@ -56,7 +56,7 @@ To begin with Agent Zero, follow the links below for detailed guides on various
56 - [Messages History and Summarization](archicture.md#messages-history-and-summarization)
57 - [Prompts](architecture.md#4-prompts)
58 - [Knowledge](architecture.md#5-knowledge)
59 - - [Instruments](architecture.md#6-instruments)
59 + - [Skills](architecture.md#6-skills)
60 - [Extensions](architecture.md#7-extensions)
61 - [Contributing](contribution.md)
62 - [Getting Started](contribution.md#getting-started)
docs/architecture.md
+54 -20
@@ -2,11 +2,11 @@
2 Agent Zero is built on a flexible and modular architecture designed for extensibility and customization. This section outlines the key components and the interactions between them.
3
4 ## System Architecture
5 -This simplified diagram illustrates the hierarchical relationship between agents and their interaction with tools, extensions, instruments, prompts, memory and knowledge base.
5 +This simplified diagram illustrates the hierarchical relationship between agents and their interaction with tools, extensions, skills, prompts, memory and knowledge base.
6
7 ![Agent Zero Architecture](res/arch-01.svg)
8
9 -The user or Agent 0 is at the top of the hierarchy, delegating tasks to subordinate agents, which can further delegate to other agents. Each agent can utilize tools and access the shared assets (prompts, memory, knowledge, extensions and instruments) to perform its tasks.
9 +The user or Agent 0 is at the top of the hierarchy, delegating tasks to subordinate agents, which can further delegate to other agents. Each agent can utilize tools and access the shared assets (prompts, memory, knowledge, extensions and skills) to perform its tasks.
10
11 ## Runtime Architecture
12 Agent Zero's runtime architecture is built around Docker containers:
@@ -42,7 +42,7 @@ This architecture ensures:
42 | --- | --- |
43 | `/docker` | Docker-related files for runtime container |
44 | `/docs` | Documentation files and guides |
45 -| `/instruments` | Custom scripts and tools for runtime environment |
45 +| `/skills` | Skills using the open SKILL.md standard (contextual expertise) |
46 | `/knowledge` | Knowledge base storage |
47 | `/logs` | HTML CLI-style chat logs |
48 | `/memory` | Persistent agent memory storage |
@@ -148,9 +148,9 @@ Users can create custom tools to extend Agent Zero's capabilities. Custom tools
148 4. Follow existing patterns for consistency
149
150 > [!NOTE]
151 -> Tools are always present in system prompt, so you should keep them to minimum.
152 -> To save yourself some tokens, use the [Instruments module](#adding-instruments)
153 -> to call custom scripts or functions.
151 +> Tools are always present in system prompt, so you should keep them to minimum.
152 +> To save yourself some tokens, use the [Skills module](#6-skills)
153 +> to add contextual expertise that is only loaded when relevant.
154
155 ### 3. Memory System
156 The memory system is a critical component of Agent Zero, enabling the agent to learn and adapt from past interactions. It operates on a hybrid model where part of the memory is managed automatically by the framework while users can also manually input and extract information.
@@ -266,20 +266,54 @@ Knowledge refers to the user-provided information and data that agents can lever
266 - Used for answering questions and decision-making
267 - Supports RAG-augmented tasks
268
269 -### 6. Instruments
270 -Instruments provide a way to add custom functionalities to Agent Zero without adding to the token count of the system prompt:
271 -- Stored in long-term memory of Agent Zero
272 -- Unlimited number of instruments available
273 -- Recalled when needed by the agent
274 -- Can modify agent behavior by introducing new procedures
275 -- Function calls or scripts to integrate with other systems
276 -- Scripts are run inside the Docker Container
277 -
278 -#### Adding Instruments
279 -1. Create folder in `instruments/custom` (no spaces in name)
280 -2. Add `.md` description file for the interface
281 -3. Add `.sh` script (or other executable) for implementation
282 -4. The agent will automatically detect and use the instrument
269 +### 6. Skills
270 +Skills provide contextual expertise using the **open SKILL.md standard** (originally developed by Anthropic). Skills are cross-platform and compatible with Claude Code, Cursor, Goose, OpenAI Codex CLI, GitHub Copilot, and more.
271 +
272 +#### Key Features
273 +- **YAML Frontmatter**: Structured metadata (name, description, tags, author)
274 +- **Cross-Platform**: Works with any AI agent that supports the SKILL.md standard
275 +- **Semantic Recall**: Skills are indexed in vector memory and loaded when contextually relevant
276 +- **Token Efficient**: Not in system prompt; loaded dynamically when needed
277 +- **Scripts Support**: Can reference `.sh`, `.py`, `.js`, `.ts` scripts
278 +
279 +#### SKILL.md Format
280 +```yaml
281 +---
282 +name: "my-skill"
283 +description: "What this skill does and when to use it"
284 +version: "1.0.0"
285 +author: "Your Name"
286 +tags: ["category", "purpose"]
287 +---
288 +
289 +# Skill Instructions
290 +
291 +Your detailed instructions here...
292 +
293 +## Examples
294 +- Example usage 1
295 +- Example usage 2
296 +```
297 +
298 +#### Directory Structure
299 +| Directory | Description |
300 +|-----------|-------------|
301 +| `/skills/builtin` | Built-in skills included with Agent Zero |
302 +| `/skills/custom` | Your custom skills (create folders here) |
303 +| `/skills/shared` | Skills shared across agents |
304 +
305 +#### Adding Skills
306 +1. Create folder in `skills/custom` (e.g., `skills/custom/my-skill`)
307 +2. Add `SKILL.md` file with YAML frontmatter (required)
308 +3. Optionally add supporting scripts (`.sh`, `.py`, etc.)
309 +4. Optionally add `docs/` subfolder for additional documentation
310 +5. The agent will automatically discover and index the skill
311 +
312 +#### Using Skills
313 +Skills are automatically recalled from memory when relevant to a task. You can also use the `skills_tool` to:
314 +- List all available skills
315 +- Load a specific skill by name
316 +- Read files from within a skill directory
317
318 ### 7. Extensions
319 Extensions are a powerful feature of Agent Zero, designed to keep the main codebase clean and organized while allowing for greater flexibility and modularity.
docs/extensibility.md
+1 -1
@@ -1,7 +1,7 @@
1 # Extensibility framework in Agent Zero
2
3 > [!NOTE]
4 -> Agent Zero is built with extensibility in mind. It provides a framework for creating custom extensions, agents, instruments, and tools that can be used to enhance the functionality of the framework.
4 +> Agent Zero is built with extensibility in mind. It provides a framework for creating custom extensions, agents, skills, and tools that can be used to enhance the functionality of the framework.
5
6 ## Extensible components
7 - The Python framework controlling Agent Zero is built as simple as possible, relying on independent smaller and modular scripts for individual tools, API endpoints, system extensions and helper scripts.
docs/installation.md
+3 -3
@@ -87,7 +87,7 @@ The following user guide provides instructions for installing and running Agent
87 - `/agents` - Specialized agents with their prompts and tools
88 - `/memory` - Agent's memory and learned information
89 - `/knowledge` - Knowledge base
90 - - `/instruments` - Instruments and functions
90 + - `/skills` - Skills using the open SKILL.md standard
91 - `/prompts` - Prompt files
92 - `.env` - Your API keys
93 - `/tmp/settings.json` - Your Agent Zero settings
@@ -372,12 +372,12 @@ For developers or users who need to run Agent Zero directly on their system,see
372 - To update to the new Docker runtime version, you might want to backup the following files and directories:
373 - `/memory` - Agent's memory
374 - `/knowledge` - Custom knowledge base (if you imported any custom knowledge files)
375 - - `/instruments` - Custom instruments and functions (if you created any custom)
375 + - `/skills` - Custom skills using SKILL.md format (if you created any)
376 - `/tmp/settings.json` - Your Agent Zero settings
377 - `/tmp/chats/` - Your chat history
378 - Once you have saved these files and directories, you can proceed with the Docker runtime [installation instructions above](#windows-macos-and-linux-setup-guide) setup guide.
379 - Reach for the folder where you saved your data and copy it to the new Agent Zero folder set during the installation process.
380 -- Agent Zero will automatically detect your saved data and use it across memory, knowledge, instruments, prompts and settings.
380 +- Agent Zero will automatically detect your saved data and use it across memory, knowledge, skills, prompts and settings.
381
382 > [!IMPORTANT]
383 > If you have issues loading your settings, you can try to delete the `/tmp/settings.json` file and let Agent Zero generate a new one.
docs/usage.md
+1 -1
@@ -259,7 +259,7 @@ By default, Agent Zero backs up your most important data:
259 * **Memory System**: Agent memories and learned information
260 * **Chat History**: All your conversations and interactions
261 * **Configuration Files**: Settings, API keys, and system preferences
262 -* **Custom Instruments**: Any tools you've added or modified
262 +* **Custom Skills**: Any skills you've added or modified (SKILL.md format)
263 * **Uploaded Files**: Documents and files you've worked with
264
265 #### Customizing Backup Content
instruments/default/.DS_Store
Binary files a/instruments/default/.DS_Store and /dev/null differ
instruments/default/yt_download/download_video.py deleted
-12
@@ -1,12 +0,0 @@
1 -import sys
2 -import yt_dlp # type: ignore
3 -
4 -if len(sys.argv) != 2:
5 - print("Usage: python3 download_video.py <url>")
6 - sys.exit(1)
7 -
8 -url = sys.argv[1]
9 -
10 -ydl_opts = {}
11 -with yt_dlp.YoutubeDL(ydl_opts) as ydl:
12 - ydl.download([url])
instruments/default/yt_download/yt_download.md deleted
-11
@@ -1,11 +0,0 @@
1 -# Problem
2 -Download a YouTube video
3 -# Solution
4 -1. If folder is specified, cd to it
5 -2. Run the shell script with your video URL:
6 -
7 -```bash
8 -bash /a0/instruments/default/yt_download/yt_download.sh <url>
9 -```
10 -3. Replace `<url>` with your video URL.
11 -4. The script will handle the installation of yt-dlp and the download process.
instruments/default/yt_download/yt_download.sh deleted
-10
@@ -1,10 +0,0 @@
1 -#!/bin/bash
2 -
3 -# Install yt-dlp and ffmpeg
4 -sudo apt-get update && sudo apt-get install -y yt-dlp ffmpeg
5 -
6 -# Install yt-dlp using pip
7 -pip install --upgrade yt-dlp
8 -
9 -# Call the Python script to download the video
10 -python3 /a0/instruments/default/yt_download/download_video.py "$1"
knowledge/default/main/about/installation.md
+3 -3
@@ -80,7 +80,7 @@ The following user guide provides instructions for installing and running Agent
80 - This directory will contain all your Agent Zero files, like the legacy root folder structure:
81 - `/memory` - Agent's memory and learned information
82 - `/knowledge` - Knowledge base
83 - - `/instruments` - Instruments and functions
83 + - `/skills` - Skills (SKILL.md standard)
84 - `/prompts` - Prompt files
85 - `/work_dir` - Working directory
86 - `.env` - Your API keys
@@ -301,12 +301,12 @@ For developers or users who need to run Agent Zero directly on their system,see
301 - To update to the new Docker runtime version, you might want to backup the following files and directories:
302 - `/memory` - Agent's memory
303 - `/knowledge` - Custom knowledge base (if you imported any custom knowledge files)
304 - - `/instruments` - Custom instruments and functions (if you created any custom)
304 + - `/skills` - Custom skills (if you created any custom SKILL.md files)
305 - `/tmp/settings.json` - Your Agent Zero settings
306 - `/tmp/chats/` - Your chat history
307 - Once you have saved these files and directories, you can proceed with the Docker runtime [installation instructions above](#windows-macos-and-linux-setup-guide) setup guide.
308 - Reach for the folder where you saved your data and copy it to the new Agent Zero folder set during the installation process.
309 -- Agent Zero will automatically detect your saved data and use it across memory, knowledge, instruments, prompts and settings.
309 +- Agent Zero will automatically detect your saved data and use it across memory, knowledge, skills, prompts and settings.
310
311 > [!IMPORTANT]
312 > If you have issues loading your settings, you can try to delete the `/tmp/settings.json` file and let Agent Zero generate a new one.
prompts/agent.system.framework.md new
+16
@@ -0,0 +1,16 @@
1 +# Active Development Framework: {{framework_name}}
2 +
3 +{{framework_description}}
4 +
5 +## Workflow Steps
6 +Follow this structured workflow when working on development tasks:
7 +
8 +{{workflow_steps}}
9 +
10 +## Framework Usage Guidelines
11 +- Use the `skills_tool` to load framework-specific skills when starting each workflow phase
12 +- Skills with the `{{framework_prefix}}-` prefix are designed for this framework
13 +- Guide the user through the appropriate workflow step based on where they are in the development process
14 +- When the user asks to start a new feature or project, begin with step 1 of the workflow
15 +- Provide clear transitions between workflow phases
16 +- Reference the relevant skill for detailed instructions on each phase
prompts/agent.system.instruments.md deleted
-5
@@ -1,5 +0,0 @@
1 -# Instruments
2 -- following are instruments at disposal
3 -- do not overly rely on them they might not be relevant
4 -
5 -{{instruments}}
prompts/agent.system.main.solving.md
+1 -1
@@ -6,7 +6,7 @@ explain each step in thoughts
6 0 outline plan
7 agentic mode active
8
9 -1 check memories solutions instruments prefer instruments
9 +1 check memories solutions skills prefer skills
10
11 2 break task into subtasks if needed
12
prompts/agent.system.main.tips.md
+3 -3
@@ -10,10 +10,10 @@ memory refers memory tools not own knowledge
10 when not in project save files in /root
11 don't use spaces in file names
12
13 -## Instruments
13 +## Skills
14
15 -instruments are programs to solve tasks
16 -instrument descriptions in prompt executed with code_execution_tool
15 +skills are contextual expertise to solve tasks (SKILL.md standard)
16 +skill descriptions in prompt executed with code_execution_tool or skills_tool
17
18 ## Best practices
19
prompts/agent.system.skills.md new
+5
@@ -0,0 +1,5 @@
1 +# Relevant Skills (SKILL.md)
2 +- The following Skills may be useful for the current task.
3 +- Use `skills_tool` to list/search/load skills and progressively read supporting files/scripts.
4 +
5 +{{skills}}
prompts/agent.system.tool.skills.md new
+419
@@ -0,0 +1,419 @@
1 +### skills_tool
2 +
3 +manage and use agent skills for specialized capabilities
4 +skills are composable bundles of instructions context and executable code
5 +use progressive disclosure: metadata → full content → referenced files
6 +use "method" arg to specify operation: "list" "load" "read_file" "execute_script" "search"
7 +
8 +## Overview
9 +
10 +Skills system provides three-level progressive disclosure:
11 +- Level 1: Metadata (name + description) loaded in system prompt at startup
12 +- Level 2: Full SKILL.md content loaded when relevant to task
13 +- Level 3+: Referenced files and scripts loaded on-demand
14 +
15 +When to use skills:
16 +- Task matches skill description from available skills list
17 +- Need specialized procedures or domain knowledge
18 +- Task requires bundled scripts or automation
19 +- Need step-by-step guidance for complex operations
20 +
21 +Progressive workflow:
22 +1. Check available skills metadata already in your context
23 +2. Use "search" if looking for specific capability
24 +3. Use "load" to get full skill instructions and context
25 +4. Use "read_file" to load additional reference documents
26 +5. Use "execute_script" to run deterministic operations
27 +
28 +## Operations
29 +
30 +### 1. list available skills
31 +
32 +Lists all available skills with metadata
33 +Shows name, version, description, tags, and author
34 +Use when: exploring available capabilities or confirming skill exists
35 +
36 +~~~json
37 +{
38 + "thoughts": [
39 + "Need to see what skills are available",
40 + "User asked about available capabilities"
41 + ],
42 + "headline": "Listing all available skills",
43 + "tool_name": "skills_tool",
44 + "tool_args": {
45 + "method": "list"
46 + }
47 +}
48 +~~~
49 +
50 +Response format:
51 +- Skill name and version
52 +- Brief description
53 +- Tags for categorization
54 +- Author attribution
55 +
56 +### 2. load full skill content
57 +
58 +Loads complete SKILL.md content with instructions and procedures
59 +Returns metadata, full content, and list of referenced files
60 +Use when: identified relevant skill and need detailed instructions
61 +
62 +~~~json
63 +{
64 + "thoughts": [
65 + "User needs PDF form extraction",
66 + "pdf_editing skill will provide procedures",
67 + "Loading full skill content"
68 + ],
69 + "headline": "Loading PDF editing skill",
70 + "tool_name": "skills_tool",
71 + "tool_args": {
72 + "method": "load",
73 + "skill_name": "pdf_editing"
74 + }
75 +}
76 +~~~
77 +
78 +Required args:
79 +- skill_name: exact name from metadata or list
80 +
81 +Response includes:
82 +- Skill metadata (name, version, description, tags)
83 +- Full markdown content with instructions
84 +- List of referenced files available to load
85 +- Code examples and procedures
86 +
87 +### 3. read skill reference file
88 +
89 +Reads additional reference files from skill directory
90 +Files referenced in SKILL.md can be loaded progressively
91 +Use when: need detailed documentation or examples from skill references
92 +
93 +~~~json
94 +{
95 + "thoughts": [
96 + "Skill mentioned forms.md for form filling details",
97 + "Need specific form field handling instructions",
98 + "Loading reference file"
99 + ],
100 + "headline": "Reading PDF forms reference documentation",
101 + "tool_name": "skills_tool",
102 + "tool_args": {
103 + "method": "read_file",
104 + "skill_name": "pdf_editing",
105 + "file_path": "forms.md"
106 + }
107 +}
108 +~~~
109 +
110 +Required args:
111 +- skill_name: name of skill containing file
112 +- file_path: relative path within skill directory (e.g. "reference.md" or "examples/example1.md")
113 +
114 +Security:
115 +- Path validation prevents directory traversal
116 +- Only files within skill directory accessible
117 +- Supports markdown, text, code files
118 +
119 +### 4. execute skill script
120 +
121 +Executes bundled scripts from skill with arguments
122 +Scripts receive arguments via standard CLI conventions (sys.argv, process.argv)
123 +Use when: skill provides script for deterministic operation or automation
124 +
125 +~~~json
126 +{
127 + "thoughts": [
128 + "Need to convert PDF to images",
129 + "Skill provides convert_pdf_to_images.py script",
130 + "Script expects positional args: input_pdf output_dir"
131 + ],
132 + "headline": "Converting PDF to images",
133 + "tool_name": "skills_tool",
134 + "tool_args": {
135 + "method": "execute_script",
136 + "skill_name": "pdf_editing",
137 + "script_path": "scripts/convert_pdf_to_images.py",
138 + "script_args": {
139 + "input_pdf": "/path/to/document.pdf",
140 + "output_dir": "/tmp/images"
141 + }
142 + }
143 +}
144 +~~~
145 +
146 +Required args:
147 +- skill_name: name of skill containing script
148 +- script_path: relative path to script file
149 +- script_args: dictionary of arguments passed to script
150 +
151 +Optional args:
152 +- arg_style: how to pass arguments to script (default: "positional")
153 + - "positional": values as positional args → sys.argv = ['script.py', 'value1', 'value2']
154 + - "named": as --key value pairs → sys.argv = ['script.py', '--key1', 'value1', '--key2', 'value2']
155 + - "env": only environment variables, no CLI args
156 +
157 +How scripts receive arguments:
158 +- .py (Python): sys.argv[1], sys.argv[2], etc. (standard argparse/CLI compatible)
159 +- .js (Node.js): process.argv[2], process.argv[3], etc. (standard CLI compatible)
160 +- .sh (Shell): $1, $2, etc. as positional parameters
161 +
162 +Environment variables (always available as fallback):
163 +- SKILL_ARG_KEY1=value1, SKILL_ARG_KEY2=value2, etc.
164 +- Scripts can use os.environ.get('SKILL_ARG_INPUT_PDF') if needed
165 +
166 +Script execution:
167 +- Runs in Docker container sandbox
168 +- Has access to installed packages
169 +- Returns stdout/stderr output
170 +- Secure and isolated execution
171 +
172 +Example with argparse script (use arg_style="named"):
173 +~~~json
174 +{
175 + "thoughts": [
176 + "Script uses argparse with --input and --output flags",
177 + "Need to use named arg_style"
178 + ],
179 + "headline": "Running argparse-based script",
180 + "tool_name": "skills_tool",
181 + "tool_args": {
182 + "method": "execute_script",
183 + "skill_name": "data_processor",
184 + "script_path": "scripts/process.py",
185 + "script_args": {
186 + "input": "/path/to/data.csv",
187 + "output": "/tmp/result.json"
188 + },
189 + "arg_style": "named"
190 + }
191 +}
192 +~~~
193 +
194 +### 5. search skills by query
195 +
196 +Searches skills by text matching in name, description, and tags
197 +Returns ranked results by relevance score
198 +Use when: looking for skills without knowing exact name
199 +
200 +~~~json
201 +{
202 + "thoughts": [
203 + "User needs web scraping capability",
204 + "Not sure of exact skill name",
205 + "Searching for web-related skills"
206 + ],
207 + "headline": "Searching for web scraping skills",
208 + "tool_name": "skills_tool",
209 + "tool_args": {
210 + "method": "search",
211 + "query": "web scraping html parsing"
212 + }
213 +}
214 +~~~
215 +
216 +Required args:
217 +- query: search text (searches name, description, tags)
218 +
219 +Scoring:
220 +- Name match: +3 points
221 +- Description match: +2 points
222 +- Tag match: +1 point per tag
223 +- Results sorted by descending score
224 +
225 +## Best Practices
226 +
227 +### When to use skills vs other tools
228 +
229 +Use skills when:
230 +- Task requires specialized domain knowledge
231 +- Need structured procedures or step-by-step guidance
232 +- Deterministic scripts available for automation
233 +- Complex multi-step operations with best practices
234 +
235 +Use other tools when:
236 +- Simple file operations (use code_execution_tool)
237 +- Web search (use search_engine)
238 +- General computation (use code_execution_tool)
239 +- Memory operations (use memory tools)
240 +
241 +### Progressive disclosure workflow
242 +
243 +1. Start with metadata (already in context)
244 + - Check available skills list in system prompt
245 + - Match task to skill description
246 +
247 +2. Load full content when relevant
248 + - Use "load" to get complete instructions
249 + - Review procedures and examples
250 +
251 +3. Load references as needed
252 + - Use "read_file" for detailed documentation
253 + - Load only files relevant to current subtask
254 +
255 +4. Execute scripts for automation
256 + - Use "execute_script" for deterministic operations
257 + - Provide appropriate arguments from context
258 +
259 +### Common patterns
260 +
261 +Pattern: Using a skill for first time
262 +1. Identify skill from metadata
263 +2. Load full skill content
264 +3. Follow instructions in content
265 +4. Load reference files if mentioned
266 +5. Execute scripts if provided
267 +
268 +Pattern: Quick script execution
269 +1. Know skill name from previous use
270 +2. Execute script directly with args
271 +3. Process output
272 +
273 +Pattern: Exploring capabilities
274 +1. Search with query terms
275 +2. Review matches
276 +3. Load most relevant skill
277 +
278 +## Error Handling
279 +
280 +Common errors:
281 +- "Skill not found": Check spelling, use list or search to find correct name
282 +- "File not found": Verify file_path matches referenced files from load output
283 +- "Script failed": Check script_args match expected parameters, review skill docs
284 +- "Unsupported script type": Only .py, .js, .sh supported
285 +
286 +When skill loading fails:
287 +- Verify skill exists using list method
288 +- Check for typos in skill_name
289 +- Ensure skill system is enabled in settings
290 +
291 +When script execution fails:
292 +- Review skill documentation for required arguments
293 +- Check script_args dictionary format
294 +- Verify required packages installed in container
295 +- Check script output for specific error messages
296 +
297 +## Examples
298 +
299 +Example 1: Simple script with positional args (default)
300 +Script expects: python script.py /path/to/file.pdf
301 +~~~json
302 +{
303 + "thoughts": [
304 + "User has PDF to convert to images",
305 + "Script uses sys.argv[1] for input, sys.argv[2] for output",
306 + "Using default positional arg_style"
307 + ],
308 + "headline": "Converting PDF to images",
309 + "tool_name": "skills_tool",
310 + "tool_args": {
311 + "method": "execute_script",
312 + "skill_name": "pdf_editing",
313 + "script_path": "scripts/convert_pdf_to_images.py",
314 + "script_args": {
315 + "input_pdf": "/workspace/document.pdf",
316 + "output_dir": "/tmp/images"
317 + }
318 + }
319 +}
320 +~~~
321 +Result: sys.argv = ['script.py', '/workspace/document.pdf', '/tmp/images']
322 +
323 +Example 2: Argparse script with named args
324 +Script expects: python script.py --url https://... --selector .price
325 +~~~json
326 +{
327 + "thoughts": [
328 + "Need to scrape product prices from website",
329 + "Script uses argparse with --url and --selector flags",
330 + "Using arg_style='named' for argparse compatibility"
331 + ],
332 + "headline": "Scraping product prices from webpage",
333 + "tool_name": "skills_tool",
334 + "tool_args": {
335 + "method": "execute_script",
336 + "skill_name": "web_scraping",
337 + "script_path": "scripts/fetch_page.py",
338 + "script_args": {
339 + "url": "https://example.com/products",
340 + "selector": ".price"
341 + },
342 + "arg_style": "named"
343 + }
344 +}
345 +~~~
346 +Result: sys.argv = ['script.py', '--url', 'https://...', '--selector', '.price']
347 +
348 +Example 3: Environment-only script
349 +Script reads from os.environ only
350 +~~~json
351 +{
352 + "thoughts": [
353 + "Script reads configuration from environment variables",
354 + "Using arg_style='env' to only set env vars"
355 + ],
356 + "headline": "Running config-based processor",
357 + "tool_name": "skills_tool",
358 + "tool_args": {
359 + "method": "execute_script",
360 + "skill_name": "data_processor",
361 + "script_path": "scripts/process.py",
362 + "script_args": {
363 + "input_file": "/data/input.csv",
364 + "mode": "production"
365 + },
366 + "arg_style": "env"
367 + }
368 +}
369 +~~~
370 +Result: SKILL_ARG_INPUT_FILE=/data/input.csv, SKILL_ARG_MODE=production
371 +
372 +Example 4: Data analysis workflow
373 +~~~json
374 +{
375 + "thoughts": [
376 + "User needs CSV analysis",
377 + "data_analysis skill has analysis procedures",
378 + "Loading skill for detailed instructions"
379 + ],
380 + "headline": "Loading data analysis skill",
381 + "tool_name": "skills_tool",
382 + "tool_args": {
383 + "method": "load",
384 + "skill_name": "data_analysis"
385 + }
386 +}
387 +~~~
388 +
389 +Then follow up with script (positional args):
390 +~~~json
391 +{
392 + "thoughts": [
393 + "Skill loaded, now analyzing CSV",
394 + "Script takes csv_path as first arg, group_by as second"
395 + ],
396 + "headline": "Analyzing sales data grouped by category",
397 + "tool_name": "skills_tool",
398 + "tool_args": {
399 + "method": "execute_script",
400 + "skill_name": "data_analysis",
401 + "script_path": "scripts/analyze_csv.py",
402 + "script_args": {
403 + "csv_path": "/workspace/sales_data.csv",
404 + "group_by": "category"
405 + }
406 + }
407 +}
408 +~~~
409 +
410 +## Notes
411 +
412 +- Skills metadata already loaded in your system prompt
413 +- Skills cache after first load for efficiency
414 +- Referenced files listed in load response
415 +- Scripts receive arguments via sys.argv (positional by default) + SKILL_ARG_* env vars
416 +- Use arg_style parameter to control argument passing: "positional", "named", or "env"
417 +- All operations return formatted text responses
418 +- Skills follow the open SKILL.md standard (cross-platform compatible)
419 +- Use skills for structured procedures and contextual expertise
python/api/frameworks.py new
+39
@@ -0,0 +1,39 @@
1 +from dataclasses import asdict
2 +from python.helpers.api import ApiHandler, Input, Output, Request
3 +from python.helpers import frameworks
4 +
5 +
6 +class Frameworks(ApiHandler):
7 + """API handler for development framework operations."""
8 +
9 + async def process(self, input: Input, request: Request) -> Output:
10 + action = input.get("action", "list")
11 +
12 + try:
13 + if action == "list":
14 + data = self.list_frameworks()
15 + elif action == "get":
16 + data = self.get_framework(input.get("id", ""))
17 + else:
18 + raise Exception(f"Invalid action: {action}")
19 +
20 + return {
21 + "ok": True,
22 + "data": data,
23 + }
24 + except Exception as e:
25 + return {
26 + "ok": False,
27 + "error": str(e),
28 + }
29 +
30 + def list_frameworks(self) -> list[dict]:
31 + """List all available frameworks."""
32 + return [asdict(fw) for fw in frameworks.list_frameworks()]
33 +
34 + def get_framework(self, framework_id: str) -> dict | None:
35 + """Get a specific framework by ID."""
36 + fw = frameworks.get_framework(framework_id)
37 + if fw is None:
38 + return None
39 + return asdict(fw)
python/api/skills_import.py new
+88
@@ -0,0 +1,88 @@
1 +from __future__ import annotations
2 +
3 +import os
4 +import time
5 +import uuid
6 +from pathlib import Path
7 +
8 +from python.helpers.api import ApiHandler, Request, Response
9 +from python.helpers import files
10 +from python.helpers.skills_import import import_skills
11 +from werkzeug.datastructures import FileStorage
12 +from werkzeug.utils import secure_filename
13 +
14 +
15 +class SkillsImport(ApiHandler):
16 + """
17 + Import an external skills pack (.zip) into skills/shared/<namespace>/...
18 + Performs the actual import (not dry-run).
19 + """
20 +
21 + async def process(self, input: dict, request: Request) -> dict | Response:
22 + if "skills_file" not in request.files:
23 + return {"success": False, "error": "No skills file provided"}
24 +
25 + skills_file: FileStorage = request.files["skills_file"]
26 + if not skills_file.filename:
27 + return {"success": False, "error": "No file selected"}
28 +
29 + ctxid = request.form.get("ctxid", "")
30 + if not ctxid:
31 + return {"success": False, "error": "No context id provided"}
32 + _context = self.use_context(ctxid)
33 +
34 + dest = (request.form.get("dest", "shared") or "shared").strip().lower()
35 + if dest not in ("shared", "custom", "project"):
36 + dest = "shared"
37 +
38 + conflict = (request.form.get("conflict", "skip") or "skip").strip().lower()
39 + if conflict not in ("skip", "overwrite", "rename"):
40 + conflict = "skip"
41 +
42 + namespace = (request.form.get("namespace", "") or "").strip() or None
43 + project_name = (request.form.get("project_name", "") or "").strip() or None
44 +
45 + # If dest is "project", project_name is required
46 + if dest == "project" and not project_name:
47 + return {"success": False, "error": "project_name is required when dest is 'project'"}
48 +
49 + # Save upload to a temp file so we can pass a filesystem path to the importer
50 + tmp_dir = Path(files.get_abs_path("tmp", "uploads"))
51 + tmp_dir.mkdir(parents=True, exist_ok=True)
52 + base = secure_filename(skills_file.filename) # type: ignore[arg-type]
53 + if not base.lower().endswith(".zip"):
54 + base = f"{base}.zip"
55 + unique = uuid.uuid4().hex[:8]
56 + stamp = time.strftime("%Y%m%d_%H%M%S")
57 + tmp_path = tmp_dir / f"skills_import_{stamp}_{unique}_{base}"
58 + skills_file.save(str(tmp_path))
59 +
60 + try:
61 + result = import_skills(
62 + str(tmp_path),
63 + dest_subdir=dest, # type: ignore[arg-type]
64 + namespace=namespace,
65 + conflict=conflict, # type: ignore[arg-type]
66 + dry_run=False, # Actual import, not preview
67 + project_name=project_name,
68 + )
69 +
70 + imported = [files.deabsolute_path(str(p)) for p in result.imported]
71 + skipped = [files.deabsolute_path(str(p)) for p in result.skipped]
72 + dest_root = files.deabsolute_path(str(result.destination_root / result.namespace))
73 +
74 + return {
75 + "success": True,
76 + "namespace": result.namespace,
77 + "destination": dest_root,
78 + "imported": imported,
79 + "skipped": skipped,
80 + "imported_count": len(imported),
81 + "skipped_count": len(skipped),
82 + "conflict_policy": conflict,
83 + }
84 + finally:
85 + try:
86 + tmp_path.unlink(missing_ok=True) # type: ignore[arg-type]
87 + except Exception:
88 + pass
python/api/skills_import_preview.py new
+89
@@ -0,0 +1,89 @@
1 +from __future__ import annotations
2 +
3 +import os
4 +import time
5 +import uuid
6 +from pathlib import Path
7 +
8 +from python.helpers.api import ApiHandler, Request, Response
9 +from python.helpers import files
10 +from python.helpers.skills_import import import_skills
11 +from werkzeug.datastructures import FileStorage
12 +from werkzeug.utils import secure_filename
13 +
14 +
15 +class SkillsImportPreview(ApiHandler):
16 + """
17 + Preview importing an external skills pack (.zip) into skills/shared/<namespace>/...
18 + Uses dry-run (no copying).
19 + """
20 +
21 + async def process(self, input: dict, request: Request) -> dict | Response:
22 + if "skills_file" not in request.files:
23 + return {"success": False, "error": "No skills file provided"}
24 +
25 + skills_file: FileStorage = request.files["skills_file"]
26 + if not skills_file.filename:
27 + return {"success": False, "error": "No file selected"}
28 +
29 + ctxid = request.form.get("ctxid", "")
30 + if not ctxid:
31 + return {"success": False, "error": "No context id provided"}
32 + _context = self.use_context(ctxid)
33 +
34 + dest = (request.form.get("dest", "shared") or "shared").strip().lower()
35 + if dest not in ("shared", "custom", "project"):
36 + dest = "shared"
37 +
38 + conflict = (request.form.get("conflict", "skip") or "skip").strip().lower()
39 + if conflict not in ("skip", "overwrite", "rename"):
40 + conflict = "skip"
41 +
42 + namespace = (request.form.get("namespace", "") or "").strip() or None
43 + project_name = (request.form.get("project_name", "") or "").strip() or None
44 +
45 + # If dest is "project", project_name is required
46 + if dest == "project" and not project_name:
47 + return {"success": False, "error": "project_name is required when dest is 'project'"}
48 +
49 + # Save upload to a temp file so we can pass a filesystem path to the importer
50 + tmp_dir = Path(files.get_abs_path("tmp", "uploads"))
51 + tmp_dir.mkdir(parents=True, exist_ok=True)
52 + base = secure_filename(skills_file.filename) # type: ignore[arg-type]
53 + if not base.lower().endswith(".zip"):
54 + base = f"{base}.zip"
55 + unique = uuid.uuid4().hex[:8]
56 + stamp = time.strftime("%Y%m%d_%H%M%S")
57 + tmp_path = tmp_dir / f"skills_import_preview_{stamp}_{unique}_{base}"
58 + skills_file.save(str(tmp_path))
59 +
60 + try:
61 + result = import_skills(
62 + str(tmp_path),
63 + dest_subdir=dest, # type: ignore[arg-type]
64 + namespace=namespace,
65 + conflict=conflict, # type: ignore[arg-type]
66 + dry_run=True,
67 + project_name=project_name,
68 + )
69 +
70 + imported = [files.deabsolute_path(str(p)) for p in result.imported]
71 + skipped = [files.deabsolute_path(str(p)) for p in result.skipped]
72 + dest_root = files.deabsolute_path(str(result.destination_root / result.namespace))
73 +
74 + return {
75 + "success": True,
76 + "namespace": result.namespace,
77 + "destination": dest_root,
78 + "imported": imported,
79 + "skipped": skipped,
80 + "imported_count": len(imported),
81 + "skipped_count": len(skipped),
82 + "conflict_policy": conflict,
83 + }
84 + finally:
85 + try:
86 + tmp_path.unlink(missing_ok=True) # type: ignore[arg-type]
87 + except Exception:
88 + pass
89 +
python/extensions/message_loop_prompts_after/_55_recall_skills.py new
+115
@@ -0,0 +1,115 @@
1 +import os
2 +from pathlib import Path
3 +
4 +from python.helpers.extension import Extension
5 +from agent import LoopData
6 +from python.helpers.memory import Memory
7 +from python.helpers import files
8 +from python.helpers import skills as skills_helper
9 +from python.helpers import frameworks
10 +
11 +
12 +class RecallSkills(Extension):
13 + """
14 + Surface relevant SKILL.md-based Skills into the prompt (token-efficient).
15 +
16 + The Memory subsystem already indexes `skills/**/SKILL.md` into area "skills".
17 + This extension does a lightweight similarity lookup and injects a small
18 + "relevant skills" list into extras for the current user message.
19 + """
20 +
21 + async def execute(self, loop_data: LoopData = LoopData(), **kwargs):
22 + # Only on the first iteration of the message loop (new user instruction)
23 + if loop_data.iteration != 0:
24 + return
25 +
26 + # Determine query from current user message
27 + user_instruction = (
28 + loop_data.user_message.output_text() if loop_data.user_message else ""
29 + ).strip()
30 + if not user_instruction or len(user_instruction) < 8:
31 + return
32 +
33 + try:
34 + db = await Memory.get(self.agent)
35 + docs = await db.search_similarity_threshold(
36 + query=user_instruction,
37 + limit=12,
38 + threshold=0.55,
39 + filter=f"area == '{Memory.Area.SKILLS.value}'",
40 + )
41 + except Exception:
42 + docs = []
43 +
44 + # Fallback: simple keyword search over discovered skills if vector recall yields nothing
45 + recalled = []
46 + if docs:
47 + seen = set()
48 + for doc in docs:
49 + src = (doc.metadata or {}).get("source_path") or ""
50 + if not src:
51 + continue
52 + if src in seen:
53 + continue
54 + seen.add(src)
55 + recalled.append(src)
56 + if len(recalled) >= 6:
57 + break
58 +
59 + if not recalled:
60 + # cheap lexical fallback - include framework skills if a framework is active
61 + framework = frameworks.get_active_framework(self.agent.context)
62 + framework_id = framework.id if framework else None
63 + matches = skills_helper.search_skills(user_instruction, limit=6, framework_id=framework_id)
64 + for s in matches:
65 + recalled.append(str(s.skill_md_path))
66 +
67 + if not recalled:
68 + return
69 +
70 + # Build compact metadata list
71 + base_skills_dir = Path(files.get_abs_path("skills")).resolve()
72 + lines = []
73 + for src_path in recalled[:6]:
74 + try:
75 + p = Path(src_path)
76 + # Some docs may store /a0/... paths; map to dev path when needed
77 + abs_path = Path(files.fix_dev_path(str(p)))
78 + text = abs_path.read_text(encoding="utf-8", errors="replace")
79 + fm, body = skills_helper.split_frontmatter(text)
80 +
81 + # Infer source if possible (custom/builtin/shared/framework), else "unknown"
82 + source = "unknown"
83 + try:
84 + rel = abs_path.resolve().relative_to(base_skills_dir)
85 + if rel.parts and rel.parts[0] in ("custom", "builtin", "shared", "frameworks"):
86 + source = rel.parts[0]
87 + # Normalize "frameworks" to "framework" for display
88 + if source == "frameworks":
89 + source = "framework"
90 + except Exception:
91 + pass
92 +
93 + name = str(fm.get("name") or abs_path.parent.name).strip()
94 + desc = str(fm.get("description") or "").strip()
95 + if not desc:
96 + # fallback to first non-empty line of body
97 + for line in (body or "").splitlines():
98 + if line.strip():
99 + desc = line.strip()
100 + break
101 + if len(desc) > 220:
102 + desc = desc[:220].rstrip() + "…"
103 +
104 + lines.append(f"- {name} [{source}]: {desc}")
105 + except Exception:
106 + continue
107 +
108 + if not lines:
109 + return
110 +
111 + skills_block = "\n".join(lines)
112 + loop_data.extras_temporary["skills"] = self.agent.parse_prompt(
113 + "agent.system.skills.md", skills=skills_block
114 + )
115 +
python/extensions/system_prompt/_10_system_prompt.py
+29 -1
@@ -3,7 +3,7 @@ from python.helpers.extension import Extension
3 from python.helpers.mcp_handler import MCPConfig
4 from agent import Agent, LoopData
5 from python.helpers.settings import get_settings
6 -from python.helpers import projects
6 +from python.helpers import projects, frameworks
7
8
9 class SystemPrompt(Extension):
@@ -20,6 +20,7 @@ class SystemPrompt(Extension):
20 mcp_tools = get_mcp_tools_prompt(self.agent)
21 secrets_prompt = get_secrets_prompt(self.agent)
22 project_prompt = get_project_prompt(self.agent)
23 + framework_prompt = get_framework_prompt(self.agent)
24
25 system_prompt.append(main)
26 system_prompt.append(tools)
@@ -29,6 +30,8 @@ class SystemPrompt(Extension):
30 system_prompt.append(secrets_prompt)
31 if project_prompt:
32 system_prompt.append(project_prompt)
33 + if framework_prompt:
34 + system_prompt.append(framework_prompt)
35
36
37 def get_main_prompt(agent: Agent):
@@ -80,3 +83,28 @@ def get_project_prompt(agent: Agent):
83 else:
84 result += "\n\n" + agent.read_prompt("agent.system.projects.inactive.md")
85 return result
86 +
87 +
88 +def get_framework_prompt(agent: Agent):
89 + """
90 + Get the active development framework prompt if one is selected.
91 +
92 + Returns empty string if no framework is active (framework_id == "none").
93 + """
94 + framework = frameworks.get_active_framework(agent.context)
95 + if not framework:
96 + return ""
97 +
98 + # Build workflow steps description
99 + workflow_steps = "\n".join([
100 + f"{w.sequence}. **{w.name}** (`{w.skill_name}`): {w.description}"
101 + for w in framework.workflows
102 + ])
103 +
104 + return agent.read_prompt(
105 + "agent.system.framework.md",
106 + framework_name=framework.name,
107 + framework_description=framework.description,
108 + framework_prefix=framework.skill_prefix,
109 + workflow_steps=workflow_steps,
110 + )
python/helpers/backup.py
+3 -3
@@ -64,9 +64,9 @@ class BackupService:
64 {agent_root}/knowledge/**
65 !{agent_root}/knowledge/default/**
66
67 -# Agent Zero Instruments (excluding defaults)
68 -{agent_root}/instruments/**
69 -!{agent_root}/instruments/default/**
67 +# Agent Zero Skills (excluding builtins)
68 +{agent_root}/skills/**
69 +!{agent_root}/skills/builtin/**
70
71 # Memory (excluding embeddings cache)
72 {agent_root}/memory/**
python/helpers/frameworks.py new
+623
@@ -0,0 +1,623 @@
1 +"""
2 +Development Framework Registry for Agent Zero.
3 +
4 +This module defines the available development frameworks that can be used
5 +to guide agent workflows. Each framework provides structured methodologies
6 +for software development tasks.
7 +
8 +Frameworks are selected globally in settings or overridden per-project.
9 +When a framework is active, its skills are prioritized in skill discovery
10 +and framework context is injected into the system prompt.
11 +"""
12 +
13 +from __future__ import annotations
14 +
15 +from dataclasses import dataclass, field
16 +from typing import TYPE_CHECKING, List, Literal, Optional
17 +
18 +if TYPE_CHECKING:
19 + from agent import AgentContext
20 +
21 +# Supported framework identifiers
22 +FrameworkId = Literal[
23 + "none",
24 + "gsd",
25 + "superpowers",
26 + "bmad",
27 + "bmad-builder",
28 + "bmad-cis",
29 + "bmad-gds",
30 + "speckit",
31 + "prp",
32 + "agentos",
33 + "amplihack",
34 + "agent-zero-dev",
35 +]
36 +
37 +ALL_FRAMEWORK_IDS: List[str] = [
38 + "none",
39 + "gsd",
40 + "superpowers",
41 + "bmad",
42 + "bmad-builder",
43 + "bmad-cis",
44 + "bmad-gds",
45 + "speckit",
46 + "prp",
47 + "agentos",
48 + "amplihack",
49 + "agent-zero-dev",
50 +]
51 +
52 +
53 +@dataclass(slots=True)
54 +class FrameworkWorkflow:
55 + """A single workflow step within a framework."""
56 +
57 + name: str # e.g., "plan-phase"
58 + skill_name: str # Maps to SKILL.md name, e.g., "gsd-plan-phase"
59 + description: str
60 + sequence: int # Order in workflow (1-based)
61 +
62 +
63 +@dataclass(slots=True)
64 +class Framework:
65 + """A development framework definition."""
66 +
67 + id: FrameworkId
68 + name: str # Display name
69 + description: str
70 + skill_prefix: str # Namespace for skills, e.g., "gsd", "bmad"
71 + workflows: List[FrameworkWorkflow] = field(default_factory=list)
72 +
73 +
74 +# ─────────────────────────────────────────────────────────────────────────────
75 +# Framework Registry
76 +# ─────────────────────────────────────────────────────────────────────────────
77 +
78 +FRAMEWORK_REGISTRY: dict[str, Framework] = {
79 + "none": Framework(
80 + id="none",
81 + name="None",
82 + description="No development framework. Agent operates with standard skills only.",
83 + skill_prefix="",
84 + workflows=[],
85 + ),
86 + "gsd": Framework(
87 + id="gsd",
88 + name="GSD (Get Stuff Done)",
89 + description="A structured methodology emphasizing planning before implementation. Features clear phases: project setup, discussion, planning, execution, verification, and milestone completion.",
90 + skill_prefix="gsd",
91 + workflows=[
92 + FrameworkWorkflow(
93 + name="New Project",
94 + skill_name="gsd-new-project",
95 + description="Initialize project structure, requirements, and roadmap",
96 + sequence=1,
97 + ),
98 + FrameworkWorkflow(
99 + name="Discuss Phase",
100 + skill_name="gsd-discuss-phase",
101 + description="Capture implementation decisions and preferences before planning",
102 + sequence=2,
103 + ),
104 + FrameworkWorkflow(
105 + name="Plan Phase",
106 + skill_name="gsd-plan-phase",
107 + description="Research, create atomic task plans, and verify against requirements",
108 + sequence=3,
109 + ),
110 + FrameworkWorkflow(
111 + name="Execute Phase",
112 + skill_name="gsd-execute-phase",
113 + description="Run plans in parallel waves with fresh context per task",
114 + sequence=4,
115 + ),
116 + FrameworkWorkflow(
117 + name="Verify Work",
118 + skill_name="gsd-verify-work",
119 + description="Manual user acceptance testing with automatic fix generation",
120 + sequence=5,
121 + ),
122 + FrameworkWorkflow(
123 + name="Complete Milestone",
124 + skill_name="gsd-complete-milestone",
125 + description="Archive milestone, tag release, prepare for next iteration",
126 + sequence=6,
127 + ),
128 + ],
129 + ),
130 + "superpowers": Framework(
131 + id="superpowers",
132 + name="Superpowers",
133 + description="A comprehensive development workflow framework for Claude Code. Emphasizes TDD, brainstorming, planning, subagent execution, code review, and proper branch management.",
134 + skill_prefix="sp",
135 + workflows=[
136 + FrameworkWorkflow(
137 + name="Brainstorming",
138 + skill_name="sp-brainstorming",
139 + description="Socratic design refinement before writing code",
140 + sequence=1,
141 + ),
142 + FrameworkWorkflow(
143 + name="Git Worktrees",
144 + skill_name="sp-git-worktrees",
145 + description="Create isolated workspace on new branch for development",
146 + sequence=2,
147 + ),
148 + FrameworkWorkflow(
149 + name="Writing Plans",
150 + skill_name="sp-writing-plans",
151 + description="Break work into bite-sized tasks (2-5 min each) with verification",
152 + sequence=3,
153 + ),
154 + FrameworkWorkflow(
155 + name="Test-Driven Development",
156 + skill_name="sp-test-driven-development",
157 + description="RED-GREEN-REFACTOR: test first, minimal code, commit",
158 + sequence=4,
159 + ),
160 + FrameworkWorkflow(
161 + name="Executing Plans",
162 + skill_name="sp-executing-plans",
163 + description="Dispatch subagents per task with two-stage review",
164 + sequence=5,
165 + ),
166 + FrameworkWorkflow(
167 + name="Code Review",
168 + skill_name="sp-code-review",
169 + description="Review against plan, report issues by severity",
170 + sequence=6,
171 + ),
172 + FrameworkWorkflow(
173 + name="Finishing Branch",
174 + skill_name="sp-finishing-branch",
175 + description="Verify tests, merge/PR options, cleanup worktree",
176 + sequence=7,
177 + ),
178 + ],
179 + ),
180 + "bmad": Framework(
181 + id="bmad",
182 + name="BMAD (Business-Minded Agile Development)",
183 + description="A business-focused agile methodology with 21 specialized agents. Features two paths: Quick (spec→dev→review) for small tasks, Full (brief→PRD→arch→epics→sprint→stories) for complex projects.",
184 + skill_prefix="bmad",
185 + workflows=[
186 + FrameworkWorkflow(
187 + name="Quick Spec",
188 + skill_name="bmad-quick-spec",
189 + description="(Quick Path) Analyze codebase and produce tech-spec with stories",
190 + sequence=1,
191 + ),
192 + FrameworkWorkflow(
193 + name="Product Brief",
194 + skill_name="bmad-product-brief",
195 + description="(Full Path) Define problem, users, and MVP scope",
196 + sequence=2,
197 + ),
198 + FrameworkWorkflow(
199 + name="Create PRD",
200 + skill_name="bmad-create-prd",
201 + description="Full requirements with personas, metrics, and risks",
202 + sequence=3,
203 + ),
204 + FrameworkWorkflow(
205 + name="Architecture",
206 + skill_name="bmad-create-architecture",
207 + description="Technical decisions and system design",
208 + sequence=4,
209 + ),
210 + FrameworkWorkflow(
211 + name="Create Epics",
212 + skill_name="bmad-create-epics",
213 + description="Break work into prioritized epics and stories",
214 + sequence=5,
215 + ),
216 + FrameworkWorkflow(
217 + name="Sprint Planning",
218 + skill_name="bmad-sprint-planning",
219 + description="Initialize sprint tracking and story selection",
220 + sequence=6,
221 + ),
222 + FrameworkWorkflow(
223 + name="Developer Story",
224 + skill_name="bmad-dev-story",
225 + description="Implement individual stories with guidance",
226 + sequence=7,
227 + ),
228 + FrameworkWorkflow(
229 + name="Code Review",
230 + skill_name="bmad-code-review",
231 + description="Validate quality and completeness",
232 + sequence=8,
233 + ),
234 + ],
235 + ),
236 + "bmad-builder": Framework(
237 + id="bmad-builder",
238 + name="BMad Builder",
239 + description="Meta-module for creating custom BMad agents, workflows, and domain-specific modules. Build specialized AI agents with custom expertise, structured workflows, and shareable module packages.",
240 + skill_prefix="bmb",
241 + workflows=[
242 + FrameworkWorkflow(
243 + name="Build Agent",
244 + skill_name="bmb-agent",
245 + description="Create specialized AI agents with custom expertise and tools",
246 + sequence=1,
247 + ),
248 + FrameworkWorkflow(
249 + name="Build Workflow",
250 + skill_name="bmb-workflow",
251 + description="Design structured workflows with steps and cross-workflow communication",
252 + sequence=2,
253 + ),
254 + FrameworkWorkflow(
255 + name="Build Module",
256 + skill_name="bmb-module",
257 + description="Package agents and workflows into shareable BMad modules",
258 + sequence=3,
259 + ),
260 + ],
261 + ),
262 + "bmad-cis": Framework(
263 + id="bmad-cis",
264 + name="BMad Creative Intelligence Suite",
265 + description="Tools for the fuzzy front-end of development—where ideas are born, problems are reframed, and solutions emerge through structured creativity. Features innovation, design thinking, and brainstorming workflows.",
266 + skill_prefix="cis",
267 + workflows=[
268 + FrameworkWorkflow(
269 + name="Brainstorm",
270 + skill_name="cis-brainstorm",
271 + description="Generate ideas with structured techniques (SCAMPER, Reverse Brainstorming)",
272 + sequence=1,
273 + ),
274 + FrameworkWorkflow(
275 + name="Design Thinking",
276 + skill_name="cis-design-thinking",
277 + description="Human-centered design through empathy, ideation, and prototyping",
278 + sequence=2,
279 + ),
280 + FrameworkWorkflow(
281 + name="Problem Solve",
282 + skill_name="cis-problem-solve",
283 + description="Systematic problem diagnosis and root cause analysis",
284 + sequence=3,
285 + ),
286 + FrameworkWorkflow(
287 + name="Innovation",
288 + skill_name="cis-innovation",
289 + description="Business model innovation and disruption opportunity analysis",
290 + sequence=4,
291 + ),
292 + FrameworkWorkflow(
293 + name="Storytelling",
294 + skill_name="cis-storytelling",
295 + description="Craft compelling narratives for products and features",
296 + sequence=5,
297 + ),
298 + FrameworkWorkflow(
299 + name="Presentation",
300 + skill_name="cis-presentation",
301 + description="Structure and deliver persuasive presentations",
302 + sequence=6,
303 + ),
304 + ],
305 + ),
306 + "bmad-gds": Framework(
307 + id="bmad-gds",
308 + name="BMad Game Dev Studio",
309 + description="Six specialized game development agents: Game Designer (Samus Shepard), Game Architect (Cloud Dragonborn), Game Developer (Link Freeman), Game Scrum Master (Max), Game QA (GLaDOS), and Game Solo Dev (Indie). Two paths: Full (brief→GDD→arch→sprint→stories) for team projects, Quick Flow for solo/indie dev.",
310 + skill_prefix="gds",
311 + workflows=[
312 + FrameworkWorkflow(
313 + name="Brainstorm Game",
314 + skill_name="gds-brainstorm-game",
315 + description="Guided game ideation with Game Designer (Samus Shepard)",
316 + sequence=1,
317 + ),
318 + FrameworkWorkflow(
319 + name="Create Game Brief",
320 + skill_name="gds-create-brief",
321 + description="Define game vision, core loop, and target experience",
322 + sequence=2,
323 + ),
324 + FrameworkWorkflow(
325 + name="Create GDD",
326 + skill_name="gds-create-gdd",
327 + description="Full Game Design Document with mechanics and systems",
328 + sequence=3,
329 + ),
330 + FrameworkWorkflow(
331 + name="Game Architecture",
332 + skill_name="gds-create-architecture",
333 + description="Technical architecture with Game Architect (Cloud Dragonborn)",
334 + sequence=4,
335 + ),
336 + FrameworkWorkflow(
337 + name="Sprint Planning",
338 + skill_name="gds-sprint-planning",
339 + description="Plan sprints with Game Scrum Master (Max)",
340 + sequence=5,
341 + ),
342 + FrameworkWorkflow(
343 + name="Dev Story",
344 + skill_name="gds-dev-story",
345 + description="Implement stories with Game Developer (Link Freeman)",
346 + sequence=6,
347 + ),
348 + FrameworkWorkflow(
349 + name="QA Framework",
350 + skill_name="gds-qa-framework",
351 + description="Set up testing with Game QA (GLaDOS)",
352 + sequence=7,
353 + ),
354 + FrameworkWorkflow(
355 + name="Quick Flow",
356 + skill_name="gds-quick-flow",
357 + description="Solo dev fast path with Game Solo Dev (Indie)",
358 + sequence=8,
359 + ),
360 + ],
361 + ),
362 + "speckit": Framework(
363 + id="speckit",
364 + name="Spec Kit",
365 + description="A specification-driven approach emphasizing upfront clarity. Starts with constitution definition, progresses through specification, planning, task generation, and implementation.",
366 + skill_prefix="speckit",
367 + workflows=[
368 + FrameworkWorkflow(
369 + name="Constitution",
370 + skill_name="speckit-constitution",
371 + description="Define project principles and constraints",
372 + sequence=1,
373 + ),
374 + FrameworkWorkflow(
375 + name="Specify",
376 + skill_name="speckit-specify",
377 + description="Create detailed specifications",
378 + sequence=2,
379 + ),
380 + FrameworkWorkflow(
381 + name="Plan",
382 + skill_name="speckit-plan",
383 + description="Generate implementation roadmap from specs",
384 + sequence=3,
385 + ),
386 + FrameworkWorkflow(
387 + name="Tasks",
388 + skill_name="speckit-tasks",
389 + description="Break plan into actionable tasks",
390 + sequence=4,
391 + ),
392 + FrameworkWorkflow(
393 + name="Implement",
394 + skill_name="speckit-implement",
395 + description="Execute tasks following specifications",
396 + sequence=5,
397 + ),
398 + ],
399 + ),
400 + "prp": Framework(
401 + id="prp",
402 + name="PRP (Prompt-Response Protocol)",
403 + description="A lightweight two-phase methodology: generate comprehensive PRPs (prompts) for tasks, then execute them. Ideal for well-defined, repeatable tasks.",
404 + skill_prefix="prp",
405 + workflows=[
406 + FrameworkWorkflow(
407 + name="Generate PRP",
408 + skill_name="prp-generate",
409 + description="Create detailed prompt specification for task",
410 + sequence=1,
411 + ),
412 + FrameworkWorkflow(
413 + name="Execute PRP",
414 + skill_name="prp-execute",
415 + description="Execute the generated prompt systematically",
416 + sequence=2,
417 + ),
418 + ],
419 + ),
420 + "agentos": Framework(
421 + id="agentos",
422 + name="AgentOS",
423 + description="A standards-based framework focusing on project initialization and adherence to coding standards. Emphasizes consistent project structure and quality gates.",
424 + skill_prefix="agentos",
425 + workflows=[
426 + FrameworkWorkflow(
427 + name="Project Install",
428 + skill_name="agentos-project-install",
429 + description="Initialize project with standard structure",
430 + sequence=1,
431 + ),
432 + FrameworkWorkflow(
433 + name="Standards",
434 + skill_name="agentos-standards",
435 + description="Apply and verify coding standards",
436 + sequence=2,
437 + ),
438 + ],
439 + ),
440 + "amplihack": Framework(
441 + id="amplihack",
442 + name="AMPLIHACK",
443 + description="A multi-agent orchestration framework with specialized agents. Features auto workflow selection, analysis, cascade patterns, debate workflows, fix workflows, and modular building.",
444 + skill_prefix="amplihack",
445 + workflows=[
446 + FrameworkWorkflow(
447 + name="Auto",
448 + skill_name="amplihack-auto",
449 + description="Automatic workflow selection based on task complexity",
450 + sequence=1,
451 + ),
452 + FrameworkWorkflow(
453 + name="Analyze",
454 + skill_name="amplihack-analyze",
455 + description="Deep code/requirements analysis with multiple perspectives",
456 + sequence=2,
457 + ),
458 + FrameworkWorkflow(
459 + name="Cascade",
460 + skill_name="amplihack-cascade",
461 + description="Sequential multi-agent processing for complex tasks",
462 + sequence=3,
463 + ),
464 + FrameworkWorkflow(
465 + name="Debate",
466 + skill_name="amplihack-debate",
467 + description="Multi-perspective debate for technical decisions",
468 + sequence=4,
469 + ),
470 + FrameworkWorkflow(
471 + name="Fix",
472 + skill_name="amplihack-fix",
473 + description="Systematic error resolution with pattern-specific context",
474 + sequence=5,
475 + ),
476 + FrameworkWorkflow(
477 + name="Modular Build",
478 + skill_name="amplihack-modular-build",
479 + description="Build code following brick philosophy with modules",
480 + sequence=6,
481 + ),
482 + ],
483 + ),
484 + "agent-zero-dev": Framework(
485 + id="agent-zero-dev",
486 + name="Agent Zero Dev",
487 + description="Development framework for extending and building features for Agent Zero. Provides patterns, templates, and code generators for creating tools, extensions, skills, API endpoints, subordinate profiles, and project configurations.",
488 + skill_prefix="a0dev",
489 + workflows=[
490 + FrameworkWorkflow(
491 + name="Quickstart",
492 + skill_name="a0dev-quickstart",
493 + description="5-minute guide to extending Agent Zero",
494 + sequence=1,
495 + ),
496 + FrameworkWorkflow(
497 + name="Create Tool",
498 + skill_name="a0dev-create-tool",
499 + description="Create new agent capabilities (tools)",
500 + sequence=2,
501 + ),
502 + FrameworkWorkflow(
503 + name="Create Extension",
504 + skill_name="a0dev-create-extension",
505 + description="Hook into agent lifecycle events",
506 + sequence=3,
507 + ),
508 + FrameworkWorkflow(
509 + name="Create Skill",
510 + skill_name="a0dev-create-skill",
511 + description="Build reusable instruction bundles (SKILL.md)",
512 + sequence=4,
513 + ),
514 + FrameworkWorkflow(
515 + name="Create API",
516 + skill_name="a0dev-create-api",
517 + description="Add Web UI / REST API endpoints",
518 + sequence=5,
519 + ),
520 + FrameworkWorkflow(
521 + name="Create Subordinate",
522 + skill_name="a0dev-create-subordinate",
523 + description="Create specialized agent profiles",
524 + sequence=6,
525 + ),
526 + FrameworkWorkflow(
527 + name="Create Project",
528 + skill_name="a0dev-create-project",
529 + description="Set up project-specific configuration",
530 + sequence=7,
531 + ),
532 + FrameworkWorkflow(
533 + name="Dev Workflow",
534 + skill_name="a0dev-workflow",
535 + description="Full Agent Zero development workflow",
536 + sequence=8,
537 + ),
538 + ],
539 + ),
540 +}
541 +
542 +
543 +# ─────────────────────────────────────────────────────────────────────────────
544 +# Public API
545 +# ─────────────────────────────────────────────────────────────────────────────
546 +
547 +
548 +def get_framework(framework_id: str) -> Optional[Framework]:
549 + """
550 + Get a framework by its ID.
551 +
552 + Args:
553 + framework_id: The framework identifier (e.g., "gsd", "bmad")
554 +
555 + Returns:
556 + Framework object if found, None otherwise
557 + """
558 + return FRAMEWORK_REGISTRY.get(framework_id)
559 +
560 +
561 +def list_frameworks() -> List[Framework]:
562 + """
563 + List all available frameworks.
564 +
565 + Returns:
566 + List of all Framework objects in registry order
567 + """
568 + return [FRAMEWORK_REGISTRY[fid] for fid in ALL_FRAMEWORK_IDS if fid in FRAMEWORK_REGISTRY]
569 +
570 +
571 +def get_active_framework(context: "AgentContext") -> Optional[Framework]:
572 + """
573 + Get the active framework for an agent context.
574 +
575 + Priority:
576 + 1. Project-level override (if project has dev_framework set)
577 + 2. Global setting (settings.dev_framework)
578 + 3. None (no framework active)
579 +
580 + Args:
581 + context: The agent context
582 +
583 + Returns:
584 + Active Framework object, or None if "none" is selected
585 + """
586 + from python.helpers import projects
587 + from python.helpers.settings import get_settings
588 +
589 + framework_id: str = "none"
590 +
591 + # Check project-level override first
592 + project_name = projects.get_context_project_name(context)
593 + if project_name:
594 + try:
595 + project_data = projects.load_basic_project_data(project_name)
596 + project_fw = project_data.get("dev_framework", "")
597 + if project_fw and project_fw != "":
598 + framework_id = project_fw
599 + except Exception:
600 + pass
601 +
602 + # Fall back to global setting
603 + if framework_id == "none" or not framework_id:
604 + settings = get_settings()
605 + framework_id = settings.get("dev_framework", "none")
606 +
607 + if framework_id == "none" or not framework_id:
608 + return None
609 +
610 + return get_framework(framework_id)
611 +
612 +
613 +def get_framework_options() -> List[dict]:
614 + """
615 + Get framework options formatted for settings UI select field.
616 +
617 + Returns:
618 + List of dicts with 'value' and 'label' keys
619 + """
620 + return [
621 + {"value": fw.id, "label": fw.name}
622 + for fw in list_frameworks()
623 + ]
python/helpers/mcp_server.py
+1 -1
@@ -484,4 +484,4 @@ async def mcp_middleware(request: Request, call_next):
484 status_code=403, detail="MCP server is disabled in settings."
485 )
486
487 - return await call_next(request)
487 + return await call_next(request)
\ No newline at end of file
python/helpers/memory.py
+12 -10
@@ -57,7 +57,7 @@ class Memory:
57 MAIN = "main"
58 FRAGMENTS = "fragments"
59 SOLUTIONS = "solutions"
60 - INSTRUMENTS = "instruments"
60 + SKILLS = "skills" # Open SKILL.md standard (replaces legacy instruments)
61
62 index: dict[str, "MyFaiss"] = {}
63
@@ -323,15 +323,17 @@ class Memory:
323 recursive=True,
324 )
325
326 - # load instruments descriptions
327 - index = knowledge_import.load_knowledge(
328 - log_item,
329 - files.get_abs_path("instruments"),
330 - index,
331 - {"area": Memory.Area.INSTRUMENTS.value},
332 - filename_pattern="**/*.md",
333 - recursive=True,
334 - )
326 + # load skills from custom, builtin, and shared directories (SKILL.md standard)
327 + skills_dirs = ["custom", "builtin", "shared"]
328 + for skills_subdir in skills_dirs:
329 + skills_path = files.get_abs_path("skills", skills_subdir)
330 + index = knowledge_import.load_knowledge(
331 + log_item,
332 + skills_path,
333 + index,
334 + {"area": Memory.Area.SKILLS.value},
335 + filename_pattern="**/SKILL.md",
336 + )
337
338 return index
339
python/helpers/memory_consolidation.py
+1 -1
@@ -82,7 +82,7 @@ class MemoryConsolidator:
82
83 Args:
84 new_memory: The new memory content to process
85 - area: Memory area (MAIN, FRAGMENTS, SOLUTIONS, INSTRUMENTS)
85 + area: Memory area (MAIN, FRAGMENTS, SOLUTIONS, SKILLS)
86 metadata: Initial metadata for the memory
87 log_item: Optional log item for progress tracking
88
python/helpers/projects.py
+3
@@ -37,6 +37,7 @@ class BasicProjectData(TypedDict):
37 "own", "global"
38 ] # in the future we can add cutom and point to another existing folder
39 file_structure: FileStructureInjectionSettings
40 + dev_framework: str # "" = use global setting, or specific framework ID
41
42 class EditProjectData(BasicProjectData):
43 name: str
@@ -112,6 +113,7 @@ def _normalizeBasicData(data: BasicProjectData):
113 "file_structure",
114 _default_file_structure_settings(),
115 ),
116 + dev_framework=data.get("dev_framework", ""),
117 )
118
119
@@ -132,6 +134,7 @@ def _normalizeEditData(data: EditProjectData):
134 _default_file_structure_settings(),
135 ),
136 subagents=data.get("subagents", {}),
137 + dev_framework=data.get("dev_framework", ""),
138 )
139
140
python/helpers/settings.py
+10 -3
@@ -149,6 +149,9 @@ class Settings(TypedDict):
149
150 update_check_enabled: bool
151
152 + # Development framework selection
153 + dev_framework: str
154 +
155 class PartialSettings(Settings, total=False):
156 pass
157
@@ -198,6 +201,7 @@ class SettingsOutputAdditional(TypedDict):
201 agent_subdirs: list[FieldOption]
202 knowledge_subdirs: list[FieldOption]
203 stt_models: list[FieldOption]
204 + framework_options: list[FieldOption]
205 is_dockerized: bool
206
207 class SettingsOutput(TypedDict):
@@ -228,6 +232,8 @@ def _ensure_option_present(options: list[OptionT] | None, current_value: str | N
232 return opts
233
234 def convert_out(settings: Settings) -> SettingsOutput:
235 + from python.helpers import frameworks
236 +
237 out = SettingsOutput(
238 settings = settings.copy(),
239 additional = SettingsOutputAdditional(
@@ -247,8 +253,8 @@ def convert_out(settings: Settings) -> SettingsOutput:
253 {"value": "medium", "label": "Medium (769M, English)"},
254 {"value": "large", "label": "Large (1.5B, Multilingual)"},
255 {"value": "turbo", "label": "Turbo (Multilingual)"},
250 - ]
251 -
256 + ],
257 + framework_options=cast(list[FieldOption], frameworks.get_framework_options()),
258 )
259 )
260
@@ -264,6 +270,7 @@ def convert_out(settings: Settings) -> SettingsOutput:
270 additional["agent_subdirs"] = _ensure_option_present(additional.get("agent_subdirs"), current.get("agent_profile"))
271 additional["knowledge_subdirs"] = _ensure_option_present(additional.get("knowledge_subdirs"), current.get("agent_knowledge_subdir"))
272 additional["stt_models"] = _ensure_option_present(additional.get("stt_models"), current.get("stt_model_size"))
273 + additional["framework_options"] = _ensure_option_present(additional.get("framework_options"), current.get("dev_framework"))
274
275 # masked api keys
276 providers = get_providers("chat") + get_providers("embedding")
@@ -304,7 +311,6 @@ def convert_out(settings: Settings) -> SettingsOutput:
311 out["settings"][key] = _dict_to_env(value)
312 return out
313
307 -
314 def _get_api_key_field(settings: Settings, provider: str, title: str) -> SettingsField:
315 key = settings["api_keys"].get(provider, models.get_api_key(provider))
316 # For API keys, use simple asterisk placeholder for existing keys
@@ -530,6 +536,7 @@ def get_default_settings() -> Settings:
536 secrets="",
537 litellm_global_kwargs=get_default_value("litellm_global_kwargs", {}),
538 update_check_enabled=get_default_value("update_check_enabled", True),
539 + dev_framework=get_default_value("dev_framework", "none"),
540 )
541
542
python/helpers/skills.py new
+368
@@ -0,0 +1,368 @@
1 +from __future__ import annotations
2 +
3 +import os
4 +import re
5 +from dataclasses import dataclass, field
6 +from pathlib import Path
7 +from typing import Any, Dict, Iterable, List, Literal, Optional, Tuple
8 +
9 +from python.helpers import files
10 +
11 +try:
12 + import yaml # type: ignore
13 +except Exception: # pragma: no cover
14 + yaml = None # type: ignore
15 +
16 +
17 +SkillSource = Literal["custom", "builtin", "shared", "framework"]
18 +
19 +
20 +@dataclass(slots=True)
21 +class Skill:
22 + name: str
23 + description: str
24 + path: Path
25 + skill_md_path: Path
26 + source: SkillSource
27 +
28 + version: str = ""
29 + author: str = ""
30 + tags: List[str] = field(default_factory=list)
31 + triggers: List[str] = field(default_factory=list)
32 + allowed_tools: List[str] = field(default_factory=list)
33 + license: str = ""
34 + metadata: Dict[str, Any] = field(default_factory=dict)
35 +
36 + # Optional heavy fields (only set when requested)
37 + content: str = "" # body content (markdown without frontmatter)
38 + raw_frontmatter: Dict[str, Any] = field(default_factory=dict)
39 +
40 +
41 +def get_skills_base_dir() -> Path:
42 + return Path(files.get_abs_path("skills"))
43 +
44 +
45 +def get_skill_roots(
46 + order: Optional[List[SkillSource]] = None,
47 + framework_id: Optional[str] = None,
48 +) -> List[Tuple[SkillSource, Path]]:
49 + """
50 + Get skill root directories in priority order.
51 +
52 + Args:
53 + order: List of skill sources to search (default: custom, builtin, shared)
54 + framework_id: If provided and not "none", framework skills are added at highest priority
55 +
56 + Returns:
57 + List of (source, path) tuples in priority order
58 + """
59 + base = get_skills_base_dir()
60 + order = order or ["custom", "builtin", "shared"]
61 + roots: List[Tuple[SkillSource, Path]] = [(src, base / src) for src in order]
62 +
63 + # Framework skills take priority when active
64 + if framework_id and framework_id != "none":
65 + fw_path = base / "frameworks" / framework_id
66 + if fw_path.exists():
67 + roots.insert(0, ("framework", fw_path))
68 +
69 + return roots
70 +
71 +
72 +def _is_hidden_path(path: Path) -> bool:
73 + return any(part.startswith(".") for part in path.parts)
74 +
75 +
76 +def discover_skill_md_files(root: Path) -> List[Path]:
77 + """
78 + Recursively discover SKILL.md files under a root directory.
79 + Hidden folders/files are ignored.
80 + """
81 + if not root.exists():
82 + return []
83 +
84 + results: List[Path] = []
85 + for p in root.rglob("SKILL.md"):
86 + try:
87 + if not p.is_file():
88 + continue
89 + if _is_hidden_path(p.relative_to(root)):
90 + continue
91 + results.append(p)
92 + except Exception:
93 + # If relative_to fails (weird symlink), fall back to conservative checks
94 + if p.is_file() and ".git" not in str(p):
95 + results.append(p)
96 + results.sort(key=lambda x: str(x))
97 + return results
98 +
99 +
100 +def _coerce_list(value: Any) -> List[str]:
101 + if value is None:
102 + return []
103 + if isinstance(value, list):
104 + return [str(v).strip() for v in value if str(v).strip()]
105 + if isinstance(value, tuple):
106 + return [str(v).strip() for v in list(value) if str(v).strip()]
107 + if isinstance(value, str):
108 + # Support comma-separated strings
109 + parts = [p.strip() for p in value.split(",")]
110 + return [p for p in parts if p]
111 + return [str(value).strip()] if str(value).strip() else []
112 +
113 +
114 +def _normalize_name(name: str) -> str:
115 + return re.sub(r"\s+", "-", (name or "").strip().lower())
116 +
117 +
118 +def _read_text(path: Path) -> str:
119 + return path.read_text(encoding="utf-8", errors="replace")
120 +
121 +
122 +def split_frontmatter(markdown: str) -> Tuple[Dict[str, Any], str]:
123 + """
124 + Splits a SKILL.md into (frontmatter_dict, body_text).
125 +
126 + If no YAML frontmatter is present, returns ({}, full_text).
127 + """
128 + text = markdown or ""
129 + if not text.lstrip().startswith("---"):
130 + return {}, text.strip()
131 +
132 + # We require frontmatter fence at the start (allow leading whitespace/newlines).
133 + lines = text.splitlines()
134 + # find first '---' line
135 + start_idx = None
136 + for i, line in enumerate(lines):
137 + if line.strip() == "---":
138 + start_idx = i
139 + break
140 + if line.strip(): # non-empty before fence => not frontmatter
141 + return {}, text.strip()
142 +
143 + if start_idx is None:
144 + return {}, text.strip()
145 +
146 + end_idx = None
147 + for j in range(start_idx + 1, len(lines)):
148 + if lines[j].strip() == "---":
149 + end_idx = j
150 + break
151 +
152 + if end_idx is None:
153 + return {}, text.strip()
154 +
155 + fm_text = "\n".join(lines[start_idx + 1 : end_idx]).strip()
156 + body = "\n".join(lines[end_idx + 1 :]).strip()
157 + fm = parse_frontmatter(fm_text)
158 + return fm, body
159 +
160 +
161 +def parse_frontmatter(frontmatter_text: str) -> Dict[str, Any]:
162 + """
163 + Parse YAML frontmatter. Uses PyYAML if available, otherwise a minimal fallback parser.
164 + """
165 + if not frontmatter_text.strip():
166 + return {}
167 +
168 + if yaml is not None:
169 + try:
170 + parsed = yaml.safe_load(frontmatter_text) # type: ignore[attr-defined]
171 + return parsed if isinstance(parsed, dict) else {}
172 + except Exception:
173 + return {}
174 +
175 + # Fallback: very small YAML subset (key: value, lists with '- item')
176 + data: Dict[str, Any] = {}
177 + current_key: Optional[str] = None
178 + for raw in frontmatter_text.splitlines():
179 + line = raw.rstrip()
180 + if not line.strip() or line.strip().startswith("#"):
181 + continue
182 +
183 + m = re.match(r"^([A-Za-z0-9_.-]+)\s*:\s*(.*)$", line)
184 + if m:
185 + key = m.group(1)
186 + val = m.group(2).strip()
187 + current_key = key
188 + if val == "":
189 + data[key] = []
190 + else:
191 + # strip surrounding quotes
192 + if (val.startswith('"') and val.endswith('"')) or (
193 + val.startswith("'") and val.endswith("'")
194 + ):
195 + val = val[1:-1]
196 + data[key] = val
197 + continue
198 +
199 + m_list = re.match(r"^\s*-\s*(.*)$", line)
200 + if m_list and current_key:
201 + item = m_list.group(1).strip()
202 + if (item.startswith('"') and item.endswith('"')) or (
203 + item.startswith("'") and item.endswith("'")
204 + ):
205 + item = item[1:-1]
206 + if not isinstance(data.get(current_key), list):
207 + data[current_key] = []
208 + data[current_key].append(item)
209 + continue
210 +
211 + return data
212 +
213 +
214 +def skill_from_markdown(
215 + skill_md_path: Path,
216 + source: SkillSource,
217 + *,
218 + include_content: bool = False,
219 +) -> Optional[Skill]:
220 + try:
221 + text = _read_text(skill_md_path)
222 + except Exception:
223 + return None
224 +
225 + fm, body = split_frontmatter(text)
226 + skill_dir = skill_md_path.parent
227 +
228 + name = str(fm.get("name") or fm.get("skill") or skill_dir.name).strip()
229 + description = str(
230 + fm.get("description") or fm.get("when_to_use") or fm.get("summary") or ""
231 + ).strip()
232 +
233 + # Cross-platform aliases:
234 + # - Claude Code leans on description (triggers may be embedded there)
235 + # - Some repos use triggers/trigger_patterns
236 + triggers = _coerce_list(
237 + fm.get("triggers")
238 + or fm.get("trigger_patterns")
239 + or fm.get("trigger")
240 + or fm.get("activation")
241 + )
242 +
243 + tags = _coerce_list(fm.get("tags") or fm.get("tag"))
244 + allowed_tools = _coerce_list(fm.get("allowed_tools") or fm.get("tools"))
245 +
246 + version = str(fm.get("version") or "").strip()
247 + author = str(fm.get("author") or "").strip()
248 + license_ = str(fm.get("license") or "").strip()
249 +
250 + meta = fm.get("metadata")
251 + if not isinstance(meta, dict):
252 + meta = {}
253 +
254 + skill = Skill(
255 + name=name,
256 + description=description,
257 + path=skill_dir,
258 + skill_md_path=skill_md_path,
259 + source=source,
260 + version=version,
261 + author=author,
262 + tags=tags,
263 + triggers=triggers,
264 + allowed_tools=allowed_tools,
265 + license=license_,
266 + metadata=dict(meta),
267 + raw_frontmatter=fm if include_content else {},
268 + content=body if include_content else "",
269 + )
270 + return skill
271 +
272 +
273 +def list_skills(
274 + *,
275 + include_content: bool = False,
276 + dedupe: bool = True,
277 + root_order: Optional[List[SkillSource]] = None,
278 + framework_id: Optional[str] = None,
279 +) -> List[Skill]:
280 + skills: List[Skill] = []
281 +
282 + roots = get_skill_roots(order=root_order, framework_id=framework_id)
283 + for source, root in roots:
284 + for skill_md in discover_skill_md_files(root):
285 + s = skill_from_markdown(skill_md, source, include_content=include_content)
286 + if s:
287 + skills.append(s)
288 +
289 + if not dedupe:
290 + return skills
291 +
292 + # Dedupe by normalized name, preserving root_order priority (earlier wins)
293 + by_name: Dict[str, Skill] = {}
294 + for s in skills:
295 + key = _normalize_name(s.name) or _normalize_name(s.path.name)
296 + if key and key not in by_name:
297 + by_name[key] = s
298 + return list(by_name.values())
299 +
300 +
301 +def find_skill(
302 + skill_name: str,
303 + *,
304 + include_content: bool = False,
305 + root_order: Optional[List[SkillSource]] = None,
306 + framework_id: Optional[str] = None,
307 +) -> Optional[Skill]:
308 + target = _normalize_name(skill_name)
309 + if not target:
310 + return None
311 +
312 + roots = get_skill_roots(order=root_order, framework_id=framework_id)
313 + for source, root in roots:
314 + for skill_md in discover_skill_md_files(root):
315 + s = skill_from_markdown(skill_md, source, include_content=include_content)
316 + if not s:
317 + continue
318 + if _normalize_name(s.name) == target or _normalize_name(s.path.name) == target:
319 + return s
320 + return None
321 +
322 +
323 +def search_skills(
324 + query: str,
325 + *,
326 + limit: int = 25,
327 + framework_id: Optional[str] = None,
328 +) -> List[Skill]:
329 + q = (query or "").strip().lower()
330 + if not q:
331 + return []
332 +
333 + terms = [t for t in re.split(r"\s+", q) if t]
334 + candidates = list_skills(include_content=False, dedupe=True, framework_id=framework_id)
335 +
336 + scored: List[Tuple[int, Skill]] = []
337 + for s in candidates:
338 + name = s.name.lower()
339 + desc = (s.description or "").lower()
340 + tags = [t.lower() for t in s.tags]
341 +
342 + score = 0
343 + for term in terms:
344 + if term in name:
345 + score += 3
346 + if term in desc:
347 + score += 2
348 + if any(term in tag for tag in tags):
349 + score += 1
350 +
351 + if score > 0:
352 + scored.append((score, s))
353 +
354 + scored.sort(key=lambda pair: (-pair[0], pair[1].name))
355 + return [s for _score, s in scored[:limit]]
356 +
357 +
358 +def safe_path_within_dir(base_dir: Path, rel_path: str) -> Path:
359 + """
360 + Resolve rel_path inside base_dir, preventing directory traversal.
361 + """
362 + base = base_dir.resolve()
363 + candidate = (base / rel_path).resolve()
364 + if os.path.commonpath([str(candidate), str(base)]) != str(base):
365 + raise ValueError("Path escapes skill directory")
366 + return candidate
367 +
368 +
python/helpers/skills_cli.py new
+364
@@ -0,0 +1,364 @@
1 +#!/usr/bin/env python3
2 +"""
3 +Skills CLI - Easy skill management for Agent Zero
4 +
5 +Usage:
6 + python -m python.helpers.skills_cli list List all skills
7 + python -m python.helpers.skills_cli create <name> Create a new skill
8 + python -m python.helpers.skills_cli show <name> Show skill details
9 + python -m python.helpers.skills_cli validate <name> Validate a skill
10 + python -m python.helpers.skills_cli search <query> Search skills
11 +"""
12 +
13 +import argparse
14 +import os
15 +import sys
16 +import yaml
17 +import re
18 +from pathlib import Path
19 +from typing import Optional, List, Dict, Any
20 +from dataclasses import dataclass
21 +from datetime import datetime
22 +
23 +# Add parent directory to path for imports
24 +sys.path.insert(0, str(Path(__file__).parent.parent.parent))
25 +
26 +from python.helpers import files
27 +
28 +
29 +@dataclass
30 +class Skill:
31 + """Represents a skill loaded from SKILL.md"""
32 + name: str
33 + description: str
34 + path: Path
35 + version: str = "1.0.0"
36 + author: str = ""
37 + tags: List[str] = None
38 + trigger_patterns: List[str] = None
39 + content: str = ""
40 +
41 + def __post_init__(self):
42 + if self.tags is None:
43 + self.tags = []
44 + if self.trigger_patterns is None:
45 + self.trigger_patterns = []
46 +
47 +
48 +def get_skills_dirs() -> List[Path]:
49 + """Get all skill directories"""
50 + base = Path(files.get_abs_path("skills"))
51 + return [
52 + base / "builtin",
53 + base / "custom",
54 + base / "shared",
55 + ]
56 +
57 +
58 +def parse_skill_file(skill_path: Path) -> Optional[Skill]:
59 + """Parse a SKILL.md file and return a Skill object"""
60 + try:
61 + content = skill_path.read_text(encoding="utf-8")
62 +
63 + # Parse YAML frontmatter
64 + if content.startswith("---"):
65 + parts = content.split("---", 2)
66 + if len(parts) >= 3:
67 + frontmatter = yaml.safe_load(parts[1])
68 + body = parts[2].strip()
69 +
70 + return Skill(
71 + name=frontmatter.get("name", skill_path.parent.name),
72 + description=frontmatter.get("description", ""),
73 + path=skill_path.parent,
74 + version=frontmatter.get("version", "1.0.0"),
75 + author=frontmatter.get("author", ""),
76 + tags=frontmatter.get("tags", []),
77 + trigger_patterns=frontmatter.get("trigger_patterns", []),
78 + content=body,
79 + )
80 +
81 + return None
82 + except Exception as e:
83 + print(f"Error parsing {skill_path}: {e}")
84 + return None
85 +
86 +
87 +def list_skills() -> List[Skill]:
88 + """List all available skills"""
89 + skills = []
90 + for skills_dir in get_skills_dirs():
91 + if not skills_dir.exists():
92 + continue
93 + for skill_dir in skills_dir.iterdir():
94 + if skill_dir.is_dir():
95 + skill_file = skill_dir / "SKILL.md"
96 + if skill_file.exists():
97 + skill = parse_skill_file(skill_file)
98 + if skill:
99 + skills.append(skill)
100 + return skills
101 +
102 +
103 +def find_skill(name: str) -> Optional[Skill]:
104 + """Find a skill by name"""
105 + for skill in list_skills():
106 + if skill.name == name or skill.path.name == name:
107 + return skill
108 + return None
109 +
110 +
111 +def search_skills(query: str) -> List[Skill]:
112 + """Search skills by name, description, or tags"""
113 + query = query.lower()
114 + results = []
115 + for skill in list_skills():
116 + if (
117 + query in skill.name.lower()
118 + or query in skill.description.lower()
119 + or any(query in tag.lower() for tag in skill.tags)
120 + or any(query in trigger.lower() for trigger in skill.trigger_patterns)
121 + ):
122 + results.append(skill)
123 + return results
124 +
125 +
126 +def validate_skill(skill: Skill) -> List[str]:
127 + """Validate a skill and return list of issues"""
128 + issues = []
129 +
130 + # Required fields
131 + if not skill.name:
132 + issues.append("Missing required field: name")
133 + if not skill.description:
134 + issues.append("Missing required field: description")
135 +
136 + # Name format
137 + if skill.name and not re.match(r"^[a-z0-9_-]+$", skill.name):
138 + issues.append(f"Invalid name format: '{skill.name}' (use lowercase, hyphens, underscores)")
139 +
140 + # Description length
141 + if skill.description and len(skill.description) < 20:
142 + issues.append("Description is too short (minimum 20 characters)")
143 +
144 + # Content
145 + if len(skill.content) < 100:
146 + issues.append("Skill content is too short (minimum 100 characters)")
147 +
148 + # Check for associated files
149 + skill_dir = skill.path
150 + has_scripts = (skill_dir / "scripts").exists()
151 + has_docs = (skill_dir / "docs").exists()
152 +
153 + return issues
154 +
155 +
156 +def create_skill(name: str, description: str = "", author: str = "") -> Path:
157 + """Create a new skill from template"""
158 + # Use custom directory for user-created skills
159 + custom_dir = Path(files.get_abs_path("skills/custom"))
160 + custom_dir.mkdir(parents=True, exist_ok=True)
161 +
162 + skill_dir = custom_dir / name
163 + if skill_dir.exists():
164 + raise ValueError(f"Skill '{name}' already exists at {skill_dir}")
165 +
166 + # Create directory structure
167 + skill_dir.mkdir(parents=True)
168 + (skill_dir / "scripts").mkdir()
169 + (skill_dir / "docs").mkdir()
170 +
171 + # Create SKILL.md from template
172 + skill_content = f'''---
173 +name: "{name}"
174 +description: "{description or 'Description of what this skill does and when to use it'}"
175 +version: "1.0.0"
176 +author: "{author or 'Your Name'}"
177 +tags: ["custom"]
178 +trigger_patterns:
179 + - "{name}"
180 +---
181 +
182 +# {name.replace("-", " ").replace("_", " ").title()}
183 +
184 +## When to Use
185 +
186 +Describe when this skill should be activated.
187 +
188 +## Instructions
189 +
190 +Provide detailed instructions for the agent to follow.
191 +
192 +### Step 1: First Step
193 +
194 +Description of what to do first.
195 +
196 +### Step 2: Second Step
197 +
198 +Description of what to do next.
199 +
200 +## Examples
201 +
202 +**User**: "Example prompt that triggers this skill"
203 +
204 +**Agent Response**:
205 +> Example of how the agent should respond
206 +
207 +## Tips
208 +
209 +- Tip 1: Helpful guidance
210 +- Tip 2: More helpful guidance
211 +
212 +## Anti-Patterns
213 +
214 +- Don't do this
215 +- Avoid that
216 +'''
217 +
218 + skill_file = skill_dir / "SKILL.md"
219 + skill_file.write_text(skill_content, encoding="utf-8")
220 +
221 + # Create placeholder README in docs
222 + readme = skill_dir / "docs" / "README.md"
223 + readme.write_text(f"# {name}\n\nAdditional documentation for the {name} skill.\n")
224 +
225 + return skill_dir
226 +
227 +
228 +def print_skill_table(skills: List[Skill]):
229 + """Print skills in a formatted table"""
230 + if not skills:
231 + print("No skills found.")
232 + return
233 +
234 + # Calculate column widths
235 + name_width = max(len(s.name) for s in skills) + 2
236 + desc_width = 50
237 +
238 + # Print header
239 + print(f"\n{'Name':<{name_width}} {'Version':<10} {'Tags':<20} Description")
240 + print("-" * (name_width + 80))
241 +
242 + # Print skills
243 + for skill in skills:
244 + tags = ", ".join(skill.tags[:3])
245 + if len(skill.tags) > 3:
246 + tags += "..."
247 + desc = skill.description[:desc_width]
248 + if len(skill.description) > desc_width:
249 + desc += "..."
250 + print(f"{skill.name:<{name_width}} {skill.version:<10} {tags:<20} {desc}")
251 +
252 + print(f"\nTotal: {len(skills)} skills")
253 +
254 +
255 +def main():
256 + parser = argparse.ArgumentParser(
257 + description="Agent Zero Skills CLI",
258 + formatter_class=argparse.RawDescriptionHelpFormatter,
259 + epilog="""
260 +Examples:
261 + %(prog)s list List all skills
262 + %(prog)s create my-skill Create a new skill
263 + %(prog)s show brainstorming Show skill details
264 + %(prog)s validate my-skill Validate a skill
265 + %(prog)s search python Search for skills
266 + """
267 + )
268 +
269 + subparsers = parser.add_subparsers(dest="command", help="Available commands")
270 +
271 + # List command
272 + list_parser = subparsers.add_parser("list", help="List all skills")
273 + list_parser.add_argument("--tags", help="Filter by tags (comma-separated)")
274 +
275 + # Create command
276 + create_parser = subparsers.add_parser("create", help="Create a new skill")
277 + create_parser.add_argument("name", help="Skill name (lowercase, use hyphens)")
278 + create_parser.add_argument("-d", "--description", help="Skill description")
279 + create_parser.add_argument("-a", "--author", help="Author name")
280 +
281 + # Show command
282 + show_parser = subparsers.add_parser("show", help="Show skill details")
283 + show_parser.add_argument("name", help="Skill name")
284 +
285 + # Validate command
286 + validate_parser = subparsers.add_parser("validate", help="Validate a skill")
287 + validate_parser.add_argument("name", help="Skill name")
288 +
289 + # Search command
290 + search_parser = subparsers.add_parser("search", help="Search skills")
291 + search_parser.add_argument("query", help="Search query")
292 +
293 + args = parser.parse_args()
294 +
295 + if args.command == "list":
296 + skills = list_skills()
297 + if args.tags:
298 + filter_tags = [t.strip().lower() for t in args.tags.split(",")]
299 + skills = [s for s in skills if any(t in [tag.lower() for tag in s.tags] for t in filter_tags)]
300 + print_skill_table(skills)
301 +
302 + elif args.command == "create":
303 + try:
304 + skill_dir = create_skill(args.name, args.description, args.author)
305 + print(f"\n✅ Created skill at: {skill_dir}")
306 + print(f"\nNext steps:")
307 + print(f" 1. Edit {skill_dir / 'SKILL.md'} to add your instructions")
308 + print(f" 2. Add any helper scripts to {skill_dir / 'scripts'}/")
309 + print(f" 3. Run: python -m python.helpers.skills_cli validate {args.name}")
310 + except ValueError as e:
311 + print(f"\n❌ Error: {e}")
312 + sys.exit(1)
313 +
314 + elif args.command == "show":
315 + skill = find_skill(args.name)
316 + if skill:
317 + print(f"\n{'=' * 60}")
318 + print(f"Skill: {skill.name}")
319 + print(f"{'=' * 60}")
320 + print(f"Version: {skill.version}")
321 + print(f"Author: {skill.author or 'Unknown'}")
322 + print(f"Path: {skill.path}")
323 + print(f"Tags: {', '.join(skill.tags) if skill.tags else 'None'}")
324 + print(f"Triggers: {', '.join(skill.trigger_patterns) if skill.trigger_patterns else 'None'}")
325 + print(f"\nDescription:")
326 + print(f" {skill.description}")
327 + print(f"\nContent Preview (first 500 chars):")
328 + print("-" * 60)
329 + print(skill.content[:500])
330 + if len(skill.content) > 500:
331 + print("...")
332 + print("-" * 60)
333 + else:
334 + print(f"\n❌ Skill '{args.name}' not found")
335 + sys.exit(1)
336 +
337 + elif args.command == "validate":
338 + skill = find_skill(args.name)
339 + if skill:
340 + issues = validate_skill(skill)
341 + if issues:
342 + print(f"\n⚠️ Validation issues for '{args.name}':")
343 + for issue in issues:
344 + print(f" - {issue}")
345 + else:
346 + print(f"\n✅ Skill '{args.name}' is valid!")
347 + else:
348 + print(f"\n❌ Skill '{args.name}' not found")
349 + sys.exit(1)
350 +
351 + elif args.command == "search":
352 + results = search_skills(args.query)
353 + if results:
354 + print(f"\nSearch results for '{args.query}':")
355 + print_skill_table(results)
356 + else:
357 + print(f"\nNo skills found matching '{args.query}'")
358 +
359 + else:
360 + parser.print_help()
361 +
362 +
363 +if __name__ == "__main__":
364 + main()
python/helpers/skills_import.py new
+251
@@ -0,0 +1,251 @@
1 +from __future__ import annotations
2 +
3 +import os
4 +import shutil
5 +import tempfile
6 +import time
7 +import zipfile
8 +from dataclasses import dataclass
9 +from pathlib import Path
10 +from typing import Iterable, List, Literal, Optional, Tuple
11 +
12 +from python.helpers import files
13 +from python.helpers.skills import discover_skill_md_files
14 +
15 +
16 +ConflictPolicy = Literal["skip", "overwrite", "rename"]
17 +DestSubdir = Literal["shared", "custom", "project"]
18 +
19 +# Project skills folder name (inside .a0proj)
20 +PROJECT_SKILLS_DIR = "skills"
21 +
22 +
23 +@dataclass(slots=True)
24 +class ImportPlanItem:
25 + src_root: Path
26 + src_skill_dir: Path
27 + dest_skill_dir: Path
28 +
29 +
30 +@dataclass(slots=True)
31 +class ImportResult:
32 + imported: List[Path]
33 + skipped: List[Path]
34 + source_root: Path
35 + destination_root: Path
36 + namespace: str
37 +
38 +
39 +def _is_within(child: Path, parent: Path) -> bool:
40 + try:
41 + child.resolve().relative_to(parent.resolve())
42 + return True
43 + except Exception:
44 + return False
45 +
46 +
47 +def _derive_namespace(source: Path) -> str:
48 + # Use stem for zip, name for directory
49 + return (source.stem or source.name or "import").strip()
50 +
51 +
52 +def _candidate_skill_roots(source_dir: Path) -> List[Path]:
53 + """
54 + Heuristics to find likely skill roots inside a repo/pack:
55 + - <source>/skills
56 + - <source>/plugins/*/skills (Claude Code style)
57 + - fallback: <source>
58 + """
59 + candidates: List[Path] = []
60 +
61 + direct = source_dir / "skills"
62 + if direct.is_dir() and discover_skill_md_files(direct):
63 + candidates.append(direct)
64 +
65 + plugins = source_dir / "plugins"
66 + if plugins.is_dir():
67 + for child in plugins.iterdir():
68 + if not child.is_dir():
69 + continue
70 + skills_dir = child / "skills"
71 + if skills_dir.is_dir() and discover_skill_md_files(skills_dir):
72 + candidates.append(skills_dir)
73 +
74 + # Deduplicate while preserving order
75 + unique: List[Path] = []
76 + seen = set()
77 + for c in candidates:
78 + key = str(c.resolve())
79 + if key not in seen:
80 + seen.add(key)
81 + unique.append(c)
82 +
83 + return unique or [source_dir]
84 +
85 +
86 +def _unzip_to_temp_dir(zip_path: Path) -> Path:
87 + """
88 + Extract a zip into a temp folder under tmp/skill_imports (inside Agent Zero base dir).
89 + Returns the extraction root folder.
90 + """
91 + base_tmp = Path(files.get_abs_path("tmp", "skill_imports"))
92 + base_tmp.mkdir(parents=True, exist_ok=True)
93 + stamp = time.strftime("%Y%m%d_%H%M%S")
94 + target = base_tmp / f"import_{zip_path.stem}_{stamp}"
95 + target.mkdir(parents=True, exist_ok=True)
96 +
97 + with zipfile.ZipFile(zip_path, "r") as z:
98 + z.extractall(target)
99 +
100 + # If zip contains a single top-level folder, treat that as the root
101 + children = [p for p in target.iterdir()]
102 + if len(children) == 1 and children[0].is_dir():
103 + return children[0]
104 + return target
105 +
106 +
107 +def build_import_plan(
108 + source: Path,
109 + dest_root: Path,
110 + *,
111 + namespace: Optional[str] = None,
112 +) -> Tuple[List[ImportPlanItem], Path]:
113 + """
114 + Build a copy plan for importing skills from a source folder.
115 +
116 + Returns: (plan_items, source_root_dir_used_for_scan)
117 + """
118 + source_dir = source
119 + roots = _candidate_skill_roots(source_dir)
120 + plan: List[ImportPlanItem] = []
121 + ns = (namespace or _derive_namespace(source)).strip()
122 + dest_ns_root = dest_root / ns
123 +
124 + for root in roots:
125 + for skill_md in discover_skill_md_files(root):
126 + skill_dir = skill_md.parent
127 + # Skip if the skill dir is already inside destination (prevents recursive import)
128 + if _is_within(skill_dir, dest_root):
129 + continue
130 + try:
131 + rel = skill_dir.resolve().relative_to(root.resolve())
132 + except Exception:
133 + # If relative fails due to symlink oddities, just use leaf folder name
134 + rel = Path(skill_dir.name)
135 + dest_dir = dest_ns_root / rel
136 + plan.append(ImportPlanItem(src_root=root, src_skill_dir=skill_dir, dest_skill_dir=dest_dir))
137 +
138 + # Deduplicate by destination path (keep first occurrence)
139 + seen_dest = set()
140 + deduped: List[ImportPlanItem] = []
141 + for item in plan:
142 + key = str(item.dest_skill_dir.resolve())
143 + if key in seen_dest:
144 + continue
145 + seen_dest.add(key)
146 + deduped.append(item)
147 +
148 + return deduped, roots[0]
149 +
150 +
151 +def _resolve_conflict(dest: Path, policy: ConflictPolicy) -> Tuple[Path, bool]:
152 + """
153 + Returns (final_dest_path, should_copy).
154 + """
155 + if not dest.exists():
156 + return dest, True
157 +
158 + if policy == "skip":
159 + return dest, False
160 +
161 + if policy == "overwrite":
162 + shutil.rmtree(dest)
163 + return dest, True
164 +
165 + # rename
166 + i = 2
167 + while True:
168 + candidate = dest.with_name(f"{dest.name}_{i}")
169 + if not candidate.exists():
170 + return candidate, True
171 + i += 1
172 +
173 +
174 +def get_project_skills_folder(project_name: str) -> Path:
175 + """Get the skills folder path for a project."""
176 + from python.helpers.projects import get_project_meta_folder
177 + return Path(get_project_meta_folder(project_name, PROJECT_SKILLS_DIR))
178 +
179 +
180 +def import_skills(
181 + source_path: str,
182 + *,
183 + dest_subdir: DestSubdir = "shared",
184 + namespace: Optional[str] = None,
185 + conflict: ConflictPolicy = "skip",
186 + dry_run: bool = False,
187 + project_name: Optional[str] = None,
188 +) -> ImportResult:
189 + """
190 + Import external Skills into skills/<dest_subdir>/<namespace>/...
191 +
192 + If dest_subdir is "project", imports into the project's .a0proj/skills/ folder.
193 +
194 + - source_path can be a directory or a .zip file
195 + - Uses heuristics to detect the Skills root(s)
196 + - Copies each skill folder (parent of SKILL.md) as-is
197 + """
198 + src = Path(source_path).expanduser()
199 + if not src.is_absolute():
200 + src = (Path.cwd() / src).resolve()
201 +
202 + if not src.exists():
203 + raise FileNotFoundError(f"Source not found: {src}")
204 +
205 + # Determine destination root based on dest_subdir
206 + if dest_subdir == "project":
207 + if not project_name:
208 + raise ValueError("project_name is required when dest_subdir is 'project'")
209 + dest_root = get_project_skills_folder(project_name)
210 + else:
211 + dest_root = Path(files.get_abs_path("skills", dest_subdir))
212 + dest_root.mkdir(parents=True, exist_ok=True)
213 +
214 + extracted_root: Optional[Path] = None
215 + source_dir: Path
216 + if src.is_file() and src.suffix.lower() == ".zip":
217 + extracted_root = _unzip_to_temp_dir(src)
218 + source_dir = extracted_root
219 + elif src.is_dir():
220 + source_dir = src
221 + else:
222 + raise ValueError("Source must be a directory or a .zip file")
223 +
224 + ns = (namespace or _derive_namespace(src)).strip()
225 + if not ns:
226 + ns = "import"
227 +
228 + plan, root_used = build_import_plan(source_dir, dest_root, namespace=ns)
229 + imported: List[Path] = []
230 + skipped: List[Path] = []
231 +
232 + for item in plan:
233 + final_dest, should_copy = _resolve_conflict(item.dest_skill_dir, conflict)
234 + if not should_copy:
235 + skipped.append(item.dest_skill_dir)
236 + continue
237 + if dry_run:
238 + imported.append(final_dest)
239 + continue
240 + final_dest.parent.mkdir(parents=True, exist_ok=True)
241 + shutil.copytree(item.src_skill_dir, final_dest)
242 + imported.append(final_dest)
243 +
244 + return ImportResult(
245 + imported=imported,
246 + skipped=skipped,
247 + source_root=root_used,
248 + destination_root=dest_root,
249 + namespace=ns,
250 + )
251 +
python/tools/call_subordinate.py
+3
@@ -33,6 +33,9 @@ class Delegation(Tool):
33 # run subordinate monologue
34 result = await subordinate.monologue()
35
36 + # seal the subordinate's current topic so messages move to `topics` for compression
37 + subordinate.history.new_topic()
38 +
39 # hint to use includes for long responses
40 additional = None
41 if len(result) >= save_tool_call_file.LEN_MIN:
python/tools/skills_tool.py new
+404
@@ -0,0 +1,404 @@
1 +from __future__ import annotations
2 +
3 +import json
4 +import re
5 +import shlex
6 +from pathlib import Path
7 +from typing import Any, Dict, List
8 +
9 +from python.helpers.tool import Tool, Response
10 +from python.helpers import files
11 +from python.helpers import skills as skills_helper
12 +from python.helpers import frameworks
13 +
14 +
15 +class SkillsTool(Tool):
16 + """
17 + Manage and use SKILL.md-based Skills (Anthropic open standard).
18 +
19 + Methods (tool_args.method):
20 + - list
21 + - search (query)
22 + - load (skill_name)
23 + - read_file (skill_name, file_path)
24 + - execute_script (skill_name, script_path, script_args, arg_style)
25 +
26 + arg_style options for execute_script:
27 + - "positional" (default): Pass values as positional args (sys.argv[1], sys.argv[2])
28 + Example: {"input": "file.pdf", "output": "/tmp"} → sys.argv = ['script.py', 'file.pdf', '/tmp']
29 + - "named": Pass as --key value pairs (for argparse/click scripts)
30 + Example: {"input": "file.pdf", "output": "/tmp"} → sys.argv = ['script.py', '--input', 'file.pdf', '--output', '/tmp']
31 + - "env": Only use environment variables (SKILL_ARG_INPUT, SKILL_ARG_OUTPUT)
32 +
33 + Environment variables (SKILL_ARG_*) are always set regardless of arg_style.
34 + """
35 +
36 + async def execute(self, **kwargs) -> Response:
37 + method = (
38 + (kwargs.get("method") or self.args.get("method") or self.method or "")
39 + .strip()
40 + .lower()
41 + )
42 +
43 + try:
44 + if method == "list":
45 + return Response(message=self._list(), break_loop=False)
46 + if method == "search":
47 + query = str(kwargs.get("query") or "").strip()
48 + return Response(message=self._search(query), break_loop=False)
49 + if method == "load":
50 + skill_name = str(kwargs.get("skill_name") or "").strip()
51 + return Response(message=self._load(skill_name), break_loop=False)
52 + if method == "read_file":
53 + skill_name = str(kwargs.get("skill_name") or "").strip()
54 + file_path = str(kwargs.get("file_path") or "").strip()
55 + return Response(message=self._read_file(skill_name, file_path), break_loop=False)
56 + if method == "execute_script":
57 + skill_name = str(kwargs.get("skill_name") or "").strip()
58 + script_path = str(kwargs.get("script_path") or "").strip()
59 + script_args = kwargs.get("script_args") or {}
60 + if not isinstance(script_args, dict):
61 + script_args = {}
62 + # arg_style: "positional" (default), "named" (--key value), or "env" (env vars only)
63 + arg_style = str(kwargs.get("arg_style") or "positional").strip().lower()
64 + return await self._execute_script(skill_name, script_path, script_args, arg_style)
65 +
66 + return Response(
67 + message=(
68 + "Error: missing/invalid 'method'. Supported methods: "
69 + "list, search, load, read_file, execute_script."
70 + ),
71 + break_loop=False,
72 + )
73 + except Exception as e: # keep tool robust; return error instead of crashing loop
74 + return Response(message=f"Error in skills_tool: {e}", break_loop=False)
75 +
76 + def _get_active_framework_id(self) -> str | None:
77 + """Get the active framework ID from the agent's context."""
78 + try:
79 + framework = frameworks.get_active_framework(self.agent.context)
80 + return framework.id if framework else None
81 + except Exception:
82 + return None
83 +
84 + def _list(self) -> str:
85 + framework_id = self._get_active_framework_id()
86 + skills = skills_helper.list_skills(include_content=False, dedupe=True, framework_id=framework_id)
87 + if not skills:
88 + return "No skills found. Expected SKILL.md files under: skills/{custom,builtin,shared}."
89 +
90 + # Stable output: sort by name
91 + skills_sorted = sorted(skills, key=lambda s: (s.name.lower(), s.source))
92 +
93 + lines: List[str] = []
94 + lines.append(f"Available skills ({len(skills_sorted)}):")
95 + for s in skills_sorted:
96 + tags = f" tags={','.join(s.tags)}" if s.tags else ""
97 + ver = f" v{s.version}" if s.version else ""
98 + desc = (s.description or "").strip()
99 + if len(desc) > 200:
100 + desc = desc[:200].rstrip() + "…"
101 + lines.append(f"- {s.name}{ver} [{s.source}]{tags}: {desc}")
102 + lines.append("")
103 + lines.append("Tip: use skills_tool method=search or method=load for details.")
104 + return "\n".join(lines)
105 +
106 + def _search(self, query: str) -> str:
107 + if not query:
108 + return "Error: 'query' is required for method=search."
109 +
110 + framework_id = self._get_active_framework_id()
111 + results = skills_helper.search_skills(query, limit=25, framework_id=framework_id)
112 + if not results:
113 + return f"No skills matched query: {query!r}"
114 +
115 + lines: List[str] = []
116 + lines.append(f"Skills matching {query!r} ({len(results)}):")
117 + for s in results:
118 + desc = (s.description or "").strip()
119 + if len(desc) > 200:
120 + desc = desc[:200].rstrip() + "…"
121 + lines.append(f"- {s.name} [{s.source}]: {desc}")
122 + lines.append("")
123 + lines.append("Tip: use skills_tool method=load skill_name=<name> to load full instructions.")
124 + return "\n".join(lines)
125 +
126 + def _load(self, skill_name: str) -> str:
127 + if not skill_name:
128 + return "Error: 'skill_name' is required for method=load."
129 +
130 + framework_id = self._get_active_framework_id()
131 + skill = skills_helper.find_skill(skill_name, include_content=True, framework_id=framework_id)
132 + if not skill:
133 + return f"Error: skill not found: {skill_name!r}. Try skills_tool method=list or method=search."
134 +
135 + # Enumerate files under the skill directory for progressive disclosure
136 + referenced_files = self._list_skill_files(skill.path, max_files=80)
137 + rel_skill_dir = Path(files.deabsolute_path(str(skill.path)))
138 +
139 + lines: List[str] = []
140 + lines.append(f"Skill: {skill.name}")
141 + lines.append(f"Source: {skill.source}")
142 + lines.append(f"Path: {rel_skill_dir}")
143 + if skill.version:
144 + lines.append(f"Version: {skill.version}")
145 + if skill.author:
146 + lines.append(f"Author: {skill.author}")
147 + if skill.license:
148 + lines.append(f"License: {skill.license}")
149 + if skill.tags:
150 + lines.append(f"Tags: {', '.join(skill.tags)}")
151 + if skill.allowed_tools:
152 + lines.append(f"Allowed tools: {', '.join(skill.allowed_tools)}")
153 + if skill.triggers:
154 + lines.append(f"Triggers: {', '.join(skill.triggers)}")
155 +
156 + lines.append("")
157 + if skill.description:
158 + lines.append("Description:")
159 + lines.append(skill.description.strip())
160 + lines.append("")
161 +
162 + lines.append("Content (SKILL.md body):")
163 + lines.append(skill.content.strip() or "(empty)")
164 + lines.append("")
165 +
166 + if referenced_files:
167 + lines.append("Files in skill directory (use skills_tool method=read_file to open):")
168 + for p in referenced_files:
169 + lines.append(f"- {p}")
170 + else:
171 + lines.append("No additional files found in skill directory.")
172 +
173 + return "\n".join(lines)
174 +
175 + def _read_file(self, skill_name: str, file_path: str) -> str:
176 + if not skill_name:
177 + return "Error: 'skill_name' is required for method=read_file."
178 + if not file_path:
179 + return "Error: 'file_path' is required for method=read_file."
180 +
181 + framework_id = self._get_active_framework_id()
182 + skill = skills_helper.find_skill(skill_name, include_content=False, framework_id=framework_id)
183 + if not skill:
184 + return f"Error: skill not found: {skill_name!r}."
185 +
186 + try:
187 + target = skills_helper.safe_path_within_dir(skill.path, file_path)
188 + except Exception as e:
189 + return f"Error: invalid file_path: {e}"
190 +
191 + if not target.exists() or not target.is_file():
192 + return f"Error: file not found: {file_path!r} (within skill {skill.name})"
193 +
194 + # Basic binary guard: if null byte present, do not dump
195 + content = target.read_bytes()
196 + if b"\x00" in content[:4096]:
197 + return f"Error: file appears to be binary; refusing to print raw bytes ({file_path})."
198 +
199 + text = content.decode("utf-8", errors="replace")
200 + return f"File: {file_path}\n\n{text}"
201 +
202 + async def _execute_script(
203 + self, skill_name: str, script_path: str, script_args: Dict[str, Any],
204 + arg_style: str = "positional"
205 + ) -> Response:
206 + if not skill_name:
207 + return Response(message="Error: 'skill_name' is required for method=execute_script.", break_loop=False)
208 + if not script_path:
209 + return Response(message="Error: 'script_path' is required for method=execute_script.", break_loop=False)
210 +
211 + framework_id = self._get_active_framework_id()
212 + skill = skills_helper.find_skill(skill_name, include_content=False, framework_id=framework_id)
213 + if not skill:
214 + return Response(message=f"Error: skill not found: {skill_name!r}.", break_loop=False)
215 +
216 + try:
217 + script_abs = skills_helper.safe_path_within_dir(skill.path, script_path)
218 + except Exception as e:
219 + return Response(message=f"Error: invalid script_path: {e}", break_loop=False)
220 +
221 + if not script_abs.exists() or not script_abs.is_file():
222 + return Response(message=f"Error: script not found: {script_path!r} (within skill {skill.name})", break_loop=False)
223 +
224 + ext = script_abs.suffix.lower()
225 + runtime: str
226 + code: str
227 +
228 + # Use /a0 paths for remote (SSH) execution inside the container; use local absolute paths otherwise.
229 + if self.agent.config.code_exec_ssh_enabled:
230 + script_runtime_path = files.normalize_a0_path(str(script_abs))
231 + script_runtime_dir = files.normalize_a0_path(str(script_abs.parent))
232 + else:
233 + script_runtime_path = str(script_abs)
234 + script_runtime_dir = str(script_abs.parent)
235 +
236 + # Build environment variables (SKILL_ARG_*) - always set as fallback
237 + env_vars: Dict[str, str] = {}
238 + for k, v in (script_args or {}).items():
239 + env_key = f"SKILL_ARG_{re.sub(r'[^A-Za-z0-9_]', '_', str(k).upper())}"
240 + env_vars[env_key] = str(v)
241 +
242 + # Build CLI args based on arg_style:
243 + # - "positional": ['value1', 'value2'] - for scripts using sys.argv[1], sys.argv[2]
244 + # - "named": ['--key1', 'value1', '--key2', 'value2'] - for argparse/click scripts
245 + # - "env": [] - only use environment variables, no CLI args
246 + cli_args: List[str] = []
247 + if arg_style == "positional":
248 + cli_args = [str(v) for v in (script_args or {}).values()]
249 + elif arg_style == "named":
250 + for k, v in (script_args or {}).items():
251 + cli_args.append(f"--{k}")
252 + cli_args.append(str(v))
253 + # "env" style: cli_args stays empty, only env vars are used
254 +
255 + if ext == ".py":
256 + runtime = "python"
257 + # Set env vars (always available as fallback)
258 + env_lines = [f"os.environ[{json.dumps(k)}] = {json.dumps(v)}" for k, v in env_vars.items()]
259 + env_setup = "\n".join(env_lines) if env_lines else "pass"
260 + # Set sys.argv: ['script.py', ...cli_args]
261 + argv_list = [script_runtime_path] + cli_args
262 + argv_setup = f"sys.argv = {json.dumps(argv_list)}"
263 + code = (
264 + "import os, sys, runpy\n"
265 + f"os.chdir({json.dumps(script_runtime_dir)})\n"
266 + f"{env_setup}\n"
267 + f"{argv_setup}\n"
268 + f"runpy.run_path({json.dumps(script_runtime_path)}, run_name='__main__')\n"
269 + )
270 + elif ext == ".js":
271 + runtime = "nodejs"
272 + # Set process.env (always available as fallback)
273 + env_lines = [f"process.env[{json.dumps(k)}] = {json.dumps(v)};" for k, v in env_vars.items()]
274 + env_setup = "\n".join(env_lines) if env_lines else ""
275 + # Node.js argv: ['node', 'script.js', ...cli_args]
276 + argv_list = ["node", script_runtime_path] + cli_args
277 + code = (
278 + f"process.chdir({json.dumps(script_runtime_dir)});\n"
279 + f"{env_setup}\n"
280 + f"process.argv = {json.dumps(argv_list)};\n"
281 + f"require({json.dumps(script_runtime_path)});\n"
282 + )
283 + elif ext == ".sh":
284 + runtime = "terminal"
285 + # Environment variables (always available as fallback)
286 + env_parts = [f"{k}={shlex.quote(v)}" for k, v in env_vars.items()]
287 + env_prefix = " ".join(env_parts)
288 + # Pass CLI args to script
289 + cli_args_str = " ".join(shlex.quote(a) for a in cli_args)
290 + cd_cmd = f"cd {shlex.quote(script_runtime_dir)}"
291 + run_cmd = f"bash {shlex.quote(script_runtime_path)}"
292 + if cli_args_str:
293 + run_cmd = f"{run_cmd} {cli_args_str}"
294 + if env_prefix:
295 + code = f"{cd_cmd} && {env_prefix} {run_cmd}"
296 + else:
297 + code = f"{cd_cmd} && {run_cmd}"
298 + else:
299 + return Response(
300 + message=f"Error: unsupported script type {ext!r}. Supported: .py, .js, .sh",
301 + break_loop=False,
302 + )
303 +
304 + # Delegate actual execution to code_execution_tool (sandboxed)
305 + from python.tools.code_execution_tool import CodeExecution
306 +
307 + cet = CodeExecution(
308 + agent=self.agent,
309 + name="code_execution_tool",
310 + method=None,
311 + args={
312 + "runtime": runtime,
313 + "code": code,
314 + "session": int(self.args.get("session", 0) or 0),
315 + },
316 + message=self.message,
317 + loop_data=self.loop_data,
318 + )
319 +
320 + # Must call before_execution to initialize self.log before execute()
321 + await cet.before_execution(**cet.args)
322 + resp = await cet.execute(**cet.args)
323 + # Wrap result to make it clear it was a skill script
324 + wrapped = (
325 + f"Executed script: {skill.name}/{script_path}\n"
326 + f"Runtime: {runtime}\n\n"
327 + f"{resp.message}"
328 + )
329 + return Response(message=wrapped, break_loop=False)
330 +
331 + def _list_skill_files(self, skill_dir: Path, *, max_files: int = 80) -> List[str]:
332 + if not skill_dir.exists():
333 + return []
334 +
335 + results: List[str] = []
336 +
337 + preferred_dirs = ["scripts", "references", "assets", "templates", "docs"]
338 +
339 + # 1) Root-level files (excluding SKILL.md)
340 + try:
341 + for p in sorted(skill_dir.iterdir(), key=lambda x: x.name):
342 + if len(results) >= max_files:
343 + return results
344 + if p.name.startswith("."):
345 + continue
346 + if p.is_file():
347 + if p.name == "SKILL.md":
348 + continue
349 + results.append(p.name)
350 + except Exception:
351 + pass
352 +
353 + # 2) Preferred optional directories (one level deep)
354 + for dname in preferred_dirs:
355 + dpath = skill_dir / dname
356 + if not dpath.exists() or not dpath.is_dir():
357 + continue
358 + try:
359 + for p in sorted(dpath.iterdir(), key=lambda x: x.name):
360 + if len(results) >= max_files:
361 + return results
362 + if p.name.startswith("."):
363 + continue
364 + if p.is_file():
365 + results.append(f"{dname}/{p.name}")
366 + elif p.is_dir():
367 + # Show one nested level (common in assets/templates/*)
368 + nested_added = False
369 + try:
370 + for sub in sorted(p.iterdir(), key=lambda x: x.name):
371 + if sub.name.startswith("."):
372 + continue
373 + if sub.is_file():
374 + results.append(f"{dname}/{p.name}/{sub.name}")
375 + nested_added = True
376 + break
377 + except Exception:
378 + pass
379 + if not nested_added:
380 + results.append(f"{dname}/{p.name}/")
381 + except Exception:
382 + continue
383 +
384 + # 3) Other directories (one level deep)
385 + try:
386 + for p in sorted(skill_dir.iterdir(), key=lambda x: x.name):
387 + if len(results) >= max_files:
388 + return results
389 + if p.name.startswith(".") or p.name in preferred_dirs:
390 + continue
391 + if p.is_dir():
392 + for sub in sorted(p.iterdir(), key=lambda x: x.name):
393 + if len(results) >= max_files:
394 + return results
395 + if sub.name.startswith("."):
396 + continue
397 + if sub.is_file():
398 + results.append(f"{p.name}/{sub.name}")
399 + except Exception:
400 + pass
401 +
402 + return results
403 +
404 +
requirements.txt
+4 -1
@@ -47,4 +47,7 @@ html2text>=2024.2.26
47 beautifulsoup4>=4.12.3
48 boto3>=1.35.0
49 exchangelib>=5.4.3
50 -pywinpty==3.0.2; sys_platform == "win32"
\ No newline at end of file
50 +pywinpty==3.0.2; sys_platform == "win32"
51 +seaborn==0.13.2
52 +pydantic>=2.0,<2.12
53 +pydantic-settings>=2.0,<2.12
skills/builtin/api_development/SKILL.md new
+385
@@ -0,0 +1,385 @@
1 +---
2 +name: "api_development"
3 +description: "Best practices for designing and implementing RESTful and GraphQL APIs. Use when building, designing, or reviewing APIs."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["api", "rest", "graphql", "design", "backend", "web"]
7 +trigger_patterns:
8 + - "api"
9 + - "endpoint"
10 + - "rest"
11 + - "graphql"
12 + - "http"
13 +---
14 +
15 +# API Development Skill
16 +
17 +Best practices for designing, implementing, and documenting APIs.
18 +
19 +## RESTful API Design
20 +
21 +### URL Structure
22 +
23 +```
24 +https://api.example.com/v1/resources/{id}/subresources
25 +```
26 +
27 +**Guidelines:**
28 +- Use nouns, not verbs: `/users` not `/getUsers`
29 +- Use plural nouns: `/users` not `/user`
30 +- Use kebab-case: `/user-profiles` not `/userProfiles`
31 +- Nest resources logically: `/users/{id}/orders`
32 +- Version your API: `/v1/`, `/v2/`
33 +
34 +### HTTP Methods
35 +
36 +| Method | Purpose | Example |
37 +|--------|---------|---------|
38 +| `GET` | Retrieve resource(s) | `GET /users/123` |
39 +| `POST` | Create resource | `POST /users` |
40 +| `PUT` | Replace resource | `PUT /users/123` |
41 +| `PATCH` | Partial update | `PATCH /users/123` |
42 +| `DELETE` | Remove resource | `DELETE /users/123` |
43 +
44 +### Status Codes
45 +
46 +| Code | Meaning | When to Use |
47 +|------|---------|-------------|
48 +| `200 OK` | Success | GET, PUT, PATCH success |
49 +| `201 Created` | Resource created | POST success |
50 +| `204 No Content` | Success, no body | DELETE success |
51 +| `400 Bad Request` | Invalid input | Validation failed |
52 +| `401 Unauthorized` | Not authenticated | Missing/invalid token |
53 +| `403 Forbidden` | Not authorized | Insufficient permissions |
54 +| `404 Not Found` | Resource not found | ID doesn't exist |
55 +| `409 Conflict` | Resource conflict | Duplicate entry |
56 +| `422 Unprocessable` | Semantic error | Valid syntax, invalid data |
57 +| `429 Too Many` | Rate limited | Exceeded request limit |
58 +| `500 Server Error` | Internal error | Unexpected failure |
59 +
60 +### Request/Response Format
61 +
62 +**Request:**
63 +```http
64 +POST /api/v1/users HTTP/1.1
65 +Content-Type: application/json
66 +Authorization: Bearer <token>
67 +
68 +{
69 + "email": "user@example.com",
70 + "name": "John Doe",
71 + "role": "user"
72 +}
73 +```
74 +
75 +**Success Response:**
76 +```json
77 +{
78 + "data": {
79 + "id": "123",
80 + "email": "user@example.com",
81 + "name": "John Doe",
82 + "role": "user",
83 + "created_at": "2024-01-15T10:30:00Z"
84 + },
85 + "meta": {
86 + "request_id": "abc-123"
87 + }
88 +}
89 +```
90 +
91 +**Error Response:**
92 +```json
93 +{
94 + "error": {
95 + "code": "VALIDATION_ERROR",
96 + "message": "Invalid input data",
97 + "details": [
98 + {
99 + "field": "email",
100 + "message": "Invalid email format"
101 + }
102 + ]
103 + },
104 + "meta": {
105 + "request_id": "abc-123"
106 + }
107 +}
108 +```
109 +
110 +### Pagination
111 +
112 +**Request:**
113 +```http
114 +GET /api/v1/users?page=2&per_page=20
115 +```
116 +
117 +**Response:**
118 +```json
119 +{
120 + "data": [...],
121 + "meta": {
122 + "current_page": 2,
123 + "per_page": 20,
124 + "total_pages": 10,
125 + "total_count": 195
126 + },
127 + "links": {
128 + "first": "/api/v1/users?page=1&per_page=20",
129 + "prev": "/api/v1/users?page=1&per_page=20",
130 + "next": "/api/v1/users?page=3&per_page=20",
131 + "last": "/api/v1/users?page=10&per_page=20"
132 + }
133 +}
134 +```
135 +
136 +### Filtering & Sorting
137 +
138 +```http
139 +# Filtering
140 +GET /api/v1/users?status=active&role=admin
141 +
142 +# Sorting
143 +GET /api/v1/users?sort=created_at&order=desc
144 +
145 +# Multiple sort fields
146 +GET /api/v1/users?sort=-created_at,name
147 +```
148 +
149 +### Field Selection
150 +
151 +```http
152 +GET /api/v1/users?fields=id,name,email
153 +```
154 +
155 +## Authentication
156 +
157 +### JWT (JSON Web Token)
158 +
159 +```javascript
160 +// Token structure
161 +{
162 + "header": {
163 + "alg": "HS256",
164 + "typ": "JWT"
165 + },
166 + "payload": {
167 + "sub": "user_123",
168 + "email": "user@example.com",
169 + "role": "admin",
170 + "iat": 1516239022,
171 + "exp": 1516242622
172 + },
173 + "signature": "..."
174 +}
175 +```
176 +
177 +**Implementation:**
178 +
179 +```python
180 +# Python example with PyJWT
181 +import jwt
182 +from datetime import datetime, timedelta
183 +
184 +def create_token(user_id: str, secret: str) -> str:
185 + payload = {
186 + "sub": user_id,
187 + "iat": datetime.utcnow(),
188 + "exp": datetime.utcnow() + timedelta(hours=1)
189 + }
190 + return jwt.encode(payload, secret, algorithm="HS256")
191 +
192 +def verify_token(token: str, secret: str) -> dict:
193 + try:
194 + return jwt.decode(token, secret, algorithms=["HS256"])
195 + except jwt.ExpiredSignatureError:
196 + raise AuthError("Token expired")
197 + except jwt.InvalidTokenError:
198 + raise AuthError("Invalid token")
199 +```
200 +
201 +### API Keys
202 +
203 +```http
204 +# Header
205 +Authorization: Api-Key <key>
206 +
207 +# Query param (less secure)
208 +GET /api/v1/resource?api_key=<key>
209 +```
210 +
211 +## Rate Limiting
212 +
213 +**Headers:**
214 +```http
215 +X-RateLimit-Limit: 1000
216 +X-RateLimit-Remaining: 999
217 +X-RateLimit-Reset: 1609459200
218 +```
219 +
220 +**Implementation:**
221 +```python
222 +from functools import wraps
223 +import time
224 +
225 +class RateLimiter:
226 + def __init__(self, max_requests: int, window_seconds: int):
227 + self.max_requests = max_requests
228 + self.window = window_seconds
229 + self.requests = {}
230 +
231 + def is_allowed(self, client_id: str) -> bool:
232 + now = time.time()
233 + window_start = now - self.window
234 +
235 + # Clean old requests
236 + self.requests[client_id] = [
237 + t for t in self.requests.get(client_id, [])
238 + if t > window_start
239 + ]
240 +
241 + if len(self.requests[client_id]) >= self.max_requests:
242 + return False
243 +
244 + self.requests[client_id].append(now)
245 + return True
246 +```
247 +
248 +## Input Validation
249 +
250 +```python
251 +from pydantic import BaseModel, EmailStr, validator
252 +
253 +class CreateUserRequest(BaseModel):
254 + email: EmailStr
255 + name: str
256 + age: int
257 +
258 + @validator('name')
259 + def name_not_empty(cls, v):
260 + if not v.strip():
261 + raise ValueError('Name cannot be empty')
262 + return v.strip()
263 +
264 + @validator('age')
265 + def age_valid(cls, v):
266 + if v < 0 or v > 150:
267 + raise ValueError('Age must be between 0 and 150')
268 + return v
269 +```
270 +
271 +## Error Handling
272 +
273 +```python
274 +class APIError(Exception):
275 + def __init__(self, code: str, message: str, status_code: int = 400):
276 + self.code = code
277 + self.message = message
278 + self.status_code = status_code
279 +
280 +@app.errorhandler(APIError)
281 +def handle_api_error(error):
282 + return jsonify({
283 + "error": {
284 + "code": error.code,
285 + "message": error.message
286 + }
287 + }), error.status_code
288 +
289 +# Usage
290 +raise APIError("USER_NOT_FOUND", "User with ID 123 not found", 404)
291 +```
292 +
293 +## API Documentation
294 +
295 +### OpenAPI/Swagger Example
296 +
297 +```yaml
298 +openapi: 3.0.0
299 +info:
300 + title: User API
301 + version: 1.0.0
302 +
303 +paths:
304 + /users:
305 + get:
306 + summary: List all users
307 + parameters:
308 + - name: page
309 + in: query
310 + schema:
311 + type: integer
312 + default: 1
313 + responses:
314 + '200':
315 + description: Successful response
316 + content:
317 + application/json:
318 + schema:
319 + $ref: '#/components/schemas/UserList'
320 + post:
321 + summary: Create a user
322 + requestBody:
323 + required: true
324 + content:
325 + application/json:
326 + schema:
327 + $ref: '#/components/schemas/CreateUser'
328 + responses:
329 + '201':
330 + description: User created
331 +
332 +components:
333 + schemas:
334 + User:
335 + type: object
336 + properties:
337 + id:
338 + type: string
339 + email:
340 + type: string
341 + name:
342 + type: string
343 +```
344 +
345 +## Security Checklist
346 +
347 +```markdown
348 +- [ ] Use HTTPS only
349 +- [ ] Validate all input
350 +- [ ] Sanitize output
351 +- [ ] Use parameterized queries
352 +- [ ] Implement rate limiting
353 +- [ ] Use secure headers (CORS, CSP)
354 +- [ ] Don't expose internal errors
355 +- [ ] Log security events
356 +- [ ] Rotate secrets regularly
357 +- [ ] Version your API
358 +```
359 +
360 +## Performance Tips
361 +
362 +1. **Use caching headers**
363 + ```http
364 + Cache-Control: max-age=3600
365 + ETag: "abc123"
366 + ```
367 +
368 +2. **Implement compression**
369 + ```http
370 + Accept-Encoding: gzip
371 + Content-Encoding: gzip
372 + ```
373 +
374 +3. **Use pagination** for large datasets
375 +
376 +4. **Implement field selection** to reduce payload
377 +
378 +5. **Consider async processing** for long operations
379 + ```json
380 + {
381 + "status": "processing",
382 + "job_id": "job_123",
383 + "check_url": "/api/v1/jobs/job_123"
384 + }
385 + ```
skills/builtin/brainstorming/SKILL.md new
+123
@@ -0,0 +1,123 @@
1 +---
2 +name: "brainstorming"
3 +description: "Structured brainstorming and requirements exploration before implementation. Use this BEFORE any creative work like building features, creating components, or adding functionality."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["planning", "design", "requirements", "architecture", "creative"]
7 +trigger_patterns:
8 + - "create"
9 + - "build"
10 + - "implement"
11 + - "add feature"
12 + - "design"
13 + - "develop"
14 +---
15 +
16 +# Brainstorming Skill
17 +
18 +**CRITICAL**: Use this skill BEFORE writing any implementation code. This ensures proper requirements exploration and design alignment.
19 +
20 +## When to Use
21 +
22 +Activate this skill when you encounter:
23 +- "Create a new feature..."
24 +- "Build a component that..."
25 +- "Implement X functionality..."
26 +- "Add support for..."
27 +- "Design a system that..."
28 +
29 +## The Brainstorming Process
30 +
31 +### Phase 1: Understanding Intent (5 questions max)
32 +
33 +Ask clarifying questions to understand:
34 +
35 +1. **Goal Clarity**: What specific outcome does the user want?
36 +2. **Context**: What existing code/systems does this interact with?
37 +3. **Constraints**: Are there performance, security, or compatibility requirements?
38 +4. **Edge Cases**: What happens in failure scenarios?
39 +5. **Success Criteria**: How will we know it's working correctly?
40 +
41 +### Phase 2: Design Options
42 +
43 +Present 2-3 implementation approaches with trade-offs:
44 +
45 +```markdown
46 +## Option A: [Name]
47 +**Approach**: Brief description
48 +**Pros**: List benefits
49 +**Cons**: List drawbacks
50 +**Best for**: When to choose this
51 +
52 +## Option B: [Name]
53 +**Approach**: Brief description
54 +**Pros**: List benefits
55 +**Cons**: List drawbacks
56 +**Best for**: When to choose this
57 +```
58 +
59 +### Phase 3: Technical Specification
60 +
61 +Once approach is chosen, document:
62 +
63 +1. **Files to Create/Modify**: List with brief description
64 +2. **Dependencies**: External packages or internal modules needed
65 +3. **Data Flow**: How data moves through the system
66 +4. **API Contracts**: Input/output specifications
67 +5. **Test Strategy**: How this will be tested
68 +
69 +### Phase 4: Implementation Plan
70 +
71 +Break down into ordered tasks:
72 +
73 +```markdown
74 +## Implementation Tasks
75 +1. [ ] Task 1 - Description
76 +2. [ ] Task 2 - Description (depends on 1)
77 +3. [ ] Task 3 - Description
78 +4. [ ] Task 4 - Integration testing
79 +```
80 +
81 +## Anti-Patterns to Avoid
82 +
83 +- **Jumping to Code**: Never start coding without understanding requirements
84 +- **Single Solution Bias**: Always consider at least 2 approaches
85 +- **Ignoring Context**: Always examine existing patterns in the codebase
86 +- **Over-Engineering**: Keep solutions proportional to the problem
87 +- **Under-Specifying**: Be specific enough that implementation is clear
88 +
89 +## Example Session
90 +
91 +**User**: "Add dark mode to the application"
92 +
93 +**Agent Response**:
94 +> Before implementing dark mode, let me understand your requirements:
95 +>
96 +> 1. **Scope**: Should this apply to the entire application or specific sections?
97 +> 2. **Toggle**: How should users switch modes? (button, system preference, both?)
98 +> 3. **Persistence**: Should the preference be saved across sessions?
99 +> 4. **Theming Approach**: Do you have existing CSS variables, or should we create a new theme system?
100 +> 5. **Transition**: Should there be smooth transitions when switching modes?
101 +
102 +## Output Format
103 +
104 +After brainstorming, provide a clear summary:
105 +
106 +```markdown
107 +## Summary: [Feature Name]
108 +
109 +### Chosen Approach
110 +[Brief description of selected approach]
111 +
112 +### Key Decisions
113 +- Decision 1: Rationale
114 +- Decision 2: Rationale
115 +
116 +### Implementation Tasks
117 +1. Task 1
118 +2. Task 2
119 +3. Task 3
120 +
121 +### Ready to Implement
122 +Confirm with user before proceeding to implementation.
123 +```
skills/builtin/code_review/SKILL.md new
+272
@@ -0,0 +1,272 @@
1 +---
2 +name: "code_review"
3 +description: "Comprehensive code review skill for analyzing code quality, identifying issues, and suggesting improvements. Use when reviewing PRs or checking code quality."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["review", "quality", "security", "best-practices", "pr"]
7 +trigger_patterns:
8 + - "review"
9 + - "check code"
10 + - "code quality"
11 + - "pull request"
12 + - "PR"
13 +---
14 +
15 +# Code Review Skill
16 +
17 +**Goal**: Provide actionable, constructive feedback that improves code quality.
18 +
19 +## Review Categories
20 +
21 +### 1. Correctness
22 +- Does the code do what it's supposed to?
23 +- Are there logic errors?
24 +- Are edge cases handled?
25 +
26 +### 2. Security
27 +- Input validation
28 +- Authentication/authorization
29 +- SQL injection, XSS prevention
30 +- Secrets exposure
31 +
32 +### 3. Performance
33 +- Algorithmic complexity
34 +- Database query efficiency
35 +- Memory usage
36 +- Caching opportunities
37 +
38 +### 4. Maintainability
39 +- Code readability
40 +- Naming conventions
41 +- Documentation
42 +- Single responsibility
43 +
44 +### 5. Testing
45 +- Test coverage
46 +- Test quality
47 +- Edge case testing
48 +
49 +## Review Process
50 +
51 +### Phase 1: Understand Context
52 +
53 +Before reviewing:
54 +1. What is the purpose of this change?
55 +2. What problem is it solving?
56 +3. What are the requirements?
57 +4. Are there related changes elsewhere?
58 +
59 +### Phase 2: High-Level Review
60 +
61 +Look at:
62 +1. **Architecture**: Does the approach make sense?
63 +2. **Design patterns**: Are appropriate patterns used?
64 +3. **File organization**: Is code in the right place?
65 +4. **Dependencies**: Are new dependencies justified?
66 +
67 +### Phase 3: Line-by-Line Review
68 +
69 +For each file:
70 +1. Read through understanding intent
71 +2. Check for issues in each category
72 +3. Note both problems and good practices
73 +
74 +### Phase 4: Provide Feedback
75 +
76 +Structure feedback clearly:
77 +
78 +```markdown
79 +## Review Summary
80 +
81 +### Must Fix (Blockers)
82 +- [ ] **Security**: SQL injection vulnerability in line 42
83 +- [ ] **Bug**: Off-by-one error in loop at line 78
84 +
85 +### Should Fix (Important)
86 +- [ ] **Performance**: N+1 query problem in user loader
87 +- [ ] **Maintainability**: Function too long (150+ lines)
88 +
89 +### Consider (Suggestions)
90 +- [ ] **Style**: Variable naming could be more descriptive
91 +- [ ] **Testing**: Add test for empty input case
92 +
93 +### Positives
94 +- Good use of error handling
95 +- Clear separation of concerns
96 +```
97 +
98 +## Code Smells to Watch For
99 +
100 +### Complexity
101 +- **Long methods**: > 20-30 lines
102 +- **Deep nesting**: > 3-4 levels
103 +- **Too many parameters**: > 4-5 params
104 +- **God classes**: Classes doing too much
105 +
106 +### Duplication
107 +- Copy-pasted code blocks
108 +- Similar logic in multiple places
109 +- Magic numbers repeated
110 +
111 +### Coupling
112 +- Tight coupling between modules
113 +- Circular dependencies
114 +- Inappropriate intimacy
115 +
116 +### Naming
117 +- Single-letter variables (except loops)
118 +- Misleading names
119 +- Inconsistent conventions
120 +
121 +## Security Checklist
122 +
123 +```markdown
124 +- [ ] Input validation on all user input
125 +- [ ] Parameterized queries (no string concatenation for SQL)
126 +- [ ] Output encoding (prevent XSS)
127 +- [ ] Authentication checked on protected routes
128 +- [ ] Authorization checked for resource access
129 +- [ ] Sensitive data not logged
130 +- [ ] Secrets not hardcoded
131 +- [ ] HTTPS enforced for sensitive data
132 +- [ ] Rate limiting on authentication endpoints
133 +- [ ] CORS properly configured
134 +```
135 +
136 +## Feedback Guidelines
137 +
138 +### Be Constructive
139 +```markdown
140 +# Bad
141 +"This code is terrible"
142 +
143 +# Good
144 +"This approach works, but consider using X for better
145 +performance because [specific reason]"
146 +```
147 +
148 +### Be Specific
149 +```markdown
150 +# Bad
151 +"Fix the naming"
152 +
153 +# Good
154 +"Rename `d` to `document_count` for clarity.
155 +Single-letter variables make the code harder to understand"
156 +```
157 +
158 +### Explain Why
159 +```markdown
160 +# Bad
161 +"Don't use global variables"
162 +
163 +# Good
164 +"Global variables can cause issues because:
165 +1. They make testing difficult
166 +2. They create hidden dependencies
167 +3. They can be modified from anywhere
168 +
169 +Consider passing this as a parameter instead."
170 +```
171 +
172 +### Offer Solutions
173 +```markdown
174 +# Instead of just:
175 +"This is inefficient"
176 +
177 +# Provide:
178 +"This is O(n²) due to the nested loops. Consider using
179 +a Set for the lookup to achieve O(n):
180 +
181 +```python
182 +seen = set(processed_ids)
183 +for item in items:
184 + if item.id in seen: # O(1) lookup
185 + continue
186 +```"
187 +```
188 +
189 +## Review Checklist Template
190 +
191 +```markdown
192 +## Code Review: [PR Title]
193 +
194 +### Context Understanding
195 +- [ ] I understand the purpose of this change
196 +- [ ] I've reviewed related documentation/tickets
197 +
198 +### Correctness
199 +- [ ] Logic is correct
200 +- [ ] Edge cases handled
201 +- [ ] Error handling appropriate
202 +
203 +### Security
204 +- [ ] No SQL injection vulnerabilities
205 +- [ ] No XSS vulnerabilities
206 +- [ ] Authentication/authorization correct
207 +- [ ] No secrets exposed
208 +
209 +### Performance
210 +- [ ] No obvious performance issues
211 +- [ ] Database queries efficient
212 +- [ ] No memory leaks
213 +
214 +### Maintainability
215 +- [ ] Code is readable
216 +- [ ] Functions are focused
217 +- [ ] Good naming
218 +- [ ] Appropriate comments
219 +
220 +### Testing
221 +- [ ] Adequate test coverage
222 +- [ ] Tests are meaningful
223 +- [ ] Edge cases tested
224 +
225 +### Verdict
226 +- [ ] Approved
227 +- [ ] Approved with comments
228 +- [ ] Request changes
229 +```
230 +
231 +## Example Review
232 +
233 +```markdown
234 +## Review: Add user registration endpoint
235 +
236 +### Summary
237 +Generally good implementation! A few security concerns to address.
238 +
239 +### Must Fix
240 +1. **Security (line 45)**: Password stored in plain text
241 + ```python
242 + # Current
243 + user.password = request.password
244 +
245 + # Fix
246 + user.password_hash = hash_password(request.password)
247 + ```
248 +
249 +2. **Validation (line 38)**: Email not validated
250 + Add email format validation before saving
251 +
252 +### Should Fix
253 +1. **Error Handling (line 52)**: Bare except catches too much
254 + ```python
255 + # Current
256 + except:
257 + return error_response()
258 +
259 + # Fix
260 + except ValidationError as e:
261 + return error_response(str(e))
262 + ```
263 +
264 +### Consider
265 +1. Add rate limiting to prevent spam registrations
266 +2. Send confirmation email async to improve response time
267 +
268 +### Positives
269 +- Good use of transactions
270 +- Clear API response structure
271 +- Comprehensive logging
272 +```
skills/builtin/create_skill/SKILL.md new
+298
@@ -0,0 +1,298 @@
1 +---
2 +name: "create_skill"
3 +description: "Wizard for creating new Agent Zero skills. Guides users through creating well-structured SKILL.md files. Use when users want to create custom skills."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["meta", "wizard", "creation", "tutorial", "skills"]
7 +trigger_patterns:
8 + - "create skill"
9 + - "new skill"
10 + - "make skill"
11 + - "add skill"
12 + - "skill wizard"
13 +---
14 +
15 +# Create Skill Wizard
16 +
17 +This skill helps you create new Agent Zero skills that follow the SKILL.md standard.
18 +
19 +## Quick Start
20 +
21 +To create a new skill, I'll guide you through these steps:
22 +
23 +1. **Name & Purpose** - What should this skill do?
24 +2. **Trigger Patterns** - When should this skill activate?
25 +3. **Content Structure** - What instructions should the agent follow?
26 +4. **Supporting Files** - Any scripts or templates needed?
27 +
28 +## SKILL.md Format
29 +
30 +Every skill needs a `SKILL.md` file with YAML frontmatter:
31 +
32 +```yaml
33 +---
34 +name: "skill-name"
35 +description: "Clear description of what this skill does and when to use it"
36 +version: "1.0.0"
37 +author: "Your Name"
38 +tags: ["category1", "category2"]
39 +trigger_patterns:
40 + - "keyword1"
41 + - "phrase that triggers this"
42 +---
43 +
44 +# Skill Title
45 +
46 +Your skill instructions go here...
47 +```
48 +
49 +## Required Fields
50 +
51 +| Field | Description | Example |
52 +|-------|-------------|---------|
53 +| `name` | Unique identifier (lowercase, hyphens) | `"code-review"` |
54 +| `description` | When/why to use this skill | `"Review code for quality and security issues"` |
55 +
56 +## Optional Fields
57 +
58 +| Field | Description | Example |
59 +|-------|-------------|---------|
60 +| `version` | Semantic version | `"1.0.0"` |
61 +| `author` | Creator name | `"Jane Developer"` |
62 +| `tags` | Categorization keywords | `["review", "quality"]` |
63 +| `trigger_patterns` | Words/phrases that activate skill | `["review", "check code"]` |
64 +| `allowed_tools` | Tools this skill can use | `["code_execution", "web_search"]` |
65 +
66 +## Skill Directory Structure
67 +
68 +```
69 +skills/
70 +└── custom/
71 + └── my-skill/
72 + ├── SKILL.md # Required: Main skill file
73 + ├── scripts/ # Optional: Helper scripts
74 + │ ├── helper.py
75 + │ └── process.sh
76 + ├── templates/ # Optional: Templates
77 + │ └── output.md
78 + └── docs/ # Optional: Additional docs
79 + └── examples.md
80 +```
81 +
82 +## Writing Good Skill Instructions
83 +
84 +### Be Specific and Actionable
85 +
86 +```markdown
87 +# Good
88 +When reviewing code:
89 +1. Check for security vulnerabilities
90 +2. Verify error handling
91 +3. Assess test coverage
92 +
93 +# Bad
94 +Review the code and make it better.
95 +```
96 +
97 +### Include Examples
98 +
99 +```markdown
100 +## Example Usage
101 +
102 +**User**: "Review my Python function for issues"
103 +
104 +**Agent Response**:
105 +> I'll review your function using the code review checklist:
106 +>
107 +> 1. **Security**: No user input validation detected
108 +> 2. **Error Handling**: Missing try-catch for file operations
109 +> 3. **Testing**: Function is testable but no tests found
110 +```
111 +
112 +### Provide Checklists
113 +
114 +```markdown
115 +## Review Checklist
116 +- [ ] Input validation present
117 +- [ ] Error handling complete
118 +- [ ] Tests included
119 +- [ ] Documentation updated
120 +```
121 +
122 +## Creating Your Skill: Step by Step
123 +
124 +### Step 1: Define Purpose
125 +
126 +Answer these questions:
127 +- What problem does this skill solve?
128 +- When should the agent use it?
129 +- What's the expected output?
130 +
131 +### Step 2: Choose a Name
132 +
133 +- Use lowercase letters and hyphens
134 +- Be descriptive but concise
135 +- Examples: `code-review`, `data-analysis`, `deploy-helper`
136 +
137 +### Step 3: Write Trigger Patterns
138 +
139 +List words/phrases that should activate this skill:
140 +
141 +```yaml
142 +trigger_patterns:
143 + - "review"
144 + - "check code"
145 + - "code quality"
146 + - "pull request"
147 +```
148 +
149 +### Step 4: Structure Your Content
150 +
151 +Organize with clear sections:
152 +
153 +```markdown
154 +# Skill Title
155 +
156 +## When to Use
157 +Describe the trigger conditions
158 +
159 +## The Process
160 +Step-by-step instructions
161 +
162 +## Examples
163 +Show sample interactions
164 +
165 +## Tips
166 +Additional guidance
167 +```
168 +
169 +### Step 5: Add Supporting Files (Optional)
170 +
171 +If your skill needs scripts or templates:
172 +
173 +```bash
174 +# Create directory structure
175 +mkdir -p skills/custom/my-skill/{scripts,templates,docs}
176 +```
177 +
178 +## Example: Complete Skill
179 +
180 +```yaml
181 +---
182 +name: "python-optimizer"
183 +description: "Optimize Python code for performance and readability. Use when asked to improve or optimize Python code."
184 +version: "1.0.0"
185 +author: "Agent Zero Team"
186 +tags: ["python", "optimization", "performance"]
187 +trigger_patterns:
188 + - "optimize python"
189 + - "improve performance"
190 + - "make faster"
191 + - "python optimization"
192 +---
193 +
194 +# Python Optimizer
195 +
196 +## When to Use
197 +Activate when user asks to optimize, improve, or speed up Python code.
198 +
199 +## Optimization Process
200 +
201 +### Step 1: Profile First
202 +Before optimizing, understand where time is spent:
203 +```python
204 +import cProfile
205 +cProfile.run('your_function()')
206 +```
207 +
208 +### Step 2: Common Optimizations
209 +
210 +1. **Use List Comprehensions**
211 + ```python
212 + # Slow
213 + result = []
214 + for x in data:
215 + result.append(x * 2)
216 +
217 + # Fast
218 + result = [x * 2 for x in data]
219 + ```
220 +
221 +2. **Use Sets for Lookups**
222 + ```python
223 + # Slow: O(n)
224 + if item in large_list:
225 +
226 + # Fast: O(1)
227 + if item in large_set:
228 + ```
229 +
230 +3. **Use Generators for Large Data**
231 + ```python
232 + # Memory-heavy
233 + data = [process(x) for x in huge_list]
234 +
235 + # Memory-efficient
236 + data = (process(x) for x in huge_list)
237 + ```
238 +
239 +### Step 3: Verify Improvement
240 +Always measure before and after:
241 +```python
242 +import time
243 +start = time.perf_counter()
244 +# code to measure
245 +elapsed = time.perf_counter() - start
246 +print(f"Took {elapsed:.4f} seconds")
247 +```
248 +
249 +## Anti-Patterns to Avoid
250 +- Premature optimization
251 +- Optimizing without profiling
252 +- Sacrificing readability for tiny gains
253 +```
254 +
255 +## Skill Installation
256 +
257 +### Local Installation
258 +
259 +1. Create skill directory:
260 + ```bash
261 + mkdir -p skills/custom/my-skill
262 + ```
263 +
264 +2. Create SKILL.md:
265 + ```bash
266 + touch skills/custom/my-skill/SKILL.md
267 + ```
268 +
269 +3. Add content and save
270 +
271 +4. Skills are automatically loaded on next agent initialization
272 +
273 +### Sharing Skills
274 +
275 +To share skills with others:
276 +
277 +1. Create a GitHub repository
278 +2. Include the skill directory structure
279 +3. Add a README with installation instructions
280 +4. Users can copy to their `skills/custom/` directory
281 +
282 +## Testing Your Skill
283 +
284 +After creating a skill:
285 +
286 +1. Start a new conversation
287 +2. Use one of your trigger patterns
288 +3. Verify the agent follows your instructions
289 +4. Iterate and improve based on results
290 +
291 +## Need Help?
292 +
293 +Use this skill by saying:
294 +- "Help me create a new skill for [purpose]"
295 +- "I want to create a skill that [does something]"
296 +- "Create a skill wizard for [task]"
297 +
298 +I'll guide you through each step!
skills/builtin/database_design/SKILL.md new
+335
@@ -0,0 +1,335 @@
1 +---
2 +name: "database_design"
3 +description: "Database design, schema optimization, and query best practices. Use when designing schemas, optimizing queries, or working with databases."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["database", "sql", "schema", "optimization", "postgresql", "mysql"]
7 +trigger_patterns:
8 + - "database"
9 + - "schema"
10 + - "sql"
11 + - "query"
12 + - "table"
13 + - "index"
14 +---
15 +
16 +# Database Design Skill
17 +
18 +Best practices for schema design, query optimization, and database management.
19 +
20 +## Schema Design Principles
21 +
22 +### Normalization
23 +
24 +**1NF (First Normal Form)**
25 +- Each column contains atomic values
26 +- No repeating groups
27 +
28 +**2NF (Second Normal Form)**
29 +- Meet 1NF
30 +- No partial dependencies (all non-key columns depend on the entire primary key)
31 +
32 +**3NF (Third Normal Form)**
33 +- Meet 2NF
34 +- No transitive dependencies (non-key columns don't depend on other non-key columns)
35 +
36 +### Example: Normalized Schema
37 +
38 +```sql
39 +-- Users table
40 +CREATE TABLE users (
41 + id SERIAL PRIMARY KEY,
42 + email VARCHAR(255) UNIQUE NOT NULL,
43 + name VARCHAR(100) NOT NULL,
44 + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
45 + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
46 +);
47 +
48 +-- Addresses table (1:N relationship)
49 +CREATE TABLE addresses (
50 + id SERIAL PRIMARY KEY,
51 + user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
52 + street VARCHAR(255) NOT NULL,
53 + city VARCHAR(100) NOT NULL,
54 + country VARCHAR(100) NOT NULL,
55 + postal_code VARCHAR(20),
56 + is_primary BOOLEAN DEFAULT FALSE
57 +);
58 +
59 +-- Orders table
60 +CREATE TABLE orders (
61 + id SERIAL PRIMARY KEY,
62 + user_id INTEGER REFERENCES users(id),
63 + address_id INTEGER REFERENCES addresses(id),
64 + status VARCHAR(50) DEFAULT 'pending',
65 + total_amount DECIMAL(10, 2) NOT NULL,
66 + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
67 +);
68 +
69 +-- Order items (N:N through junction table)
70 +CREATE TABLE order_items (
71 + id SERIAL PRIMARY KEY,
72 + order_id INTEGER REFERENCES orders(id) ON DELETE CASCADE,
73 + product_id INTEGER REFERENCES products(id),
74 + quantity INTEGER NOT NULL CHECK (quantity > 0),
75 + unit_price DECIMAL(10, 2) NOT NULL
76 +);
77 +```
78 +
79 +### When to Denormalize
80 +
81 +Consider denormalization for:
82 +- Read-heavy workloads
83 +- Frequently joined tables
84 +- Reporting/analytics queries
85 +
86 +```sql
87 +-- Denormalized order summary (materialized view)
88 +CREATE MATERIALIZED VIEW order_summaries AS
89 +SELECT
90 + o.id,
91 + o.created_at,
92 + u.name AS user_name,
93 + u.email AS user_email,
94 + a.city AS shipping_city,
95 + o.total_amount,
96 + COUNT(oi.id) AS item_count
97 +FROM orders o
98 +JOIN users u ON o.user_id = u.id
99 +JOIN addresses a ON o.address_id = a.id
100 +JOIN order_items oi ON o.id = oi.order_id
101 +GROUP BY o.id, u.name, u.email, a.city;
102 +
103 +-- Refresh periodically
104 +REFRESH MATERIALIZED VIEW order_summaries;
105 +```
106 +
107 +## Index Optimization
108 +
109 +### Index Types
110 +
111 +```sql
112 +-- B-tree (default, good for most cases)
113 +CREATE INDEX idx_users_email ON users(email);
114 +
115 +-- Composite index (order matters!)
116 +CREATE INDEX idx_orders_user_date ON orders(user_id, created_at DESC);
117 +
118 +-- Partial index (for filtered queries)
119 +CREATE INDEX idx_active_users ON users(email) WHERE status = 'active';
120 +
121 +-- Expression index
122 +CREATE INDEX idx_users_lower_email ON users(LOWER(email));
123 +
124 +-- GIN index (for arrays, JSONB)
125 +CREATE INDEX idx_products_tags ON products USING GIN(tags);
126 +
127 +-- BRIN index (for large tables with natural ordering)
128 +CREATE INDEX idx_logs_timestamp ON logs USING BRIN(created_at);
129 +```
130 +
131 +### Index Guidelines
132 +
133 +```markdown
134 +## When to Add Indexes
135 +- [ ] Columns in WHERE clauses
136 +- [ ] Columns in JOIN conditions
137 +- [ ] Columns in ORDER BY
138 +- [ ] Foreign keys
139 +- [ ] Columns with high selectivity
140 +
141 +## When NOT to Add Indexes
142 +- [ ] Small tables (< 1000 rows)
143 +- [ ] Columns with low selectivity (boolean, status)
144 +- [ ] Tables with heavy write operations
145 +- [ ] Frequently updated columns
146 +```
147 +
148 +## Query Optimization
149 +
150 +### EXPLAIN ANALYZE
151 +
152 +```sql
153 +EXPLAIN ANALYZE
154 +SELECT u.name, COUNT(o.id) as order_count
155 +FROM users u
156 +LEFT JOIN orders o ON u.id = o.user_id
157 +WHERE u.created_at > '2024-01-01'
158 +GROUP BY u.id
159 +ORDER BY order_count DESC
160 +LIMIT 10;
161 +```
162 +
163 +### Common Optimizations
164 +
165 +**1. Use appropriate JOINs**
166 +```sql
167 +-- Bad: Subquery for each row
168 +SELECT *, (SELECT COUNT(*) FROM orders WHERE user_id = u.id)
169 +FROM users u;
170 +
171 +-- Good: Single JOIN
172 +SELECT u.*, COUNT(o.id) as order_count
173 +FROM users u
174 +LEFT JOIN orders o ON u.id = o.user_id
175 +GROUP BY u.id;
176 +```
177 +
178 +**2. Avoid SELECT ***
179 +```sql
180 +-- Bad
181 +SELECT * FROM users WHERE id = 1;
182 +
183 +-- Good
184 +SELECT id, name, email FROM users WHERE id = 1;
185 +```
186 +
187 +**3. Use LIMIT for pagination**
188 +```sql
189 +-- Offset pagination (slow for large offsets)
190 +SELECT * FROM products ORDER BY id LIMIT 20 OFFSET 10000;
191 +
192 +-- Keyset pagination (faster)
193 +SELECT * FROM products WHERE id > 10000 ORDER BY id LIMIT 20;
194 +```
195 +
196 +**4. Batch operations**
197 +```sql
198 +-- Bad: Individual inserts
199 +INSERT INTO logs (message) VALUES ('log1');
200 +INSERT INTO logs (message) VALUES ('log2');
201 +
202 +-- Good: Batch insert
203 +INSERT INTO logs (message) VALUES ('log1'), ('log2'), ('log3');
204 +```
205 +
206 +## Common Patterns
207 +
208 +### Soft Delete
209 +
210 +```sql
211 +ALTER TABLE users ADD COLUMN deleted_at TIMESTAMP;
212 +
213 +-- "Delete" a user
214 +UPDATE users SET deleted_at = CURRENT_TIMESTAMP WHERE id = 1;
215 +
216 +-- Query active users only
217 +SELECT * FROM users WHERE deleted_at IS NULL;
218 +
219 +-- Create view for convenience
220 +CREATE VIEW active_users AS
221 +SELECT * FROM users WHERE deleted_at IS NULL;
222 +```
223 +
224 +### Audit Trail
225 +
226 +```sql
227 +CREATE TABLE audit_log (
228 + id SERIAL PRIMARY KEY,
229 + table_name VARCHAR(100) NOT NULL,
230 + record_id INTEGER NOT NULL,
231 + action VARCHAR(10) NOT NULL, -- INSERT, UPDATE, DELETE
232 + old_data JSONB,
233 + new_data JSONB,
234 + changed_by INTEGER REFERENCES users(id),
235 + changed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
236 +);
237 +
238 +-- Trigger function
239 +CREATE OR REPLACE FUNCTION audit_trigger()
240 +RETURNS TRIGGER AS $$
241 +BEGIN
242 + IF TG_OP = 'INSERT' THEN
243 + INSERT INTO audit_log (table_name, record_id, action, new_data)
244 + VALUES (TG_TABLE_NAME, NEW.id, 'INSERT', to_jsonb(NEW));
245 + ELSIF TG_OP = 'UPDATE' THEN
246 + INSERT INTO audit_log (table_name, record_id, action, old_data, new_data)
247 + VALUES (TG_TABLE_NAME, NEW.id, 'UPDATE', to_jsonb(OLD), to_jsonb(NEW));
248 + ELSIF TG_OP = 'DELETE' THEN
249 + INSERT INTO audit_log (table_name, record_id, action, old_data)
250 + VALUES (TG_TABLE_NAME, OLD.id, 'DELETE', to_jsonb(OLD));
251 + END IF;
252 + RETURN NEW;
253 +END;
254 +$$ LANGUAGE plpgsql;
255 +```
256 +
257 +### Full-Text Search
258 +
259 +```sql
260 +-- Add search column
261 +ALTER TABLE products ADD COLUMN search_vector tsvector;
262 +
263 +-- Update search vector
264 +UPDATE products SET search_vector =
265 + setweight(to_tsvector('english', name), 'A') ||
266 + setweight(to_tsvector('english', description), 'B');
267 +
268 +-- Create GIN index
269 +CREATE INDEX idx_products_search ON products USING GIN(search_vector);
270 +
271 +-- Search query
272 +SELECT * FROM products
273 +WHERE search_vector @@ plainto_tsquery('english', 'wireless headphones')
274 +ORDER BY ts_rank(search_vector, plainto_tsquery('english', 'wireless headphones')) DESC;
275 +```
276 +
277 +## Performance Checklist
278 +
279 +```markdown
280 +## Schema Design
281 +- [ ] Appropriate data types (don't use VARCHAR(255) for everything)
282 +- [ ] Proper constraints (NOT NULL, UNIQUE, CHECK)
283 +- [ ] Foreign keys with proper ON DELETE behavior
284 +- [ ] UUID vs SERIAL for primary keys (consider use case)
285 +
286 +## Indexes
287 +- [ ] Primary key indexes exist
288 +- [ ] Foreign keys are indexed
289 +- [ ] Frequently queried columns indexed
290 +- [ ] No unused indexes (check pg_stat_user_indexes)
291 +
292 +## Queries
293 +- [ ] No N+1 queries
294 +- [ ] Appropriate use of JOINs vs subqueries
295 +- [ ] LIMIT on unbounded queries
296 +- [ ] EXPLAIN ANALYZE on slow queries
297 +
298 +## Maintenance
299 +- [ ] Regular VACUUM and ANALYZE
300 +- [ ] Connection pooling configured
301 +- [ ] Query timeouts set
302 +- [ ] Slow query logging enabled
303 +```
304 +
305 +## Useful Queries
306 +
307 +```sql
308 +-- Find unused indexes
309 +SELECT
310 + schemaname || '.' || relname AS table,
311 + indexrelname AS index,
312 + pg_size_pretty(pg_relation_size(i.indexrelid)) AS index_size,
313 + idx_scan AS index_scans
314 +FROM pg_stat_user_indexes ui
315 +JOIN pg_index i ON ui.indexrelid = i.indexrelid
316 +WHERE idx_scan < 50
317 +ORDER BY pg_relation_size(i.indexrelid) DESC;
318 +
319 +-- Find slow queries (requires pg_stat_statements)
320 +SELECT
321 + query,
322 + calls,
323 + mean_exec_time,
324 + total_exec_time
325 +FROM pg_stat_statements
326 +ORDER BY mean_exec_time DESC
327 +LIMIT 10;
328 +
329 +-- Table sizes
330 +SELECT
331 + relname AS table,
332 + pg_size_pretty(pg_total_relation_size(relid)) AS total_size
333 +FROM pg_catalog.pg_statio_user_tables
334 +ORDER BY pg_total_relation_size(relid) DESC;
335 +```
skills/builtin/debugging/SKILL.md new
+179
@@ -0,0 +1,179 @@
1 +---
2 +name: "debugging"
3 +description: "Systematic debugging methodology for identifying and fixing bugs. Use when encountering errors, unexpected behavior, or test failures."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["debugging", "troubleshooting", "errors", "testing", "analysis"]
7 +trigger_patterns:
8 + - "error"
9 + - "bug"
10 + - "not working"
11 + - "fails"
12 + - "broken"
13 + - "fix"
14 + - "debug"
15 +---
16 +
17 +# Systematic Debugging Skill
18 +
19 +**CRITICAL**: Follow this systematic process. Never guess at fixes without understanding the root cause.
20 +
21 +## When to Use
22 +
23 +Activate this skill when you encounter:
24 +- Error messages or stack traces
25 +- Unexpected behavior
26 +- Test failures
27 +- Performance issues
28 +- "It was working before" scenarios
29 +
30 +## The Debugging Process
31 +
32 +### Phase 1: Reproduce the Issue
33 +
34 +**Goal**: Confirm you can consistently trigger the bug.
35 +
36 +1. **Document the steps** to reproduce
37 +2. **Identify the exact error** message or unexpected behavior
38 +3. **Note the environment**: OS, versions, configuration
39 +4. **Establish baseline**: When did it last work correctly?
40 +
41 +```markdown
42 +## Reproduction Steps
43 +1. Step 1
44 +2. Step 2
45 +3. Step 3
46 +Expected: [What should happen]
47 +Actual: [What actually happens]
48 +```
49 +
50 +### Phase 2: Gather Evidence
51 +
52 +**Goal**: Collect all relevant information before forming hypotheses.
53 +
54 +1. **Read the full error message** and stack trace
55 +2. **Check logs** at multiple levels (app, system, network)
56 +3. **Examine recent changes** (git diff, git log)
57 +4. **Review related code** paths
58 +5. **Check dependencies** and their versions
59 +
60 +```bash
61 +# Useful commands
62 +git log --oneline -20 # Recent commits
63 +git diff HEAD~5 # Recent changes
64 +cat /var/log/app.log # Application logs
65 +```
66 +
67 +### Phase 3: Form Hypotheses
68 +
69 +**Goal**: Generate multiple possible causes ranked by likelihood.
70 +
71 +List hypotheses in order of probability:
72 +
73 +```markdown
74 +## Hypotheses
75 +1. [Most likely] Description - Evidence supporting this
76 +2. [Likely] Description - Evidence supporting this
77 +3. [Possible] Description - Evidence supporting this
78 +```
79 +
80 +### Phase 4: Test Hypotheses
81 +
82 +**Goal**: Systematically eliminate possibilities.
83 +
84 +For each hypothesis:
85 +1. **Design a test** that would confirm or refute it
86 +2. **Execute the test** with minimal changes
87 +3. **Document results**
88 +4. **Move to next hypothesis** if not confirmed
89 +
90 +```markdown
91 +## Testing: Hypothesis 1
92 +Test: [What I'll do to test this]
93 +Result: [Confirmed/Refuted]
94 +Evidence: [What I observed]
95 +```
96 +
97 +### Phase 5: Implement Fix
98 +
99 +**Goal**: Fix the root cause, not just the symptom.
100 +
101 +1. **Isolate the fix**: Make the smallest change that fixes the issue
102 +2. **Verify the fix**: Confirm the original reproduction steps now pass
103 +3. **Check for regressions**: Ensure nothing else broke
104 +4. **Document the fix**: Explain what was wrong and why the fix works
105 +
106 +### Phase 6: Prevent Recurrence
107 +
108 +**Goal**: Stop this class of bug from happening again.
109 +
110 +1. **Add a test** that would have caught this bug
111 +2. **Consider defensive coding** (validation, error handling)
112 +3. **Update documentation** if needed
113 +4. **Share learnings** with team if relevant
114 +
115 +## Anti-Patterns to Avoid
116 +
117 +- **Random Changes**: Never make changes hoping something works
118 +- **Fix Symptoms**: Always find and fix the root cause
119 +- **Skip Reproduction**: Always confirm you can reproduce before fixing
120 +- **Single Hypothesis**: Consider multiple possibilities
121 +- **No Testing**: Always verify the fix works
122 +
123 +## Debugging Tools
124 +
125 +### For Python
126 +```python
127 +# Interactive debugging
128 +import pdb; pdb.set_trace()
129 +
130 +# Or using ipdb for better experience
131 +import ipdb; ipdb.set_trace()
132 +
133 +# Print debugging with context
134 +print(f"DEBUG: {variable=}, {type(variable)=}")
135 +```
136 +
137 +### For JavaScript
138 +```javascript
139 +// Debugger statement
140 +debugger;
141 +
142 +// Console logging with labels
143 +console.log({ variable, typeof: typeof variable });
144 +
145 +// Trace to see call stack
146 +console.trace("How did we get here?");
147 +```
148 +
149 +### General
150 +```bash
151 +# Check if process is running
152 +ps aux | grep <process>
153 +
154 +# Check port usage
155 +lsof -i :<port>
156 +
157 +# Watch file changes
158 +tail -f /path/to/log
159 +```
160 +
161 +## Example Session
162 +
163 +**User**: "The API endpoint returns 500 error"
164 +
165 +**Agent Response**:
166 +> Let me debug this systematically:
167 +>
168 +> ## Phase 1: Reproduction
169 +> - Which endpoint specifically?
170 +> - What request parameters are you sending?
171 +> - Does it fail consistently or intermittently?
172 +>
173 +> ## Phase 2: Gathering Evidence
174 +> Let me check:
175 +> 1. The server error logs
176 +> 2. Recent changes to this endpoint
177 +> 3. The full stack trace
178 +>
179 +> [Proceeds systematically through each phase]
skills/builtin/docker_devops/SKILL.md new
+394
@@ -0,0 +1,394 @@
1 +---
2 +name: "docker_devops"
3 +description: "Docker and DevOps best practices for containerization, orchestration, and CI/CD pipelines. Use when working with containers, deployments, or infrastructure."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["docker", "devops", "containers", "kubernetes", "ci-cd", "infrastructure"]
7 +trigger_patterns:
8 + - "docker"
9 + - "container"
10 + - "kubernetes"
11 + - "k8s"
12 + - "deploy"
13 + - "ci/cd"
14 + - "pipeline"
15 +---
16 +
17 +# Docker & DevOps Skill
18 +
19 +Best practices for containerization, orchestration, and deployment pipelines.
20 +
21 +## Docker Fundamentals
22 +
23 +### Dockerfile Best Practices
24 +
25 +```dockerfile
26 +# Use specific version tags
27 +FROM python:3.11-slim
28 +
29 +# Set working directory
30 +WORKDIR /app
31 +
32 +# Copy dependency files first (layer caching)
33 +COPY requirements.txt .
34 +
35 +# Install dependencies
36 +RUN pip install --no-cache-dir -r requirements.txt
37 +
38 +# Copy application code
39 +COPY . .
40 +
41 +# Use non-root user
42 +RUN useradd -m appuser && chown -R appuser:appuser /app
43 +USER appuser
44 +
45 +# Expose port
46 +EXPOSE 8000
47 +
48 +# Use exec form for CMD
49 +CMD ["python", "app.py"]
50 +```
51 +
52 +### Multi-Stage Builds
53 +
54 +```dockerfile
55 +# Build stage
56 +FROM node:18 AS builder
57 +WORKDIR /app
58 +COPY package*.json ./
59 +RUN npm ci
60 +COPY . .
61 +RUN npm run build
62 +
63 +# Production stage
64 +FROM nginx:alpine
65 +COPY --from=builder /app/dist /usr/share/nginx/html
66 +EXPOSE 80
67 +CMD ["nginx", "-g", "daemon off;"]
68 +```
69 +
70 +### Docker Compose
71 +
72 +```yaml
73 +version: '3.8'
74 +
75 +services:
76 + app:
77 + build:
78 + context: .
79 + dockerfile: Dockerfile
80 + ports:
81 + - "8000:8000"
82 + environment:
83 + - DATABASE_URL=postgresql://user:pass@db:5432/app
84 + depends_on:
85 + db:
86 + condition: service_healthy
87 + volumes:
88 + - ./app:/app
89 + healthcheck:
90 + test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
91 + interval: 30s
92 + timeout: 10s
93 + retries: 3
94 +
95 + db:
96 + image: postgres:15-alpine
97 + environment:
98 + POSTGRES_USER: user
99 + POSTGRES_PASSWORD: pass
100 + POSTGRES_DB: app
101 + volumes:
102 + - postgres_data:/var/lib/postgresql/data
103 + healthcheck:
104 + test: ["CMD-SHELL", "pg_isready -U user -d app"]
105 + interval: 10s
106 + timeout: 5s
107 + retries: 5
108 +
109 +volumes:
110 + postgres_data:
111 +```
112 +
113 +## Kubernetes Basics
114 +
115 +### Deployment
116 +
117 +```yaml
118 +apiVersion: apps/v1
119 +kind: Deployment
120 +metadata:
121 + name: myapp
122 + labels:
123 + app: myapp
124 +spec:
125 + replicas: 3
126 + selector:
127 + matchLabels:
128 + app: myapp
129 + template:
130 + metadata:
131 + labels:
132 + app: myapp
133 + spec:
134 + containers:
135 + - name: myapp
136 + image: myapp:1.0.0
137 + ports:
138 + - containerPort: 8000
139 + resources:
140 + requests:
141 + memory: "128Mi"
142 + cpu: "100m"
143 + limits:
144 + memory: "256Mi"
145 + cpu: "200m"
146 + livenessProbe:
147 + httpGet:
148 + path: /health
149 + port: 8000
150 + initialDelaySeconds: 30
151 + periodSeconds: 10
152 + readinessProbe:
153 + httpGet:
154 + path: /ready
155 + port: 8000
156 + initialDelaySeconds: 5
157 + periodSeconds: 5
158 +```
159 +
160 +### Service
161 +
162 +```yaml
163 +apiVersion: v1
164 +kind: Service
165 +metadata:
166 + name: myapp-service
167 +spec:
168 + selector:
169 + app: myapp
170 + ports:
171 + - port: 80
172 + targetPort: 8000
173 + type: ClusterIP
174 +```
175 +
176 +### Ingress
177 +
178 +```yaml
179 +apiVersion: networking.k8s.io/v1
180 +kind: Ingress
181 +metadata:
182 + name: myapp-ingress
183 + annotations:
184 + nginx.ingress.kubernetes.io/rewrite-target: /
185 +spec:
186 + rules:
187 + - host: myapp.example.com
188 + http:
189 + paths:
190 + - path: /
191 + pathType: Prefix
192 + backend:
193 + service:
194 + name: myapp-service
195 + port:
196 + number: 80
197 +```
198 +
199 +## CI/CD Pipelines
200 +
201 +### GitHub Actions
202 +
203 +```yaml
204 +name: CI/CD Pipeline
205 +
206 +on:
207 + push:
208 + branches: [main]
209 + pull_request:
210 + branches: [main]
211 +
212 +jobs:
213 + test:
214 + runs-on: ubuntu-latest
215 + steps:
216 + - uses: actions/checkout@v3
217 +
218 + - name: Set up Python
219 + uses: actions/setup-python@v4
220 + with:
221 + python-version: '3.11'
222 +
223 + - name: Install dependencies
224 + run: |
225 + pip install -r requirements.txt
226 + pip install pytest
227 +
228 + - name: Run tests
229 + run: pytest
230 +
231 + build:
232 + needs: test
233 + runs-on: ubuntu-latest
234 + steps:
235 + - uses: actions/checkout@v3
236 +
237 + - name: Build Docker image
238 + run: docker build -t myapp:${{ github.sha }} .
239 +
240 + - name: Login to Container Registry
241 + uses: docker/login-action@v2
242 + with:
243 + registry: ghcr.io
244 + username: ${{ github.actor }}
245 + password: ${{ secrets.GITHUB_TOKEN }}
246 +
247 + - name: Push image
248 + run: |
249 + docker tag myapp:${{ github.sha }} ghcr.io/${{ github.repository }}:${{ github.sha }}
250 + docker push ghcr.io/${{ github.repository }}:${{ github.sha }}
251 +
252 + deploy:
253 + needs: build
254 + if: github.ref == 'refs/heads/main'
255 + runs-on: ubuntu-latest
256 + steps:
257 + - name: Deploy to production
258 + run: |
259 + echo "Deploying ${{ github.sha }}"
260 + # kubectl set image deployment/myapp myapp=ghcr.io/${{ github.repository }}:${{ github.sha }}
261 +```
262 +
263 +### GitLab CI
264 +
265 +```yaml
266 +stages:
267 + - test
268 + - build
269 + - deploy
270 +
271 +variables:
272 + DOCKER_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
273 +
274 +test:
275 + stage: test
276 + image: python:3.11
277 + script:
278 + - pip install -r requirements.txt
279 + - pytest
280 +
281 +build:
282 + stage: build
283 + image: docker:latest
284 + services:
285 + - docker:dind
286 + script:
287 + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
288 + - docker build -t $DOCKER_IMAGE .
289 + - docker push $DOCKER_IMAGE
290 +
291 +deploy:
292 + stage: deploy
293 + only:
294 + - main
295 + script:
296 + - kubectl set image deployment/myapp myapp=$DOCKER_IMAGE
297 +```
298 +
299 +## Useful Commands
300 +
301 +### Docker
302 +
303 +```bash
304 +# Build image
305 +docker build -t myapp:latest .
306 +
307 +# Run container
308 +docker run -d -p 8000:8000 --name myapp myapp:latest
309 +
310 +# View logs
311 +docker logs -f myapp
312 +
313 +# Execute in container
314 +docker exec -it myapp /bin/sh
315 +
316 +# Clean up
317 +docker system prune -a
318 +
319 +# List resources
320 +docker ps -a
321 +docker images
322 +docker volume ls
323 +docker network ls
324 +```
325 +
326 +### Kubernetes
327 +
328 +```bash
329 +# Get resources
330 +kubectl get pods
331 +kubectl get services
332 +kubectl get deployments
333 +
334 +# Describe resource
335 +kubectl describe pod <pod-name>
336 +
337 +# Logs
338 +kubectl logs -f <pod-name>
339 +
340 +# Execute in pod
341 +kubectl exec -it <pod-name> -- /bin/sh
342 +
343 +# Apply configuration
344 +kubectl apply -f deployment.yaml
345 +
346 +# Scale deployment
347 +kubectl scale deployment myapp --replicas=5
348 +
349 +# Rollback
350 +kubectl rollout undo deployment/myapp
351 +```
352 +
353 +## Security Checklist
354 +
355 +```markdown
356 +- [ ] Use specific image tags, not 'latest'
357 +- [ ] Run as non-root user
358 +- [ ] Scan images for vulnerabilities
359 +- [ ] Use secrets management (not env vars for sensitive data)
360 +- [ ] Limit container resources
361 +- [ ] Enable network policies
362 +- [ ] Use read-only file systems where possible
363 +- [ ] Implement pod security policies
364 +- [ ] Rotate credentials regularly
365 +```
366 +
367 +## Monitoring & Logging
368 +
369 +```yaml
370 +# Prometheus ServiceMonitor
371 +apiVersion: monitoring.coreos.com/v1
372 +kind: ServiceMonitor
373 +metadata:
374 + name: myapp
375 +spec:
376 + selector:
377 + matchLabels:
378 + app: myapp
379 + endpoints:
380 + - port: metrics
381 + interval: 30s
382 +```
383 +
384 +```yaml
385 +# Fluentd sidecar for logging
386 +containers:
387 +- name: myapp
388 + image: myapp:latest
389 +- name: fluentd
390 + image: fluent/fluentd:latest
391 + volumeMounts:
392 + - name: logs
393 + mountPath: /var/log/app
394 +```
skills/builtin/git_workflow/SKILL.md new
+357
@@ -0,0 +1,357 @@
1 +---
2 +name: "git_workflow"
3 +description: "Git workflow best practices for branching, committing, and collaboration. Use when working with version control."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["git", "version-control", "branching", "collaboration", "workflow"]
7 +trigger_patterns:
8 + - "git"
9 + - "commit"
10 + - "branch"
11 + - "merge"
12 + - "pull request"
13 +---
14 +
15 +# Git Workflow Skill
16 +
17 +Best practices for version control and team collaboration.
18 +
19 +## Branching Strategy
20 +
21 +### Branch Naming Convention
22 +
23 +```
24 +<type>/<ticket-id>-<short-description>
25 +```
26 +
27 +**Types:**
28 +- `feature/` - New features
29 +- `bugfix/` - Bug fixes
30 +- `hotfix/` - Urgent production fixes
31 +- `refactor/` - Code refactoring
32 +- `docs/` - Documentation updates
33 +- `test/` - Adding tests
34 +- `chore/` - Maintenance tasks
35 +
36 +**Examples:**
37 +```bash
38 +feature/PROJ-123-add-user-authentication
39 +bugfix/PROJ-456-fix-login-timeout
40 +hotfix/PROJ-789-critical-security-patch
41 +```
42 +
43 +### Branch Workflow
44 +
45 +```
46 +main (production)
47 + │
48 + ├── develop (integration)
49 + │ │
50 + │ ├── feature/add-login
51 + │ ├── feature/add-dashboard
52 + │ └── bugfix/fix-signup
53 + │
54 + └── hotfix/security-patch (urgent fixes from main)
55 +```
56 +
57 +## Commit Messages
58 +
59 +### Conventional Commits Format
60 +
61 +```
62 +<type>(<scope>): <description>
63 +
64 +[optional body]
65 +
66 +[optional footer(s)]
67 +```
68 +
69 +### Types
70 +
71 +| Type | Description |
72 +|------|-------------|
73 +| `feat` | New feature |
74 +| `fix` | Bug fix |
75 +| `docs` | Documentation |
76 +| `style` | Formatting (no code change) |
77 +| `refactor` | Code refactoring |
78 +| `test` | Adding tests |
79 +| `chore` | Maintenance |
80 +| `perf` | Performance improvement |
81 +| `ci` | CI/CD changes |
82 +
83 +### Examples
84 +
85 +```bash
86 +# Feature
87 +feat(auth): add JWT token refresh mechanism
88 +
89 +# Bug fix with ticket reference
90 +fix(api): resolve timeout issue on large payloads
91 +
92 +Closes #123
93 +
94 +# Breaking change
95 +feat(api)!: change user endpoint response format
96 +
97 +BREAKING CHANGE: User endpoint now returns nested
98 +address object instead of flat fields.
99 +
100 +# Multi-line with body
101 +refactor(database): optimize user query performance
102 +
103 +- Added composite index on (email, created_at)
104 +- Removed N+1 query in user loader
105 +- Cached frequently accessed user data
106 +
107 +Performance improved from 500ms to 50ms for user list.
108 +```
109 +
110 +## Common Workflows
111 +
112 +### Starting New Work
113 +
114 +```bash
115 +# 1. Update main branch
116 +git checkout main
117 +git pull origin main
118 +
119 +# 2. Create feature branch
120 +git checkout -b feature/PROJ-123-new-feature
121 +
122 +# 3. Make changes and commit
123 +git add .
124 +git commit -m "feat(module): add new functionality"
125 +
126 +# 4. Push and create PR
127 +git push -u origin feature/PROJ-123-new-feature
128 +```
129 +
130 +### Syncing with Main
131 +
132 +```bash
133 +# Option 1: Rebase (preferred for feature branches)
134 +git fetch origin
135 +git rebase origin/main
136 +
137 +# Option 2: Merge (when history preservation needed)
138 +git fetch origin
139 +git merge origin/main
140 +```
141 +
142 +### Interactive Rebase (Cleaning History)
143 +
144 +```bash
145 +# Squash last 3 commits
146 +git rebase -i HEAD~3
147 +
148 +# In editor, change 'pick' to 'squash' for commits to combine
149 +pick abc1234 feat: add login form
150 +squash def5678 fix: typo in form
151 +squash ghi9012 style: format code
152 +```
153 +
154 +### Undoing Changes
155 +
156 +```bash
157 +# Undo last commit (keep changes)
158 +git reset --soft HEAD~1
159 +
160 +# Undo last commit (discard changes)
161 +git reset --hard HEAD~1
162 +
163 +# Undo specific file changes
164 +git checkout -- path/to/file
165 +
166 +# Revert a pushed commit (safe)
167 +git revert <commit-hash>
168 +```
169 +
170 +### Stashing Work
171 +
172 +```bash
173 +# Save current changes
174 +git stash save "WIP: feature description"
175 +
176 +# List stashes
177 +git stash list
178 +
179 +# Apply most recent stash
180 +git stash pop
181 +
182 +# Apply specific stash
183 +git stash apply stash@{2}
184 +
185 +# Drop a stash
186 +git stash drop stash@{0}
187 +```
188 +
189 +## Pull Request Guidelines
190 +
191 +### Before Creating PR
192 +
193 +1. **Rebase on latest main**
194 + ```bash
195 + git fetch origin
196 + git rebase origin/main
197 + ```
198 +
199 +2. **Run tests locally**
200 + ```bash
201 + npm test # or your test command
202 + ```
203 +
204 +3. **Self-review your changes**
205 + ```bash
206 + git diff origin/main
207 + ```
208 +
209 +4. **Clean up commits**
210 + - Squash fixup commits
211 + - Write clear commit messages
212 +
213 +### PR Description Template
214 +
215 +```markdown
216 +## Summary
217 +Brief description of changes
218 +
219 +## Type of Change
220 +- [ ] Feature
221 +- [ ] Bug fix
222 +- [ ] Refactor
223 +- [ ] Documentation
224 +
225 +## Changes Made
226 +- Change 1
227 +- Change 2
228 +- Change 3
229 +
230 +## Testing Done
231 +- [ ] Unit tests pass
232 +- [ ] Integration tests pass
233 +- [ ] Manual testing completed
234 +
235 +## Screenshots (if applicable)
236 +[Add screenshots here]
237 +
238 +## Related Issues
239 +Closes #123
240 +```
241 +
242 +### PR Best Practices
243 +
244 +1. **Keep PRs Small**: < 400 lines ideally
245 +2. **One Concern Per PR**: Don't mix features
246 +3. **Descriptive Title**: Summarize the change
247 +4. **Link Issues**: Reference related tickets
248 +5. **Add Context**: Explain why, not just what
249 +6. **Request Reviews**: Tag appropriate reviewers
250 +
251 +## Resolving Conflicts
252 +
253 +### Step-by-Step
254 +
255 +```bash
256 +# 1. Update your branch
257 +git fetch origin
258 +
259 +# 2. Rebase on main
260 +git rebase origin/main
261 +
262 +# 3. When conflicts occur, Git will pause
263 +# Fix conflicts in your editor
264 +
265 +# 4. After fixing each file
266 +git add <fixed-file>
267 +
268 +# 5. Continue rebase
269 +git rebase --continue
270 +
271 +# 6. If too complex, abort and try merge instead
272 +git rebase --abort
273 +git merge origin/main
274 +```
275 +
276 +### Conflict Markers
277 +
278 +```
279 +<<<<<<< HEAD
280 +Your changes
281 +=======
282 +Their changes
283 +>>>>>>> branch-name
284 +```
285 +
286 +## Git Hooks
287 +
288 +### Pre-commit Hook Example
289 +
290 +```bash
291 +#!/bin/sh
292 +# .git/hooks/pre-commit
293 +
294 +# Run linter
295 +npm run lint
296 +if [ $? -ne 0 ]; then
297 + echo "Lint failed. Fix errors before committing."
298 + exit 1
299 +fi
300 +
301 +# Run tests
302 +npm test
303 +if [ $? -ne 0 ]; then
304 + echo "Tests failed. Fix tests before committing."
305 + exit 1
306 +fi
307 +```
308 +
309 +### Commit Message Hook
310 +
311 +```bash
312 +#!/bin/sh
313 +# .git/hooks/commit-msg
314 +
315 +# Enforce conventional commits
316 +commit_regex='^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .{1,50}'
317 +
318 +if ! grep -qE "$commit_regex" "$1"; then
319 + echo "Invalid commit message format."
320 + echo "Use: <type>(<scope>): <description>"
321 + exit 1
322 +fi
323 +```
324 +
325 +## Useful Aliases
326 +
327 +Add to `~/.gitconfig`:
328 +
329 +```ini
330 +[alias]
331 + # Status
332 + s = status -sb
333 +
334 + # Logging
335 + lg = log --oneline --graph --all
336 + last = log -1 HEAD --stat
337 +
338 + # Branching
339 + co = checkout
340 + cob = checkout -b
341 + br = branch -v
342 +
343 + # Committing
344 + cm = commit -m
345 + amend = commit --amend --no-edit
346 +
347 + # Stashing
348 + sl = stash list
349 + sp = stash pop
350 +
351 + # Diffing
352 + d = diff
353 + dc = diff --cached
354 +
355 + # Cleanup
356 + cleanup = "!git branch --merged | grep -v '\\*\\|main\\|develop' | xargs -n 1 git branch -d"
357 +```
skills/builtin/prompt_engineering/SKILL.md new
+404
@@ -0,0 +1,404 @@
1 +---
2 +name: "prompt_engineering"
3 +description: "Best practices for crafting effective prompts for LLMs. Use when designing prompts, creating system messages, or optimizing AI interactions."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["prompts", "llm", "ai", "gpt", "claude", "optimization"]
7 +trigger_patterns:
8 + - "prompt"
9 + - "system message"
10 + - "llm"
11 + - "ai instruction"
12 + - "chatgpt"
13 + - "claude"
14 +---
15 +
16 +# Prompt Engineering Skill
17 +
18 +Best practices for designing effective prompts for Large Language Models.
19 +
20 +## Core Principles
21 +
22 +### 1. Be Specific and Clear
23 +
24 +```markdown
25 +# Bad
26 +"Write something about dogs"
27 +
28 +# Good
29 +"Write a 200-word article about the top 3 benefits of adopting
30 +a rescue dog. Include a brief introduction and conclusion.
31 +Use a friendly, conversational tone suitable for pet owners."
32 +```
33 +
34 +### 2. Provide Context
35 +
36 +```markdown
37 +# Bad
38 +"Fix this code"
39 +
40 +# Good
41 +"I have a Python function that should validate email addresses.
42 +Currently it accepts invalid emails like 'test@'.
43 +
44 +Current code:
45 +```python
46 +def validate_email(email):
47 + return '@' in email
48 +```
49 +
50 +Please fix this to properly validate email format."
51 +```
52 +
53 +### 3. Specify Output Format
54 +
55 +```markdown
56 +# Bad
57 +"List some programming languages"
58 +
59 +# Good
60 +"List 5 programming languages for web development.
61 +Format as a markdown table with columns:
62 +- Language name
63 +- Primary use case
64 +- Learning difficulty (Easy/Medium/Hard)"
65 +```
66 +
67 +## Prompt Patterns
68 +
69 +### Role Pattern
70 +
71 +Assign a specific persona to guide responses:
72 +
73 +```markdown
74 +You are a senior Python developer with 10 years of experience.
75 +You specialize in clean code, testing, and code reviews.
76 +When reviewing code, you:
77 +- Focus on readability and maintainability
78 +- Suggest improvements with explanations
79 +- Point out potential bugs or security issues
80 +
81 +Please review the following code:
82 +[code here]
83 +```
84 +
85 +### Chain of Thought
86 +
87 +Guide step-by-step reasoning:
88 +
89 +```markdown
90 +Solve this problem step by step:
91 +
92 +Problem: A store has 150 apples. They sell 30% on Monday,
93 +then receive a shipment of 50 apples on Tuesday.
94 +How many apples do they have now?
95 +
96 +Please show your work:
97 +1. Calculate apples sold on Monday
98 +2. Calculate remaining apples after Monday
99 +3. Add Tuesday's shipment
100 +4. State the final answer
101 +```
102 +
103 +### Few-Shot Learning
104 +
105 +Provide examples to establish patterns:
106 +
107 +```markdown
108 +Convert these sentences to formal English:
109 +
110 +Example 1:
111 +Casual: "gonna grab some coffee"
112 +Formal: "I am going to get some coffee."
113 +
114 +Example 2:
115 +Casual: "wanna come with?"
116 +Formal: "Would you like to accompany me?"
117 +
118 +Now convert:
119 +Casual: "lemme know if you're free"
120 +Formal:
121 +```
122 +
123 +### Template Pattern
124 +
125 +Create reusable structures:
126 +
127 +```markdown
128 +# Bug Report Template
129 +
130 +Please analyze this bug and provide:
131 +
132 +## Summary
133 +[One sentence description]
134 +
135 +## Root Cause
136 +[Technical explanation of why this bug occurs]
137 +
138 +## Impact
139 +[Who is affected and how]
140 +
141 +## Solution
142 +[Recommended fix with code example]
143 +
144 +## Prevention
145 +[How to prevent similar bugs in the future]
146 +
147 +---
148 +Bug to analyze:
149 +[user's bug description]
150 +```
151 +
152 +## System Prompts
153 +
154 +### Structure
155 +
156 +```markdown
157 +# [Role/Identity]
158 +You are [description of the assistant's role and expertise]
159 +
160 +# [Core Behaviors]
161 +You should always:
162 +- [Behavior 1]
163 +- [Behavior 2]
164 +
165 +You should never:
166 +- [Anti-pattern 1]
167 +- [Anti-pattern 2]
168 +
169 +# [Response Format]
170 +When responding:
171 +- [Format guideline 1]
172 +- [Format guideline 2]
173 +
174 +# [Examples] (optional)
175 +Here's an example of how to respond:
176 +[example interaction]
177 +```
178 +
179 +### Example System Prompt
180 +
181 +```markdown
182 +# Role
183 +You are a helpful coding assistant specializing in Python.
184 +You have expertise in data science, web development, and automation.
185 +
186 +# Core Behaviors
187 +Always:
188 +- Write clean, well-documented code
189 +- Explain your reasoning
190 +- Suggest tests for code you write
191 +- Consider edge cases
192 +
193 +Never:
194 +- Write code without explanation
195 +- Use deprecated libraries
196 +- Ignore security best practices
197 +- Make assumptions about requirements without clarifying
198 +
199 +# Response Format
200 +When writing code:
201 +1. Start with a brief explanation of the approach
202 +2. Write the code with comments
203 +3. Explain any complex parts
204 +4. Suggest how to test it
205 +
206 +When debugging:
207 +1. Identify the likely cause
208 +2. Explain why it happens
209 +3. Provide the fix
210 +4. Suggest how to prevent similar issues
211 +```
212 +
213 +## Optimization Techniques
214 +
215 +### Iterative Refinement
216 +
217 +```markdown
218 +# First attempt
219 +"Write a story"
220 +
221 +# After iteration 1: Add specifics
222 +"Write a 500-word short story about a robot"
223 +
224 +# After iteration 2: Add constraints
225 +"Write a 500-word short story about a robot
226 +learning to paint. Include dialogue."
227 +
228 +# After iteration 3: Add style
229 +"Write a 500-word short story about a robot
230 +learning to paint. Include dialogue. Write in
231 +a warm, hopeful tone similar to Studio Ghibli films."
232 +```
233 +
234 +### Decomposition
235 +
236 +Break complex tasks into steps:
237 +
238 +```markdown
239 +Instead of:
240 +"Create a complete e-commerce website"
241 +
242 +Use:
243 +"Let's build an e-commerce website step by step:
244 +
245 +Step 1: Define the data models we need for products,
246 +users, and orders. Show me the schema.
247 +
248 +[Wait for response]
249 +
250 +Step 2: Based on those models, create the API endpoints.
251 +
252 +[Wait for response]
253 +
254 +Step 3: Now let's build the product listing page..."
255 +```
256 +
257 +### Constraint Setting
258 +
259 +```markdown
260 +# Add boundaries for better results
261 +"Write a product description for a coffee maker.
262 +
263 +Constraints:
264 +- Maximum 100 words
265 +- Include 3 key features
266 +- End with a call to action
267 +- Don't use superlatives like 'best' or 'amazing'
268 +- Write at a 6th-grade reading level"
269 +```
270 +
271 +## Common Pitfalls
272 +
273 +### 1. Vague Instructions
274 +
275 +```markdown
276 +# Bad
277 +"Make it better"
278 +
279 +# Good
280 +"Improve the readability by:
281 +- Using shorter sentences (max 20 words)
282 +- Adding subheadings every 100-150 words
283 +- Replacing jargon with plain language"
284 +```
285 +
286 +### 2. Missing Context
287 +
288 +```markdown
289 +# Bad
290 +"Why isn't my code working?"
291 +
292 +# Good
293 +"My Python code throws a TypeError.
294 +Environment: Python 3.11, macOS
295 +Error message: TypeError: 'NoneType' object is not iterable
296 +Code:
297 +```python
298 +def process(items):
299 + for item in items:
300 + print(item)
301 +
302 +process(get_items()) # Error occurs here
303 +```
304 +The get_items() function should return a list."
305 +```
306 +
307 +### 3. Overloading
308 +
309 +```markdown
310 +# Bad (too many things at once)
311 +"Write a blog post about AI, make it SEO optimized,
312 +include code examples, add images, make it funny but professional,
313 +target beginners but also appeal to experts..."
314 +
315 +# Good (focused request)
316 +"Write a 500-word introduction to machine learning
317 +for complete beginners. Use simple analogies and
318 +avoid technical jargon. Include 3 real-world examples."
319 +```
320 +
321 +## Evaluation Checklist
322 +
323 +```markdown
324 +Before submitting a prompt, verify:
325 +
326 +## Clarity
327 +- [ ] Is the task clearly defined?
328 +- [ ] Are ambiguous terms explained?
329 +- [ ] Is the expected output format specified?
330 +
331 +## Context
332 +- [ ] Is relevant background provided?
333 +- [ ] Are constraints clearly stated?
334 +- [ ] Are examples included if needed?
335 +
336 +## Structure
337 +- [ ] Is the prompt well-organized?
338 +- [ ] Are complex tasks broken into steps?
339 +- [ ] Is there a clear order of operations?
340 +
341 +## Completeness
342 +- [ ] Does it include all necessary information?
343 +- [ ] Are edge cases considered?
344 +- [ ] Is the success criteria clear?
345 +```
346 +
347 +## Examples by Use Case
348 +
349 +### Code Generation
350 +
351 +```markdown
352 +Write a Python function that:
353 +- Takes a list of dictionaries representing users
354 +- Filters users older than 18
355 +- Sorts by last name alphabetically
356 +- Returns their email addresses
357 +
358 +Input example:
359 +[{"name": "John Doe", "age": 25, "email": "john@example.com"}]
360 +
361 +Requirements:
362 +- Include type hints
363 +- Add docstring
364 +- Handle empty list case
365 +- Include unit test
366 +```
367 +
368 +### Data Analysis
369 +
370 +```markdown
371 +Analyze this sales data and provide:
372 +
373 +1. Summary statistics (mean, median, std dev)
374 +2. Top 3 performing products
375 +3. Month-over-month growth rate
376 +4. Any anomalies or patterns
377 +
378 +Present findings in a markdown table.
379 +Include a brief executive summary (3-4 sentences).
380 +
381 +Data:
382 +[paste data here]
383 +```
384 +
385 +### Writing Assistance
386 +
387 +```markdown
388 +Help me improve this email to a client:
389 +
390 +Context: We need to delay the project by 2 weeks
391 +due to unexpected technical issues.
392 +
393 +Current draft:
394 +"Hi, the project will be late. Sorry about that."
395 +
396 +Goals:
397 +- Maintain professional relationship
398 +- Clearly explain the delay
399 +- Provide new timeline
400 +- Offer mitigation options
401 +
402 +Tone: Professional but warm
403 +Length: 150-200 words
404 +```
skills/builtin/security_audit/SKILL.md new
+453
@@ -0,0 +1,453 @@
1 +---
2 +name: "security_audit"
3 +description: "Security audit and vulnerability assessment skill. Use when reviewing code for security issues, hardening systems, or implementing security best practices."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["security", "audit", "vulnerability", "owasp", "hardening"]
7 +trigger_patterns:
8 + - "security"
9 + - "vulnerability"
10 + - "secure"
11 + - "audit"
12 + - "owasp"
13 + - "penetration"
14 +---
15 +
16 +# Security Audit Skill
17 +
18 +Comprehensive security review and vulnerability assessment guidance.
19 +
20 +## OWASP Top 10 Checklist
21 +
22 +### 1. Broken Access Control
23 +
24 +```markdown
25 +## Check for:
26 +- [ ] Direct object references (IDOR)
27 +- [ ] Missing function-level access control
28 +- [ ] Privilege escalation paths
29 +- [ ] Bypassing access control via URL manipulation
30 +
31 +## Example vulnerability:
32 +```python
33 +# Bad: No authorization check
34 +@app.get("/api/users/{user_id}")
35 +def get_user(user_id: int):
36 + return db.get_user(user_id) # Any user can access any other user!
37 +
38 +# Good: Verify authorization
39 +@app.get("/api/users/{user_id}")
40 +def get_user(user_id: int, current_user: User = Depends(get_current_user)):
41 + if current_user.id != user_id and not current_user.is_admin:
42 + raise HTTPException(403, "Not authorized")
43 + return db.get_user(user_id)
44 +```
45 +```
46 +
47 +### 2. Cryptographic Failures
48 +
49 +```markdown
50 +## Check for:
51 +- [ ] Sensitive data transmitted in plaintext
52 +- [ ] Weak encryption algorithms (MD5, SHA1 for passwords)
53 +- [ ] Hardcoded secrets
54 +- [ ] Insecure random number generation
55 +
56 +## Secure practices:
57 +```python
58 +# Password hashing
59 +from argon2 import PasswordHasher
60 +ph = PasswordHasher()
61 +hash = ph.hash("password")
62 +ph.verify(hash, "password") # Raises exception if invalid
63 +
64 +# Secure token generation
65 +import secrets
66 +token = secrets.token_urlsafe(32)
67 +
68 +# Never do this:
69 +import hashlib
70 +hash = hashlib.md5(password.encode()).hexdigest() # WEAK!
71 +```
72 +```
73 +
74 +### 3. Injection
75 +
76 +```markdown
77 +## Check for:
78 +- [ ] SQL injection
79 +- [ ] NoSQL injection
80 +- [ ] Command injection
81 +- [ ] LDAP injection
82 +- [ ] XPath injection
83 +
84 +## SQL Injection Prevention:
85 +```python
86 +# Bad: String concatenation
87 +cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")
88 +
89 +# Good: Parameterized queries
90 +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
91 +
92 +# Good: ORM with proper escaping
93 +User.query.filter_by(id=user_id).first()
94 +```
95 +
96 +## Command Injection Prevention:
97 +```python
98 +# Bad
99 +os.system(f"echo {user_input}")
100 +
101 +# Good: Use subprocess with list arguments
102 +subprocess.run(["echo", user_input], shell=False)
103 +
104 +# Better: Avoid shell commands with user input entirely
105 +```
106 +```
107 +
108 +### 4. Insecure Design
109 +
110 +```markdown
111 +## Check for:
112 +- [ ] Missing threat modeling
113 +- [ ] No rate limiting on sensitive operations
114 +- [ ] Lack of defense in depth
115 +- [ ] Missing business logic validation
116 +
117 +## Example:
118 +```python
119 +# Bad: No rate limiting on login
120 +@app.post("/login")
121 +def login(credentials: Credentials):
122 + return authenticate(credentials)
123 +
124 +# Good: Rate limited
125 +from slowapi import Limiter
126 +limiter = Limiter(key_func=get_remote_address)
127 +
128 +@app.post("/login")
129 +@limiter.limit("5/minute")
130 +def login(credentials: Credentials):
131 + return authenticate(credentials)
132 +```
133 +```
134 +
135 +### 5. Security Misconfiguration
136 +
137 +```markdown
138 +## Check for:
139 +- [ ] Default credentials in use
140 +- [ ] Unnecessary features enabled
141 +- [ ] Missing security headers
142 +- [ ] Verbose error messages in production
143 +- [ ] Outdated software
144 +
145 +## Security Headers:
146 +```python
147 +# Flask example
148 +@app.after_request
149 +def add_security_headers(response):
150 + response.headers['X-Content-Type-Options'] = 'nosniff'
151 + response.headers['X-Frame-Options'] = 'DENY'
152 + response.headers['X-XSS-Protection'] = '1; mode=block'
153 + response.headers['Strict-Transport-Security'] = 'max-age=31536000; includeSubDomains'
154 + response.headers['Content-Security-Policy'] = "default-src 'self'"
155 + return response
156 +```
157 +```
158 +
159 +### 6. Vulnerable Components
160 +
161 +```markdown
162 +## Check for:
163 +- [ ] Outdated dependencies
164 +- [ ] Known vulnerable packages
165 +- [ ] Unmaintained libraries
166 +
167 +## Tools:
168 +```bash
169 +# Python
170 +pip-audit
171 +safety check -r requirements.txt
172 +
173 +# JavaScript
174 +npm audit
175 +yarn audit
176 +
177 +# General
178 +snyk test
179 +```
180 +```
181 +
182 +### 7. Authentication Failures
183 +
184 +```markdown
185 +## Check for:
186 +- [ ] Weak password policies
187 +- [ ] Missing MFA option
188 +- [ ] Session fixation
189 +- [ ] Insecure session management
190 +
191 +## Secure Session Management:
192 +```python
193 +# Secure session configuration
194 +app.config.update(
195 + SESSION_COOKIE_SECURE=True, # HTTPS only
196 + SESSION_COOKIE_HTTPONLY=True, # No JavaScript access
197 + SESSION_COOKIE_SAMESITE='Lax', # CSRF protection
198 + PERMANENT_SESSION_LIFETIME=3600 # 1 hour timeout
199 +)
200 +
201 +# Regenerate session on login
202 +@app.route('/login', methods=['POST'])
203 +def login():
204 + if authenticate(request.form):
205 + session.regenerate() # Prevent session fixation
206 + session['user_id'] = user.id
207 +```
208 +```
209 +
210 +### 8. Data Integrity Failures
211 +
212 +```markdown
213 +## Check for:
214 +- [ ] Missing integrity checks on critical data
215 +- [ ] Insecure deserialization
216 +- [ ] Missing code signing
217 +
218 +## Secure Deserialization:
219 +```python
220 +# Bad: Pickle with untrusted data
221 +import pickle
222 +data = pickle.loads(untrusted_data) # DANGEROUS!
223 +
224 +# Good: Use safe serialization
225 +import json
226 +data = json.loads(untrusted_data)
227 +
228 +# If you must use pickle, sign and verify
229 +import hmac
230 +def safe_pickle_loads(data, key):
231 + signature = data[:32]
232 + pickled = data[32:]
233 + expected = hmac.new(key, pickled, 'sha256').digest()
234 + if not hmac.compare_digest(signature, expected):
235 + raise ValueError("Invalid signature")
236 + return pickle.loads(pickled)
237 +```
238 +```
239 +
240 +### 9. Logging & Monitoring Failures
241 +
242 +```markdown
243 +## Check for:
244 +- [ ] Sensitive data in logs
245 +- [ ] Missing audit logs
246 +- [ ] No alerting for security events
247 +- [ ] Logs not protected
248 +
249 +## Secure Logging:
250 +```python
251 +import logging
252 +
253 +# Configure secure logging
254 +logging.basicConfig(
255 + level=logging.INFO,
256 + format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
257 +)
258 +
259 +# Sanitize sensitive data
260 +def sanitize_log(data):
261 + sensitive_keys = ['password', 'token', 'api_key', 'ssn']
262 + return {k: '***' if k in sensitive_keys else v for k, v in data.items()}
263 +
264 +# Log security events
265 +def log_security_event(event_type, details):
266 + logger.warning(f"SECURITY: {event_type} - {sanitize_log(details)}")
267 +```
268 +```
269 +
270 +### 10. Server-Side Request Forgery (SSRF)
271 +
272 +```markdown
273 +## Check for:
274 +- [ ] URL parameters used for server requests
275 +- [ ] Unvalidated redirects
276 +- [ ] Internal service exposure
277 +
278 +## Prevention:
279 +```python
280 +from urllib.parse import urlparse
281 +import ipaddress
282 +
283 +ALLOWED_HOSTS = ['api.example.com', 'cdn.example.com']
284 +BLOCKED_NETWORKS = [
285 + ipaddress.ip_network('10.0.0.0/8'),
286 + ipaddress.ip_network('172.16.0.0/12'),
287 + ipaddress.ip_network('192.168.0.0/16'),
288 + ipaddress.ip_network('127.0.0.0/8'),
289 +]
290 +
291 +def is_safe_url(url):
292 + try:
293 + parsed = urlparse(url)
294 +
295 + # Check allowed hosts
296 + if parsed.hostname not in ALLOWED_HOSTS:
297 + return False
298 +
299 + # Check not internal IP
300 + ip = ipaddress.ip_address(parsed.hostname)
301 + for network in BLOCKED_NETWORKS:
302 + if ip in network:
303 + return False
304 +
305 + return True
306 + except:
307 + return False
308 +```
309 +```
310 +
311 +## Security Audit Process
312 +
313 +### 1. Information Gathering
314 +
315 +```markdown
316 +- [ ] Identify all entry points (APIs, forms, file uploads)
317 +- [ ] Map authentication and authorization flows
318 +- [ ] Document data flows
319 +- [ ] List third-party integrations
320 +- [ ] Review infrastructure configuration
321 +```
322 +
323 +### 2. Automated Scanning
324 +
325 +```bash
326 +# Web application scanning
327 +nikto -h https://target.com
328 +nuclei -u https://target.com -t cves/
329 +
330 +# Dependency scanning
331 +npm audit
332 +pip-audit
333 +
334 +# Static analysis
335 +bandit -r ./src # Python
336 +semgrep --config auto ./src # Multi-language
337 +```
338 +
339 +### 3. Manual Testing
340 +
341 +```markdown
342 +## Input Validation
343 +- [ ] Test with SQL injection payloads
344 +- [ ] Test with XSS payloads
345 +- [ ] Test with path traversal (../)
346 +- [ ] Test file upload restrictions
347 +
348 +## Authentication
349 +- [ ] Test password reset flow
350 +- [ ] Test session timeout
351 +- [ ] Test concurrent session handling
352 +- [ ] Test remember me functionality
353 +
354 +## Authorization
355 +- [ ] Test horizontal privilege escalation
356 +- [ ] Test vertical privilege escalation
357 +- [ ] Test API endpoint permissions
358 +```
359 +
360 +### 4. Report Template
361 +
362 +```markdown
363 +# Security Audit Report
364 +
365 +## Executive Summary
366 +[Brief overview of findings]
367 +
368 +## Scope
369 +- Systems tested:
370 +- Testing period:
371 +- Methodology:
372 +
373 +## Findings
374 +
375 +### Critical
376 +| ID | Title | Impact | CVSS |
377 +|----|-------|--------|------|
378 +| C1 | SQL Injection in login | Data breach | 9.8 |
379 +
380 +### High
381 +[Similar table]
382 +
383 +### Medium
384 +[Similar table]
385 +
386 +### Low
387 +[Similar table]
388 +
389 +## Detailed Findings
390 +
391 +### C1: SQL Injection in Login Form
392 +
393 +**Description**: The login form is vulnerable to SQL injection...
394 +
395 +**Impact**: An attacker could bypass authentication and access any account...
396 +
397 +**Proof of Concept**:
398 +```
399 +Username: ' OR '1'='1
400 +Password: anything
401 +```
402 +
403 +**Recommendation**: Use parameterized queries...
404 +
405 +**References**:
406 +- CWE-89
407 +- OWASP SQL Injection
408 +```
409 +
410 +## Quick Reference
411 +
412 +### Input Validation
413 +
414 +```python
415 +import re
416 +from html import escape
417 +
418 +def sanitize_input(user_input: str) -> str:
419 + # Remove/escape HTML
420 + sanitized = escape(user_input)
421 +
422 + # Limit length
423 + sanitized = sanitized[:1000]
424 +
425 + # Remove null bytes
426 + sanitized = sanitized.replace('\x00', '')
427 +
428 + return sanitized
429 +
430 +def validate_email(email: str) -> bool:
431 + pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
432 + return bool(re.match(pattern, email))
433 +```
434 +
435 +### Environment Configuration
436 +
437 +```python
438 +# Never commit secrets!
439 +import os
440 +from dotenv import load_dotenv
441 +
442 +load_dotenv()
443 +
444 +DATABASE_URL = os.getenv('DATABASE_URL')
445 +SECRET_KEY = os.getenv('SECRET_KEY')
446 +API_KEY = os.getenv('API_KEY')
447 +
448 +# Verify all required env vars are set
449 +required = ['DATABASE_URL', 'SECRET_KEY', 'API_KEY']
450 +missing = [v for v in required if not os.getenv(v)]
451 +if missing:
452 + raise RuntimeError(f"Missing environment variables: {missing}")
453 +```
skills/builtin/tdd/SKILL.md new
+229
@@ -0,0 +1,229 @@
1 +---
2 +name: "tdd"
3 +description: "Test-Driven Development workflow. Write tests first, then implement code to make them pass. Use when implementing features or fixing bugs."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["testing", "tdd", "development", "quality", "best-practices"]
7 +trigger_patterns:
8 + - "test first"
9 + - "tdd"
10 + - "write tests"
11 + - "test-driven"
12 + - "unit test"
13 +---
14 +
15 +# Test-Driven Development (TDD) Skill
16 +
17 +**CRITICAL**: Write tests BEFORE writing implementation code. This ensures code is testable and meets requirements.
18 +
19 +## The TDD Cycle
20 +
21 +```
22 + ┌─────────────────────────────────────┐
23 + │ │
24 + │ RED → GREEN → REFACTOR → Repeat │
25 + │ │
26 + └─────────────────────────────────────┘
27 +```
28 +
29 +1. **RED**: Write a failing test that defines expected behavior
30 +2. **GREEN**: Write minimum code to make the test pass
31 +3. **REFACTOR**: Clean up while keeping tests green
32 +4. **Repeat**: Add next test case
33 +
34 +## When to Use
35 +
36 +Activate TDD when:
37 +- Implementing new features
38 +- Fixing bugs (write test that reproduces bug first)
39 +- Refactoring existing code
40 +- Adding edge case handling
41 +
42 +## The TDD Process
43 +
44 +### Phase 1: Understand Requirements
45 +
46 +Before writing any code:
47 +1. Clarify what the feature should do
48 +2. Identify inputs, outputs, and edge cases
49 +3. List test cases needed
50 +
51 +```markdown
52 +## Feature: [Name]
53 +### Happy Path Cases
54 +- [ ] Test case 1: Given X, when Y, then Z
55 +- [ ] Test case 2: Given A, when B, then C
56 +
57 +### Edge Cases
58 +- [ ] Empty input
59 +- [ ] Invalid input
60 +- [ ] Boundary values
61 +
62 +### Error Cases
63 +- [ ] What should happen when X fails?
64 +```
65 +
66 +### Phase 2: RED - Write Failing Test
67 +
68 +Write a test that:
69 +1. Describes the expected behavior
70 +2. Fails for the right reason (not implementation exists yet)
71 +3. Is simple and focused
72 +
73 +```python
74 +# Python example
75 +def test_calculate_total_with_discount():
76 + """Should apply 10% discount for orders over $100"""
77 + order = Order(items=[Item(price=150)])
78 +
79 + result = order.calculate_total()
80 +
81 + assert result == 135.00 # 150 - 10% = 135
82 +```
83 +
84 +```javascript
85 +// JavaScript example
86 +describe('calculateTotal', () => {
87 + it('should apply 10% discount for orders over $100', () => {
88 + const order = new Order([{ price: 150 }]);
89 +
90 + const result = order.calculateTotal();
91 +
92 + expect(result).toBe(135);
93 + });
94 +});
95 +```
96 +
97 +### Phase 3: GREEN - Make Test Pass
98 +
99 +Write the simplest code that makes the test pass:
100 +1. Don't over-engineer
101 +2. Don't add features the test doesn't require
102 +3. It's okay if code is ugly - we'll refactor next
103 +
104 +```python
105 +def calculate_total(self):
106 + total = sum(item.price for item in self.items)
107 + if total > 100:
108 + total = total * 0.9 # 10% discount
109 + return total
110 +```
111 +
112 +### Phase 4: REFACTOR - Clean Up
113 +
114 +Improve code quality while keeping tests green:
115 +1. Remove duplication
116 +2. Improve naming
117 +3. Extract methods if needed
118 +4. Run tests after each change
119 +
120 +```python
121 +DISCOUNT_THRESHOLD = 100
122 +DISCOUNT_RATE = 0.10
123 +
124 +def calculate_total(self):
125 + subtotal = self._calculate_subtotal()
126 + discount = self._calculate_discount(subtotal)
127 + return subtotal - discount
128 +
129 +def _calculate_subtotal(self):
130 + return sum(item.price for item in self.items)
131 +
132 +def _calculate_discount(self, subtotal):
133 + if subtotal > DISCOUNT_THRESHOLD:
134 + return subtotal * DISCOUNT_RATE
135 + return 0
136 +```
137 +
138 +### Phase 5: Repeat
139 +
140 +Add the next test case and repeat the cycle.
141 +
142 +## Test Patterns
143 +
144 +### Arrange-Act-Assert (AAA)
145 +
146 +```python
147 +def test_user_creation():
148 + # Arrange - set up test data
149 + user_data = {"name": "Alice", "email": "alice@example.com"}
150 +
151 + # Act - perform the action
152 + user = User.create(user_data)
153 +
154 + # Assert - verify the result
155 + assert user.name == "Alice"
156 + assert user.email == "alice@example.com"
157 +```
158 +
159 +### Given-When-Then (BDD style)
160 +
161 +```python
162 +def test_user_login():
163 + # Given a registered user
164 + user = create_user(email="test@example.com", password="secret")
165 +
166 + # When they attempt to login with correct credentials
167 + result = login(email="test@example.com", password="secret")
168 +
169 + # Then they should be authenticated
170 + assert result.success == True
171 + assert result.token is not None
172 +```
173 +
174 +## Common Test Types
175 +
176 +### Unit Tests
177 +- Test single functions/methods in isolation
178 +- Mock external dependencies
179 +- Fast execution
180 +
181 +### Integration Tests
182 +- Test multiple components together
183 +- Use real databases (test instances)
184 +- Slower but more realistic
185 +
186 +### End-to-End Tests
187 +- Test full user workflows
188 +- Run against complete system
189 +- Slowest but most comprehensive
190 +
191 +## Anti-Patterns to Avoid
192 +
193 +- **Test After**: Writing tests after implementation defeats the purpose
194 +- **Testing Implementation**: Test behavior, not implementation details
195 +- **Brittle Tests**: Tests shouldn't break when refactoring
196 +- **Skipping Refactor**: Technical debt accumulates without refactoring
197 +- **Too Many Mocks**: Over-mocking makes tests meaningless
198 +
199 +## Example TDD Session
200 +
201 +**User**: "Implement a password validator"
202 +
203 +**Agent Response**:
204 +> Let me implement this using TDD:
205 +>
206 +> ## Test Cases to Cover
207 +> 1. Password must be at least 8 characters
208 +> 2. Password must contain uppercase letter
209 +> 3. Password must contain number
210 +> 4. Password must contain special character
211 +>
212 +> ## RED: First Test
213 +> ```python
214 +> def test_rejects_short_password():
215 +> result = validate_password("short")
216 +> assert result.valid == False
217 +> assert "at least 8 characters" in result.errors
218 +> ```
219 +>
220 +> ## GREEN: Minimal Implementation
221 +> ```python
222 +> def validate_password(password):
223 +> errors = []
224 +> if len(password) < 8:
225 +> errors.append("Password must be at least 8 characters")
226 +> return ValidationResult(valid=len(errors) == 0, errors=errors)
227 +> ```
228 +>
229 +> [Continues with next test case...]
skills/frameworks/agent-zero-dev/README.md new
+166
@@ -0,0 +1,166 @@
1 +# Agent Zero Development Framework
2 +
3 +A comprehensive development framework for extending and building features for the Agent Zero AI framework.
4 +
5 +## Overview
6 +
7 +This framework provides everything you need to extend Agent Zero:
8 +
9 +- 🛠️ **Code Generators** - Scaffold tools, extensions, skills, and APIs
10 +- 📚 **Documentation** - Architecture guides, best practices, and quickstart
11 +- 🧩 **Templates** - Boilerplate code following framework patterns
12 +- 🎯 **Examples** - Real-world patterns and use cases
13 +
14 +## Quick Start
15 +
16 +```bash
17 +# Create a new tool
18 +python scripts/create_tool.py MyTool "Description of what it does"
19 +
20 +# Create an extension
21 +python scripts/create_extension.py agent_init MyExtension "What it does"
22 +
23 +# Create a skill
24 +python scripts/create_skill.py my-skill "Skill description"
25 +
26 +# Create an API endpoint
27 +python scripts/create_api.py MyEndpoint "What it does"
28 +```
29 +
30 +## What's Included
31 +
32 +### Scripts
33 +
34 +| Script | Purpose | Usage |
35 +|--------|---------|-------|
36 +| `create_tool.py` | Generate tool boilerplate | `python create_tool.py ToolName "Description"` |
37 +| `create_extension.py` | Generate extension boilerplate | `python create_extension.py hook_point ExtName` |
38 +| `create_skill.py` | Generate skill boilerplate | `python create_skill.py skill-name "Description"` |
39 +| `create_api.py` | Generate API endpoint boilerplate | `python create_api.py EndpointName "Description"` |
40 +
41 +### Documentation
42 +
43 +| Document | Contents |
44 +|----------|----------|
45 +| [SKILL.md](SKILL.md) | Main framework documentation |
46 +| [docs/quickstart.md](docs/quickstart.md) | 5-minute quickstart guide |
47 +| [docs/architecture.md](docs/architecture.md) | Deep dive into architecture |
48 +| [docs/best-practices.md](docs/best-practices.md) | Coding standards and patterns |
49 +
50 +### Directory Structure
51 +
52 +```
53 +agent-zero-dev/
54 +├── SKILL.md # Main skill documentation
55 +├── README.md # This file
56 +├── scripts/ # Code generator scripts
57 +│ ├── create_tool.py
58 +│ ├── create_extension.py
59 +│ ├── create_skill.py
60 +│ └── create_api.py
61 +├── templates/ # Placeholder for templates
62 +└── docs/ # Additional documentation
63 + ├── quickstart.md
64 + ├── architecture.md
65 + └── best-practices.md
66 +```
67 +
68 +## Usage
69 +
70 +### Activating This Skill
71 +
72 +This skill activates automatically when you mention:
73 +- "extend agent zero"
74 +- "create a tool"
75 +- "build agent zero feature"
76 +- "agent zero development"
77 +
78 +### Example Workflows
79 +
80 +#### Creating a Weather Tool
81 +
82 +```bash
83 +# 1. Generate the tool
84 +python scripts/create_tool.py WeatherLookup "Get weather for a location"
85 +
86 +# 2. Edit /a0/python/tools/weather_lookup.py
87 +# - Add your weather API logic
88 +# - Update docstrings
89 +
90 +# 3. Restart Agent Zero
91 +# - The tool loads automatically
92 +```
93 +
94 +#### Creating a Custom Skill
95 +
96 +```bash
97 +# 1. Generate the skill
98 +python scripts/create_skill.py data-processor "Process CSV and JSON data"
99 +
100 +# 2. Edit /a0/skills/custom/data-processor/SKILL.md
101 +# - Add trigger patterns
102 +# - Write step-by-step instructions
103 +
104 +# 3. Test it
105 +# "Use data-processor to analyze my CSV"
106 +```
107 +
108 +## Architecture Overview
109 +
110 +Agent Zero is built on these extension points:
111 +
112 +1. **Tools** - Agent capabilities (web search, code execution)
113 +2. **Extensions** - Lifecycle hooks (initialization, message processing)
114 +3. **Skills** - Reusable instruction bundles (SKILL.md standard)
115 +4. **APIs** - Web UI endpoints (FastAPI)
116 +5. **Subordinates** - Specialized agent profiles
117 +6. **Projects** - Isolated workspaces with custom config
118 +
119 +## Development Workflow
120 +
121 +```
122 +1. Brainstorm → Identify what to build
123 +2. Plan → Choose the right extension point
124 +3. Scaffold → Use scripts to generate boilerplate
125 +4. Implement → Fill in your logic
126 +5. Test → Verify with the agent
127 +6. Refine → Iterate based on results
128 +```
129 +
130 +## Best Practices
131 +
132 +- ✅ Follow existing patterns in the codebase
133 +- ✅ Write clear docstrings and comments
134 +- ✅ Handle errors gracefully
135 +- ✅ Test thoroughly before deploying
136 +- ✅ Update documentation
137 +
138 +## Contributing
139 +
140 +When adding to this framework:
141 +
142 +1. Follow the SKILL.md standard
143 +2. Include examples in documentation
144 +3. Test scripts before committing
145 +4. Update this README
146 +
147 +## Resources
148 +
149 +- [Agent Zero Main Documentation](https://github.com/frdel/agent-zero)
150 +- [SKILL.md Standard](https://github.com/anthropics/skills/blob/main/SKILL.md)
151 +- [Python Async/Await Guide](https://docs.python.org/3/library/asyncio.html)
152 +- [FastAPI Documentation](https://fastapi.tiangolo.com/)
153 +
154 +## License
155 +
156 +Part of the Agent Zero framework - follow the same license terms.
157 +
158 +## Support
159 +
160 +- Check [docs/troubleshooting.md](docs/troubleshooting.md) (if exists)
161 +- Review [docs/best-practices.md](docs/best-practices.md)
162 +- Examine existing code in `/a0/python/`
163 +
164 +---
165 +
166 +**Ready to extend Agent Zero?** Start with [docs/quickstart.md](docs/quickstart.md)!
skills/frameworks/agent-zero-dev/SKILL.md new
+705
@@ -0,0 +1,705 @@
1 +---
2 +name: "agent-zero-dev"
3 +description: "Development framework for extending and building features for the Agent Zero AI framework. Provides patterns, templates, and best practices for creating tools, extensions, skills, API endpoints, subordinate profiles, and framework components."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["development", "framework", "agent-zero", "extending", "tools", "extensions", "skills", "api"]
7 +trigger_patterns:
8 + - "extend agent zero"
9 + - "agent zero development"
10 + - "build agent zero feature"
11 + - "create agent zero tool"
12 + - "add extension"
13 + - "framework development"
14 + - "agent zero skill"
15 +---
16 +
17 +# Agent Zero Development Framework
18 +
19 +This framework provides comprehensive guidance for extending and building features for the Agent Zero AI framework. Use this skill when you need to:
20 +
21 +- Create new **Tools** for agent capabilities
22 +- Add **Extensions** to hook into framework lifecycle
23 +- Build **Skills** following the SKILL.md standard
24 +- Develop **API Endpoints** for the Web UI
25 +- Create **Subordinate Profiles** for specialized agents
26 +- Extend **Projects** with custom configuration
27 +- Understand framework **Architecture** and patterns
28 +
29 +## Quick Start
30 +
31 +Choose your extension point:
32 +
33 +| Component | Use Case | Location |
34 +|-----------|----------|----------|
35 +| **Tools** | Add agent capabilities (web search, code execution) | `python/tools/` |
36 +| **Extensions** | Hook into lifecycle events | `python/extensions/<hook_point>/` |
37 +| **Skills** | Create reusable instruction bundles | `skills/custom/<skill-name>/` |
38 +| **API Endpoints** | Add Web UI functionality | `python/api/` |
39 +| **Subordinates** | Create specialized agent profiles | `agents/<profile>/` |
40 +| **Projects** | Project-specific configuration | `.a0proj/` |
41 +
42 +---
43 +
44 +## Architecture Overview
45 +
46 +### Core Components
47 +
48 +```
49 +Agent Zero Framework Architecture
50 +├── python/
51 +│ ├── tools/ # Agent capabilities (inherit from Tool)
52 +│ ├── extensions/ # Lifecycle hooks (numbered execution)
53 +│ ├── api/ # FastAPI endpoints (inherit from ApiHandler)
54 +│ └── helpers/ # Utility functions and base classes
55 +├── skills/
56 +│ ├── builtin/ # Built-in skills (system)
57 +│ ├── custom/ # User-created skills
58 +│ └── frameworks/ # Multi-phase framework skills
59 +├── agents/
60 +│ └── <profile>/ # Subordinate agent profiles
61 +├── memory/ # FAISS-based vector memory
62 +└── tmp/
63 + └── chats/ # Conversation storage
64 +```
65 +
66 +### Key Patterns
67 +
68 +1. **Extensions execute in numeric order** (`_10_*.py`, `_20_*.py`, etc.)
69 +2. **Tools inherit from `Tool` base class** with `execute()` method
70 +3. **Skills use progressive disclosure** (metadata → content → scripts)
71 +4. **Shared AgentContext** enables memory persistence across agents
72 +5. **Async/await throughout** for non-blocking operations
73 +
74 +---
75 +
76 +## Creating Tools
77 +
78 +Tools are the primary way agents interact with the world. Each tool inherits from the `Tool` base class.
79 +
80 +### Tool Structure
81 +
82 +```python
83 +# python/tools/my_tool.py
84 +from python.helpers.tool import Tool, Response
85 +
86 +class MyTool(Tool):
87 + """
88 + Brief description of what this tool does.
89 +
90 + Arguments (tool_args):
91 + - arg1: Description of first argument
92 + - arg2: Description of second argument
93 + """
94 +
95 + async def execute(self, **kwargs) -> Response:
96 + # Get arguments from kwargs or self.args
97 + arg1 = kwargs.get("arg1") or self.args.get("arg1")
98 + arg2 = kwargs.get("arg2") or self.args.get("arg2")
99 +
100 + # Tool logic here
101 + result = await self.do_something(arg1, arg2)
102 +
103 + return Response(
104 + message=result,
105 + break_loop=False # Set True to end agent loop
106 + )
107 +
108 + async def do_something(self, arg1, arg2):
109 + # Implement tool functionality
110 + pass
111 +```
112 +
113 +### Tool Best Practices
114 +
115 +1. **Always document args** in the class docstring
116 +2. **Use `Response` objects** for consistent return format
117 +3. **Handle errors gracefully** - return error message, don't crash
118 +4. **Access agent context** via `self.agent.context`
119 +5. **Use kwargs fallback** to `self.args` for flexibility
120 +
121 +### Example: Complete Tool
122 +
123 +```python
124 +# python/tools/data_processor.py
125 +from python.helpers.tool import Tool, Response
126 +import json
127 +
128 +class DataProcessor(Tool):
129 + """
130 + Process and transform data structures.
131 +
132 + Arguments (tool_args):
133 + - operation: The operation to perform (filter, map, reduce)
134 + - data: JSON data to process
135 + - key: Key to filter/sort by (for filter/sort operations)
136 + - value: Value to filter by (for filter operation)
137 + """
138 +
139 + async def execute(self, **kwargs) -> Response:
140 + try:
141 + operation = kwargs.get("operation") or self.args.get("operation", "")
142 + data_str = kwargs.get("data") or self.args.get("data", "[]")
143 + key = kwargs.get("key") or self.args.get("key")
144 + value = kwargs.get("value") or self.args.get("value")
145 +
146 + data = json.loads(data_str)
147 +
148 + if operation == "filter":
149 + result = [item for item in data if item.get(key) == value]
150 + elif operation == "sort":
151 + result = sorted(data, key=lambda x: x.get(key))
152 + else:
153 + return Response(message=f"Unknown operation: {operation}", break_loop=False)
154 +
155 + return Response(
156 + message=json.dumps(result, indent=2),
157 + break_loop=False
158 + )
159 + except Exception as e:
160 + return Response(message=f"Error processing data: {e}", break_loop=False)
161 +```
162 +
163 +---
164 +
165 +## Creating Extensions
166 +
167 +Extensions hook into specific points in the agent lifecycle. They execute in numeric order.
168 +
169 +### Extension Hook Points
170 +
171 +| Hook Point | When It Fires | Use For |
172 +|------------|---------------|---------|
173 +| `agent_init` | Agent initialization | Loading configs, setting defaults |
174 +| `message_loop_start` | Before message processing | Pre-processing, logging |
175 +| `message_loop_end` | After message processing | Cleanup, post-processing |
176 +| `before_main_llm_call` | Before LLM API call | Modifying prompts, adding context |
177 +| `response_stream_start` | When response streaming begins | Initializing stream handlers |
178 +| `response_stream_chunk` | Per response chunk | Transforming output |
179 +| `response_stream_end` | When streaming ends | Finalizing, cleanup |
180 +| `tool_execute_before` | Before tool execution | Validation, logging |
181 +| `tool_execute_after` | After tool execution | Post-processing results |
182 +
183 +### Extension Structure
184 +
185 +```python
186 +# python/extensions/<hook_point>/_10_my_extension.py
187 +from python.helpers.extension import Extension
188 +from python.helpers.print_style import PrintStyle
189 +
190 +class MyExtension(Extension):
191 + """
192 + Brief description of extension purpose.
193 + """
194 +
195 + async def execute(self, **kwargs):
196 + # Access the agent
197 + agent = self.agent
198 + context = agent.context
199 +
200 + # Extension logic
201 + PrintStyle.hint("MyExtension executing...")
202 +
203 + # Modify data if needed (check kwargs for hook-specific data)
204 + data = kwargs.get("data", {})
205 + data["modified"] = True
206 +
207 + # Return modified data if applicable
208 + return data
209 +```
210 +
211 +### Extension Execution Order
212 +
213 +Extensions execute in numeric order based on filename prefix:
214 +
215 +```
216 +_10_load_config.py # Runs first
217 +_20_validate.py # Runs second
218 +_30_process.py # Runs third
219 +```
220 +
221 +Use 10-number increments to leave room for future extensions.
222 +
223 +### Example: Agent Init Extension
224 +
225 +```python
226 +# python/extensions/agent_init/_15_load_custom_config.py
227 +from python.helpers.extension import Extension
228 +from python.helpers import files
229 +import json
230 +
231 +class LoadCustomConfig(Extension):
232 + """
233 + Load custom configuration from .a0proj/config.json
234 + """
235 +
236 + async def execute(self, **kwargs):
237 + agent = self.agent
238 + context = agent.context
239 +
240 + config_path = files.get_abs_path(".a0proj/config.json")
241 + if files.exists(config_path):
242 + with open(config_path, 'r') as f:
243 + config = json.load(f)
244 + context.data["custom_config"] = config
245 +
246 + return kwargs.get("data", {})
247 +```
248 +
249 +---
250 +
251 +## Creating Skills
252 +
253 +Skills are reusable instruction bundles following the SKILL.md standard.
254 +
255 +### Skill Directory Structure
256 +
257 +```
258 +skills/custom/my-skill/
259 +├── SKILL.md # Required: Main skill file
260 +├── scripts/ # Optional: Helper scripts
261 +│ ├── helper.py
262 +│ └── process.sh
263 +├── templates/ # Optional: Templates
264 +│ └── template.md
265 +└── docs/ # Optional: Additional docs
266 + └── examples.md
267 +```
268 +
269 +### SKILL.md Format
270 +
271 +```yaml
272 +---
273 +name: "skill-name"
274 +description: "Clear description of what this skill does and when to use it"
275 +version: "1.0.0"
276 +author: "Your Name"
277 +tags: ["category1", "category2"]
278 +trigger_patterns:
279 + - "keyword1"
280 + - "phrase that triggers this"
281 +---
282 +
283 +# Skill Title
284 +
285 +## When to Use
286 +Describe trigger conditions and use cases.
287 +
288 +## The Process
289 +Step-by-step instructions for the agent to follow.
290 +
291 +### Step 1: First Action
292 +Details...
293 +
294 +### Step 2: Second Action
295 +Details...
296 +
297 +## Examples
298 +Show sample interactions.
299 +
300 +## Scripts
301 +Reference any helper scripts:
302 +- `scripts/helper.py` - Does X
303 +- `scripts/process.sh` - Does Y
304 +
305 +## Tips
306 +Additional guidance and best practices.
307 +```
308 +
309 +### Using Skills
310 +
311 +```python
312 +# Load skill metadata
313 +await skills_tool.execute(method="list")
314 +
315 +# Load full skill content
316 +await skills_tool.execute(method="load", skill_name="my-skill")
317 +
318 +# Execute skill script
319 +await skills_tool.execute(
320 + method="execute_script",
321 + skill_name="my-skill",
322 + script_path="scripts/helper.py",
323 + script_args={"input": "value"},
324 + arg_style="positional" # or "named" or "env"
325 +)
326 +```
327 +
328 +---
329 +
330 +## Creating API Endpoints
331 +
332 +API endpoints serve the Web UI and external clients using FastAPI.
333 +
334 +### API Endpoint Structure
335 +
336 +```python
337 +# python/api/my_endpoint.py
338 +from python.helpers.api import ApiHandler, Request, Response
339 +from agent import AgentContext
340 +
341 +class MyEndpoint(ApiHandler):
342 + """
343 + Handle requests for /api/my-endpoint
344 + """
345 +
346 + async def process(self, input: dict, request: Request) -> dict | Response:
347 + # Get query params or JSON body
348 + param = input.get("param", "default")
349 +
350 + # Get or create agent context
351 + ctxid = input.get("context", "")
352 + context = self.use_context(ctxid)
353 +
354 + # Process request
355 + result = await self.process_request(param, context)
356 +
357 + return {
358 + "result": result,
359 + "context": context.id,
360 + }
361 +
362 + async def process_request(self, param, context):
363 + # Implement endpoint logic
364 + return {"processed": param}
365 +```
366 +
367 +### API Best Practices
368 +
369 +1. **Use `ApiHandler` base class** for consistent request/response handling
370 +2. **Get context with `self.use_context(ctxid)`** - creates if not exists
371 +3. **Return dict or Response** objects
372 +4. **Handle both GET and POST** if applicable
373 +5. **Use `Request` object** for accessing headers, files, etc.
374 +
375 +### Example: File Upload Endpoint
376 +
377 +```python
378 +# python/api/upload_processor.py
379 +from python.helpers.api import ApiHandler, Request
380 +from werkzeug.utils import secure_filename
381 +import os
382 +
383 +class UploadProcessor(ApiHandler):
384 + async def process(self, input: dict, request: Request) -> dict:
385 + if request.method == "POST":
386 + uploaded_file = request.files.get("file")
387 + if uploaded_file:
388 + filename = secure_filename(uploaded_file.filename)
389 + save_path = f"/tmp/uploads/{filename}"
390 + uploaded_file.save(save_path)
391 +
392 + return {
393 + "success": True,
394 + "filename": filename,
395 + "path": save_path
396 + }
397 +
398 + return {"success": False, "error": "No file provided"}
399 +```
400 +
401 +---
402 +
403 +## Creating Subordinate Profiles
404 +
405 +Subordinates are specialized agents with custom prompts and configurations.
406 +
407 +### Profile Directory Structure
408 +
409 +```
410 +agents/<profile-name>/
411 +├── agent.json # Profile configuration
412 +└── prompts/
413 + ├── system.md # System prompt
414 + └── subordinates.md # Subordinate delegation prompts
415 +```
416 +
417 +### agent.json Configuration
418 +
419 +```json
420 +{
421 + "name": "Specialized Agent",
422 + "description": "What this subordinate specializes in",
423 + "model": "anthropic/claude-sonnet-4-20250514",
424 + "temperature": 0.7,
425 + "max_tokens": 4000,
426 + "allowed_tools": [
427 + "code_execution_tool",
428 + "search_engine",
429 + "call_subordinate"
430 + ],
431 + "prompts": {
432 + "system": "prompts/system.md",
433 + "subordinates": "prompts/subordinates.md"
434 + }
435 +}
436 +```
437 +
438 +### System Prompt Template
439 +
440 +```markdown
441 +# System Prompt for Specialized Agent
442 +
443 +## Your Role
444 +You are a specialized agent focused on [domain].
445 +
446 +## Capabilities
447 +- Expertise in [specific area]
448 +- Use tools: code_execution_tool, search_engine
449 +
450 +## Process
451 +1. Analyze the request
452 +2. Choose appropriate tools
453 +3. Execute and verify results
454 +4. Return structured response
455 +
456 +## Output Format
457 +Always respond with valid JSON:
458 +```json
459 +{
460 + "result": "your result here",
461 + "confidence": 0.95
462 +}
463 +```
464 +```
465 +
466 +### Using Subordinates
467 +
468 +```python
469 +# Call from main agent
470 +call_subordinate(
471 + profile="developer",
472 + message="Implement a Python function to calculate Fibonacci",
473 + reset="true"
474 +)
475 +```
476 +
477 +---
478 +
479 +## Creating Projects
480 +
481 +Projects provide isolated workspaces with custom configuration.
482 +
483 +### Project Structure
484 +
485 +```
486 +/usr/projects/<project-name>/
487 +├── .a0proj/
488 +│ ├── config.json # Project configuration
489 +│ ├── instructions.md # Project-specific instructions
490 +│ └── skills/ # Project-specific skills
491 +└── <project-files>/ # Your project files
492 +```
493 +
494 +### config.json
495 +
496 +```json
497 +{
498 + "name": "My Project",
499 + "description": "Project description",
500 + "default_model": "anthropic/claude-sonnet-4-20250514",
501 + "allowed_tools": ["*"],
502 + "extensions": {
503 + "enabled": ["custom_extension"]
504 + },
505 + "skills": {
506 + "auto_load": ["project-specific-skill"]
507 + }
508 +}
509 +```
510 +
511 +### instructions.md
512 +
513 +```markdown
514 +# Project: My Project
515 +
516 +## Overview
517 +This project does X, Y, Z.
518 +
519 +## Coding Standards
520 +- Use Python 3.12+ features
521 +- Follow PEP 8
522 +- Write tests for all functions
523 +
524 +## Architecture
525 +- API layer in `api/`
526 +- Business logic in `services/`
527 +- Models in `models/`
528 +```
529 +
530 +---
531 +
532 +## Framework Development Workflow
533 +
534 +When building features for Agent Zero itself, follow this workflow:
535 +
536 +### Phase 1: Brainstorming
537 +- Define the problem and solution
538 +- Identify extension points (tool, extension, skill, API)
539 +- Review existing patterns for consistency
540 +
541 +### Phase 2: Planning
542 +- Break work into small tasks (2-5 min each)
543 +- Identify dependencies and order
544 +- Write verification criteria for each task
545 +
546 +### Phase 3: Implementation
547 +- Create feature branch (use git worktrees)
548 +- Follow TDD: test first, then implement
549 +- Match existing code patterns
550 +
551 +### Phase 4: Code Review
552 +- Review against plan
553 +- Check pattern consistency
554 +- Verify tests pass
555 +
556 +### Phase 5: Integration
557 +- Merge to main
558 +- Update documentation
559 +- Test in production context
560 +
561 +---
562 +
563 +## Common Patterns Reference
564 +
565 +### Accessing Context Data
566 +
567 +```python
568 +# Shared across all agents in conversation
569 +context = self.agent.context
570 +data = context.data # dict-like shared memory
571 +
572 +# Store data
573 +data["my_key"] = my_value
574 +
575 +# Retrieve data
576 +value = data.get("my_key", default)
577 +```
578 +
579 +### Using Helpers
580 +
581 +```python
582 +from python.helpers import files, extension, print_style
583 +
584 +# File operations
585 +content = files.read_file("path/to/file")
586 +files.write_file("path/to/file", content)
587 +exists = files.exists("path/to/file")
588 +
589 +# Extensions
590 +await extension.call_extensions("hook_point", agent=agent, data=data)
591 +
592 +# Printing
593 +PrintStyle.hint("Hint message")
594 +PrintStyle.warning("Warning message")
595 +PrintStyle.error("Error message")
596 +```
597 +
598 +### Error Handling
599 +
600 +```python
601 +try:
602 + result = await risky_operation()
603 +except Exception as e:
604 + # Log for debugging
605 + PrintStyle.error(f"Operation failed: {e}")
606 + # Return graceful error to user
607 + return Response(message=f"Error: {e}", break_loop=False)
608 +```
609 +
610 +### Async Patterns
611 +
612 +```python
613 +# Concurrent execution
614 +tasks = [process_item(item) for item in items]
615 +results = await asyncio.gather(*tasks)
616 +
617 +# Timeouts
618 +try:
619 + result = await asyncio.wait_for(operation(), timeout=30)
620 +except asyncio.TimeoutError:
621 + return Response(message="Operation timed out", break_loop=False)
622 +```
623 +
624 +---
625 +
626 +## Testing Your Extensions
627 +
628 +### Manual Testing
629 +
630 +1. **Restart the framework** after code changes
631 +2. **Test with minimal input** first
632 +3. **Check logs** for errors: `docker logs -f agent-zero`
633 +4. **Verify in UI** that changes appear correctly
634 +
635 +### Unit Testing (when available)
636 +
637 +```python
638 +# tests/tools/test_my_tool.py
639 +import pytest
640 +from python.tools.my_tool import MyTool
641 +
642 +@pytest.mark.asyncio
643 +async def test_my_tool():
644 + tool = MyTool()
645 + result = await tool.execute(operation="test", data="{}")
646 + assert "success" in result.message
647 +```
648 +
649 +---
650 +
651 +## Scripts and Templates
652 +
653 +This skill includes helper scripts and templates:
654 +
655 +### Scripts
656 +
657 +| Script | Purpose | Usage |
658 +|--------|---------|-------|
659 +| `scripts/create_tool.py` | Generate tool boilerplate | `python scripts/create_tool.py ToolName` |
660 +| `scripts/create_extension.py` | Generate extension boilerplate | `python scripts/create_extension.py HookPoint ExtensionName` |
661 +| `scripts/create_skill.py` | Generate skill boilerplate | `python scripts/create_skill.py skill-name` |
662 +| `scripts/create_api.py` | Generate API endpoint boilerplate | `python scripts/create_api.py EndpointName` |
663 +
664 +### Templates
665 +
666 +| Template | Purpose |
667 +|----------|---------|
668 +| `templates/tool.py` | Tool boilerplate |
669 +| `templates/extension.py` | Extension boilerplate |
670 +| `templates/SKILL.md` | Skill boilerplate |
671 +| `templates/api.py` | API endpoint boilerplate |
672 +
673 +---
674 +
675 +## Best Practices Summary
676 +
677 +### DO
678 +- ✅ Follow existing patterns and conventions
679 +- ✅ Write clear docstrings and comments
680 +- ✅ Handle errors gracefully
681 +- ✅ Use type hints where applicable
682 +- ✅ Test your changes thoroughly
683 +- ✅ Update documentation
684 +- ✅ Use meaningful names
685 +
686 +### DON'T
687 +- ❌ Break existing functionality
688 +- ❌ Ignore error cases
689 +- ❌ Hardcode paths or values
690 +- ❌ Skip documentation
691 +- ❌ Mix sync and async code carelessly
692 +- ❌ Access internal structures directly when helpers exist
693 +
694 +---
695 +
696 +## Need Help?
697 +
698 +Use this skill by saying:
699 +- "Help me create a new tool for..."
700 +- "I want to add an extension that..."
701 +- "Create a skill for..."
702 +- "Build an API endpoint for..."
703 +- "How do I extend Agent Zero to..."
704 +
705 +I'll guide you through the appropriate patterns and generate boilerplate code!
skills/frameworks/agent-zero-dev/a0dev-create-api/SKILL.md new
+286
@@ -0,0 +1,286 @@
1 +---
2 +name: "a0dev-create-api"
3 +description: "Add Web UI and REST API endpoints for Agent Zero."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["agent-zero-dev", "api", "endpoint", "fastapi", "webui"]
7 +trigger_patterns:
8 + - "create api"
9 + - "new endpoint"
10 + - "add api"
11 + - "api endpoint"
12 + - "/a0dev-create-api"
13 +---
14 +
15 +# Agent Zero Dev: Create API
16 +
17 +API endpoints serve the Web UI and external clients using FastAPI. Each endpoint inherits from `ApiHandler`.
18 +
19 +## API Location
20 +
21 +```
22 +python/api/
23 +├── poll.py # Long-polling for updates
24 +├── chat.py # Chat message handling
25 +├── frameworks.py # Framework management
26 +├── settings.py # Settings management
27 +└── your_endpoint.py # New endpoints go here
28 +```
29 +
30 +## API Endpoint Structure
31 +
32 +```python
33 +# python/api/my_endpoint.py
34 +from python.helpers.api import ApiHandler, Request, Input, Output
35 +
36 +class MyEndpoint(ApiHandler):
37 + """
38 + Handle requests for /api/my-endpoint
39 +
40 + Query params / JSON body:
41 + - param1: Description of param1
42 + - param2: Description of param2
43 + """
44 +
45 + async def process(self, input: Input, request: Request) -> Output:
46 + # Get parameters from input (works for both GET params and POST body)
47 + param1 = input.get("param1", "default")
48 + param2 = input.get("param2")
49 +
50 + try:
51 + # Process the request
52 + result = await self.do_work(param1, param2)
53 +
54 + return {
55 + "ok": True,
56 + "data": result,
57 + }
58 + except Exception as e:
59 + return {
60 + "ok": False,
61 + "error": str(e),
62 + }
63 +
64 + async def do_work(self, param1, param2):
65 + # Implementation
66 + return {"processed": param1}
67 +```
68 +
69 +## Type Definitions
70 +
71 +```python
72 +Input = dict # Request parameters (query or body)
73 +Output = dict | Response # Return dict or FastAPI Response
74 +Request = fastapi.Request # Full request object
75 +```
76 +
77 +## URL Routing
78 +
79 +Endpoints are auto-routed based on filename:
80 +- `my_endpoint.py` → `/api/my_endpoint` or `/api/my-endpoint`
81 +- Class name doesn't affect routing
82 +
83 +## Getting Agent Context
84 +
85 +```python
86 +async def process(self, input: Input, request: Request) -> Output:
87 + # Get context ID from request
88 + ctxid = input.get("context", "")
89 +
90 + # Get or create context (creates if doesn't exist)
91 + context = self.use_context(ctxid)
92 +
93 + # Access context data
94 + data = context.data
95 +
96 + # Get the agent for this context
97 + agent = self.get_context_agent(context)
98 +
99 + return {
100 + "ok": True,
101 + "context": context.id,
102 + }
103 +```
104 +
105 +## Complete Example: Data Query Endpoint
106 +
107 +```python
108 +# python/api/data_query.py
109 +from python.helpers.api import ApiHandler, Request, Input, Output
110 +from dataclasses import asdict
111 +
112 +class DataQuery(ApiHandler):
113 + """
114 + Query and manipulate stored data.
115 +
116 + Actions:
117 + - get: Retrieve data by key
118 + - set: Store data with key
119 + - list: List all keys
120 + - delete: Remove data by key
121 +
122 + Query params / JSON body:
123 + - action: The action to perform
124 + - context: Agent context ID
125 + - key: Data key (for get/set/delete)
126 + - value: Data value (for set)
127 + """
128 +
129 + async def process(self, input: Input, request: Request) -> Output:
130 + action = input.get("action", "list")
131 + ctxid = input.get("context", "")
132 + key = input.get("key")
133 + value = input.get("value")
134 +
135 + try:
136 + context = self.use_context(ctxid)
137 +
138 + if action == "list":
139 + keys = list(context.data.keys())
140 + return {"ok": True, "keys": keys}
141 +
142 + elif action == "get":
143 + if not key:
144 + return {"ok": False, "error": "Key required"}
145 + data = context.data.get(key)
146 + return {"ok": True, "key": key, "value": data}
147 +
148 + elif action == "set":
149 + if not key:
150 + return {"ok": False, "error": "Key required"}
151 + context.data[key] = value
152 + return {"ok": True, "key": key, "stored": True}
153 +
154 + elif action == "delete":
155 + if not key:
156 + return {"ok": False, "error": "Key required"}
157 + if key in context.data:
158 + del context.data[key]
159 + return {"ok": True, "key": key, "deleted": True}
160 +
161 + else:
162 + return {"ok": False, "error": f"Unknown action: {action}"}
163 +
164 + except Exception as e:
165 + return {"ok": False, "error": str(e)}
166 +```
167 +
168 +## Handling File Uploads
169 +
170 +```python
171 +# python/api/file_upload.py
172 +from python.helpers.api import ApiHandler, Request, Input, Output
173 +from fastapi import UploadFile
174 +from python.helpers import files
175 +
176 +class FileUpload(ApiHandler):
177 + """Handle file uploads"""
178 +
179 + async def process(self, input: Input, request: Request) -> Output:
180 + # Access uploaded file from request
181 + form = await request.form()
182 + uploaded_file: UploadFile = form.get("file")
183 +
184 + if not uploaded_file:
185 + return {"ok": False, "error": "No file provided"}
186 +
187 + # Read file content
188 + content = await uploaded_file.read()
189 + filename = uploaded_file.filename
190 +
191 + # Save file
192 + save_path = f"/tmp/uploads/{filename}"
193 + files.write_file(save_path, content.decode())
194 +
195 + return {
196 + "ok": True,
197 + "filename": filename,
198 + "size": len(content),
199 + "path": save_path,
200 + }
201 +```
202 +
203 +## Streaming Responses
204 +
205 +```python
206 +# python/api/stream_data.py
207 +from python.helpers.api import ApiHandler, Request, Input, Output
208 +from fastapi.responses import StreamingResponse
209 +import asyncio
210 +
211 +class StreamData(ApiHandler):
212 + """Stream data to client"""
213 +
214 + async def process(self, input: Input, request: Request) -> Output:
215 + async def generate():
216 + for i in range(10):
217 + yield f"data: {i}\n\n"
218 + await asyncio.sleep(0.5)
219 +
220 + return StreamingResponse(
221 + generate(),
222 + media_type="text/event-stream"
223 + )
224 +```
225 +
226 +## Using the Generator Script
227 +
228 +```bash
229 +python skills/frameworks/agent-zero-dev/scripts/create_api.py \
230 + DataQuery \
231 + "Query and manipulate stored data"
232 +```
233 +
234 +Generates: `python/api/data_query.py`
235 +
236 +## API Best Practices
237 +
238 +### DO
239 +
240 +- ✅ Use `ApiHandler` base class
241 +- ✅ Return consistent response format (`{ok, data/error}`)
242 +- ✅ Document params in docstring
243 +- ✅ Handle errors gracefully
244 +- ✅ Use `self.use_context()` for context management
245 +- ✅ Support both GET and POST where appropriate
246 +
247 +### DON'T
248 +
249 +- ❌ Expose sensitive data
250 +- ❌ Skip input validation
251 +- ❌ Block the event loop
252 +- ❌ Return inconsistent response formats
253 +- ❌ Forget error handling
254 +
255 +## Testing Your API
256 +
257 +1. **Restart Agent Zero** (APIs load at startup)
258 +2. **Test with curl**:
259 + ```bash
260 + curl "http://localhost:8080/api/my_endpoint?param1=value"
261 + ```
262 +3. **Test with browser** (for GET endpoints)
263 +4. **Check logs** for errors
264 +
265 +## Frontend Integration
266 +
267 +APIs are called from the Web UI using:
268 +
269 +```javascript
270 +// webui/js/api.js
271 +import { callJsonApi, fetchApi } from "/js/api.js";
272 +
273 +// JSON POST with CSRF
274 +const result = await callJsonApi("/my_endpoint", { param1: "value" });
275 +
276 +// Raw fetch with CSRF
277 +const response = await fetchApi("/my_endpoint", { method: "GET" });
278 +```
279 +
280 +## Next Steps
281 +
282 +After creating an API:
283 +- Test all actions/parameters
284 +- Add frontend integration if needed
285 +- Document the endpoint
286 +- Consider rate limiting for public APIs
skills/frameworks/agent-zero-dev/a0dev-create-extension/SKILL.md new
+263
@@ -0,0 +1,263 @@
1 +---
2 +name: "a0dev-create-extension"
3 +description: "Hook into Agent Zero lifecycle events with extensions."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["agent-zero-dev", "extension", "lifecycle", "hooks"]
7 +trigger_patterns:
8 + - "create extension"
9 + - "new extension"
10 + - "add extension"
11 + - "lifecycle hook"
12 + - "/a0dev-create-extension"
13 +---
14 +
15 +# Agent Zero Dev: Create Extension
16 +
17 +Extensions hook into specific points in the agent lifecycle. They execute in numeric order based on filename prefix.
18 +
19 +## Extension Hook Points
20 +
21 +| Hook Point | When It Fires | Use For |
22 +|------------|---------------|---------|
23 +| `agent_init` | Agent initialization | Loading configs, setting defaults |
24 +| `message_loop_start` | Before message processing | Pre-processing, logging |
25 +| `message_loop_end` | After message processing | Cleanup, post-processing |
26 +| `message_loop_prompts_after` | After prompts assembled | Adding context to prompts |
27 +| `before_main_llm_call` | Before LLM API call | Modifying prompts |
28 +| `response_stream_start` | Response streaming begins | Initializing handlers |
29 +| `response_stream_chunk` | Per response chunk | Transforming output |
30 +| `response_stream_end` | Streaming ends | Finalizing |
31 +| `tool_execute_before` | Before tool execution | Validation, logging |
32 +| `tool_execute_after` | After tool execution | Post-processing |
33 +| `hist_add_user_message` | User message added | Message interception |
34 +| `system_prompt` | System prompt assembly | Injecting context |
35 +
36 +## Extension Location
37 +
38 +```
39 +python/extensions/
40 +├── agent_init/
41 +│ ├── _10_load_settings.py
42 +│ └── _20_your_extension.py
43 +├── message_loop_start/
44 +├── message_loop_end/
45 +├── before_main_llm_call/
46 +└── <hook_point>/
47 + └── _NN_extension_name.py
48 +```
49 +
50 +## Extension Structure
51 +
52 +```python
53 +# python/extensions/<hook_point>/_NN_my_extension.py
54 +from python.helpers.extension import Extension
55 +from python.helpers.print_style import PrintStyle
56 +
57 +class MyExtension(Extension):
58 + """
59 + Brief description of what this extension does.
60 + """
61 +
62 + async def execute(self, **kwargs):
63 + # Access the agent
64 + agent = self.agent
65 + context = agent.context
66 +
67 + # Extension logic
68 + PrintStyle.hint("MyExtension executing...")
69 +
70 + # Get/modify hook-specific data
71 + data = kwargs.get("data", {})
72 +
73 + # Return data (some hooks expect modified data back)
74 + return data
75 +```
76 +
77 +## Execution Order
78 +
79 +Extensions execute in numeric order based on filename prefix:
80 +
81 +```
82 +_10_first.py # Runs first
83 +_20_second.py # Runs second
84 +_30_third.py # Runs third
85 +_55_yours.py # Your extension
86 +_90_last.py # Runs last
87 +```
88 +
89 +**Convention:** Use 10-number increments to leave room for future extensions.
90 +
91 +## Hook-Specific Examples
92 +
93 +### Agent Init (Load Configuration)
94 +
95 +```python
96 +# python/extensions/agent_init/_15_load_custom_config.py
97 +from python.helpers.extension import Extension
98 +from python.helpers import files
99 +import json
100 +
101 +class LoadCustomConfig(Extension):
102 + """Load custom configuration from .a0proj/config.json"""
103 +
104 + async def execute(self, **kwargs):
105 + agent = self.agent
106 + context = agent.context
107 +
108 + config_path = files.get_abs_path(".a0proj/config.json")
109 + if files.exists(config_path):
110 + with open(config_path, 'r') as f:
111 + config = json.load(f)
112 + context.data["custom_config"] = config
113 +
114 + return kwargs.get("data", {})
115 +```
116 +
117 +### Message Loop Start (Logging)
118 +
119 +```python
120 +# python/extensions/message_loop_start/_10_log_message.py
121 +from python.helpers.extension import Extension
122 +import logging
123 +
124 +class LogMessage(Extension):
125 + """Log incoming messages for debugging"""
126 +
127 + async def execute(self, **kwargs):
128 + agent = self.agent
129 + message = kwargs.get("message", "")
130 +
131 + logging.info(f"Agent {agent.number} received: {message[:100]}...")
132 +
133 + return kwargs.get("data", {})
134 +```
135 +
136 +### System Prompt (Inject Context)
137 +
138 +```python
139 +# python/extensions/system_prompt/_50_inject_project_context.py
140 +from python.helpers.extension import Extension
141 +
142 +class InjectProjectContext(Extension):
143 + """Add project-specific context to system prompt"""
144 +
145 + async def execute(self, **kwargs):
146 + agent = self.agent
147 + context = agent.context
148 +
149 + # Get the prompt being built
150 + prompt_parts = kwargs.get("data", [])
151 +
152 + # Add project context if available
153 + project_info = context.data.get("project_info")
154 + if project_info:
155 + prompt_parts.append(f"\n## Project Context\n{project_info}\n")
156 +
157 + return prompt_parts
158 +```
159 +
160 +### Before LLM Call (Modify Prompt)
161 +
162 +```python
163 +# python/extensions/before_main_llm_call/_40_add_instructions.py
164 +from python.helpers.extension import Extension
165 +
166 +class AddInstructions(Extension):
167 + """Add dynamic instructions before LLM call"""
168 +
169 + async def execute(self, **kwargs):
170 + # Access messages being sent
171 + messages = kwargs.get("messages", [])
172 +
173 + # Modify or add messages
174 + custom_instruction = {
175 + "role": "system",
176 + "content": "Remember to be concise."
177 + }
178 +
179 + # Return modified data
180 + return {"messages": messages + [custom_instruction]}
181 +```
182 +
183 +### Tool Execute After (Post-Process)
184 +
185 +```python
186 +# python/extensions/tool_execute_after/_30_log_tool_result.py
187 +from python.helpers.extension import Extension
188 +from python.helpers.print_style import PrintStyle
189 +
190 +class LogToolResult(Extension):
191 + """Log tool execution results"""
192 +
193 + async def execute(self, **kwargs):
194 + tool_name = kwargs.get("tool_name", "unknown")
195 + result = kwargs.get("result", {})
196 +
197 + PrintStyle.hint(f"Tool {tool_name} returned: {str(result)[:100]}...")
198 +
199 + return kwargs.get("data", {})
200 +```
201 +
202 +## Using the Generator Script
203 +
204 +```bash
205 +python skills/frameworks/agent-zero-dev/scripts/create_extension.py \
206 + agent_init \
207 + LoadProjectSettings \
208 + "Load project-specific settings on agent init"
209 +```
210 +
211 +Generates: `python/extensions/agent_init/_50_load_project_settings.py`
212 +
213 +## Extension Best Practices
214 +
215 +### DO
216 +
217 +- ✅ Use numeric prefixes (10, 20, 30...)
218 +- ✅ Return the data dict (even if unmodified)
219 +- ✅ Document what the extension does
220 +- ✅ Keep extensions focused (single responsibility)
221 +- ✅ Handle errors gracefully
222 +- ✅ Use PrintStyle for logging
223 +
224 +### DON'T
225 +
226 +- ❌ Block the event loop
227 +- ❌ Modify global state carelessly
228 +- ❌ Ignore the return value
229 +- ❌ Use conflicting numeric prefixes
230 +- ❌ Create circular dependencies
231 +
232 +## Accessing Context
233 +
234 +```python
235 +# Agent and context
236 +agent = self.agent
237 +context = agent.context
238 +
239 +# Shared data (persists across agents)
240 +context.data["key"] = value
241 +value = context.data.get("key")
242 +
243 +# Agent-specific data
244 +agent.set_data("key", value)
245 +value = agent.get_data("key")
246 +
247 +# Configuration
248 +config = agent.config
249 +model = config.chat_model
250 +```
251 +
252 +## Testing Extensions
253 +
254 +1. **Add your extension** to the appropriate hook point
255 +2. **Restart Agent Zero** (extensions load at startup)
256 +3. **Trigger the hook** by performing the related action
257 +4. **Check logs** for your output or errors
258 +
259 +## Next Steps
260 +
261 +- Identify which hook point fits your use case
262 +- Start with logging to understand data flow
263 +- Keep extensions small and composable
skills/frameworks/agent-zero-dev/a0dev-create-project/SKILL.md new
+342
@@ -0,0 +1,342 @@
1 +---
2 +name: "a0dev-create-project"
3 +description: "Set up project-specific configuration for Agent Zero workspaces."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["agent-zero-dev", "project", "configuration", "workspace"]
7 +trigger_patterns:
8 + - "create project"
9 + - "new project"
10 + - "setup project"
11 + - "project config"
12 + - "/a0dev-create-project"
13 +---
14 +
15 +# Agent Zero Dev: Create Project
16 +
17 +Projects provide isolated workspaces with custom configuration, instructions, and skills specific to a codebase or task.
18 +
19 +## Project Location
20 +
21 +```
22 +/path/to/your/project/
23 +├── .a0proj/ # Agent Zero project config
24 +│ ├── config.json # Project configuration
25 +│ ├── instructions.md # Project-specific instructions
26 +│ └── skills/ # Project-specific skills
27 +│ └── custom-skill/
28 +│ └── SKILL.md
29 +└── <your-project-files>/ # Your actual project
30 +```
31 +
32 +## Configuration Files
33 +
34 +### .a0proj/config.json
35 +
36 +```json
37 +{
38 + "name": "My Project",
39 + "description": "Brief project description",
40 + "version": "1.0.0",
41 +
42 + "agent": {
43 + "model": "anthropic/claude-sonnet-4-20250514",
44 + "temperature": 0.7
45 + },
46 +
47 + "tools": {
48 + "allowed": ["*"],
49 + "disabled": []
50 + },
51 +
52 + "skills": {
53 + "auto_load": ["project-specific-skill"],
54 + "disabled": []
55 + },
56 +
57 + "extensions": {
58 + "enabled": [],
59 + "disabled": []
60 + },
61 +
62 + "paths": {
63 + "work_dir": ".",
64 + "output_dir": "./output"
65 + }
66 +}
67 +```
68 +
69 +### Configuration Fields
70 +
71 +| Field | Type | Description |
72 +|-------|------|-------------|
73 +| `name` | string | Project display name |
74 +| `description` | string | Brief description |
75 +| `agent.model` | string | Default LLM model |
76 +| `agent.temperature` | float | Response randomness |
77 +| `tools.allowed` | array | Allowed tools (`["*"]` for all) |
78 +| `tools.disabled` | array | Explicitly disabled tools |
79 +| `skills.auto_load` | array | Skills to load automatically |
80 +| `paths.work_dir` | string | Working directory |
81 +
82 +### .a0proj/instructions.md
83 +
84 +```markdown
85 +# Project: [Project Name]
86 +
87 +## Overview
88 +[What this project does and its purpose]
89 +
90 +## Tech Stack
91 +- Language: [Python 3.12+]
92 +- Framework: [FastAPI]
93 +- Database: [PostgreSQL]
94 +- Other: [Docker, Redis]
95 +
96 +## Architecture
97 +[Brief architecture description]
98 +
99 +```
100 +project/
101 +├── api/ # API endpoints
102 +├── services/ # Business logic
103 +├── models/ # Data models
104 +└── tests/ # Test files
105 +```
106 +
107 +## Coding Standards
108 +- Follow [PEP 8 / Standard Style]
109 +- Write tests for all functions
110 +- Use type hints
111 +- Document public APIs
112 +
113 +## Important Files
114 +- `api/main.py` - Entry point
115 +- `services/core.py` - Core logic
116 +- `config.py` - Configuration
117 +
118 +## Commands
119 +- `make dev` - Start development server
120 +- `make test` - Run tests
121 +- `make lint` - Run linter
122 +
123 +## Notes
124 +[Any special considerations or warnings]
125 +```
126 +
127 +## Complete Example: Python API Project
128 +
129 +### .a0proj/config.json
130 +
131 +```json
132 +{
133 + "name": "User API Service",
134 + "description": "REST API for user management",
135 + "version": "1.0.0",
136 +
137 + "agent": {
138 + "model": "anthropic/claude-sonnet-4-20250514",
139 + "temperature": 0.3
140 + },
141 +
142 + "tools": {
143 + "allowed": ["*"],
144 + "disabled": ["browser_tool"]
145 + },
146 +
147 + "skills": {
148 + "auto_load": ["api-development", "testing"],
149 + "disabled": []
150 + },
151 +
152 + "paths": {
153 + "work_dir": ".",
154 + "output_dir": "./generated"
155 + },
156 +
157 + "custom": {
158 + "test_command": "pytest -v",
159 + "lint_command": "ruff check .",
160 + "database": "postgresql://localhost/userdb"
161 + }
162 +}
163 +```
164 +
165 +### .a0proj/instructions.md
166 +
167 +```markdown
168 +# Project: User API Service
169 +
170 +## Overview
171 +REST API service for user management with authentication, profiles, and permissions.
172 +
173 +## Tech Stack
174 +- Python 3.12
175 +- FastAPI
176 +- PostgreSQL
177 +- SQLAlchemy (async)
178 +- Pydantic v2
179 +- pytest
180 +
181 +## Architecture
182 +
183 +```
184 +src/
185 +├── api/
186 +│ ├── routes/ # API endpoints
187 +│ ├── deps.py # Dependencies
188 +│ └── main.py # FastAPI app
189 +├── models/
190 +│ ├── user.py # User model
191 +│ └── base.py # Base model
192 +├── services/
193 +│ ├── auth.py # Authentication
194 +│ └── user.py # User service
195 +├── schemas/
196 +│ └── user.py # Pydantic schemas
197 +└── tests/
198 + ├── conftest.py # Test fixtures
199 + └── test_user.py # User tests
200 +```
201 +
202 +## Coding Standards
203 +- PEP 8 compliance (enforced by ruff)
204 +- Type hints on all functions
205 +- Docstrings for public APIs
206 +- 80%+ test coverage
207 +- Async/await for I/O operations
208 +
209 +## API Conventions
210 +- RESTful endpoints
211 +- JSON request/response
212 +- Standard error format: `{"detail": "message"}`
213 +- Auth via Bearer token
214 +
215 +## Commands
216 +```bash
217 +# Development
218 +uvicorn src.api.main:app --reload
219 +
220 +# Testing
221 +pytest -v --cov=src
222 +
223 +# Linting
224 +ruff check src/
225 +ruff format src/
226 +```
227 +
228 +## Environment Variables
229 +- `DATABASE_URL` - PostgreSQL connection string
230 +- `SECRET_KEY` - JWT signing key
231 +- `DEBUG` - Enable debug mode
232 +
233 +## Important Notes
234 +- Never commit `.env` files
235 +- Run migrations before testing
236 +- Use dependency injection for services
237 +```
238 +
239 +## Project-Specific Skills
240 +
241 +Create skills that only apply to this project:
242 +
243 +```
244 +.a0proj/skills/
245 +└── deploy-staging/
246 + └── SKILL.md
247 +```
248 +
249 +```yaml
250 +---
251 +name: "deploy-staging"
252 +description: "Deploy this project to staging environment"
253 +trigger_patterns:
254 + - "deploy to staging"
255 + - "staging deploy"
256 +---
257 +
258 +# Deploy to Staging
259 +
260 +## Steps
261 +1. Run tests: `pytest -v`
262 +2. Build image: `docker build -t userapi:staging .`
263 +3. Push: `docker push registry.example.com/userapi:staging`
264 +4. Deploy: `kubectl apply -f k8s/staging/`
265 +
266 +## Verification
267 +- Check pods: `kubectl get pods -n staging`
268 +- Check logs: `kubectl logs -n staging -l app=userapi`
269 +- Test endpoint: `curl https://staging.example.com/health`
270 +```
271 +
272 +## Setting Up a New Project
273 +
274 +### Quick Setup
275 +
276 +1. **Create the config directory**:
277 + ```bash
278 + mkdir -p .a0proj/skills
279 + ```
280 +
281 +2. **Create config.json**:
282 + ```bash
283 + cat > .a0proj/config.json << 'EOF'
284 + {
285 + "name": "My Project",
286 + "description": "Project description"
287 + }
288 + EOF
289 + ```
290 +
291 +3. **Create instructions.md**:
292 + ```bash
293 + cat > .a0proj/instructions.md << 'EOF'
294 + # Project: My Project
295 +
296 + ## Overview
297 + [Describe your project]
298 +
299 + ## Tech Stack
300 + [List technologies]
301 +
302 + ## Commands
303 + [List common commands]
304 + EOF
305 + ```
306 +
307 +4. **Open project in Agent Zero**:
308 + - Navigate to project directory
309 + - Agent will auto-detect `.a0proj/`
310 +
311 +## Best Practices
312 +
313 +### DO
314 +
315 +- ✅ Keep instructions concise but complete
316 +- ✅ Document important file locations
317 +- ✅ Include common commands
318 +- ✅ List coding standards
319 +- ✅ Update as project evolves
320 +
321 +### DON'T
322 +
323 +- ❌ Include sensitive data (secrets, keys)
324 +- ❌ Write overly detailed instructions
325 +- ❌ Forget to update after changes
326 +- ❌ Create conflicting tool configurations
327 +
328 +## Project Detection
329 +
330 +Agent Zero detects projects by:
331 +1. Looking for `.a0proj/` directory
332 +2. Loading `config.json` for settings
333 +3. Loading `instructions.md` for context
334 +4. Discovering project-specific skills
335 +
336 +## Next Steps
337 +
338 +After setting up a project:
339 +- Test that instructions are helpful
340 +- Add project-specific skills as needed
341 +- Refine configuration based on usage
342 +- Keep documentation current
skills/frameworks/agent-zero-dev/a0dev-create-skill/SKILL.md new
+275
@@ -0,0 +1,275 @@
1 +---
2 +name: "a0dev-create-skill"
3 +description: "Build reusable instruction bundles following the SKILL.md standard."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["agent-zero-dev", "skill", "instructions", "SKILL.md"]
7 +trigger_patterns:
8 + - "create skill"
9 + - "new skill"
10 + - "add skill"
11 + - "build skill"
12 + - "/a0dev-create-skill"
13 +---
14 +
15 +# Agent Zero Dev: Create Skill
16 +
17 +Skills are reusable instruction bundles that guide the agent through specific tasks. They follow the SKILL.md standard with YAML frontmatter and markdown content.
18 +
19 +## Skill Location
20 +
21 +```
22 +skills/
23 +├── builtin/ # System skills (don't modify)
24 +├── custom/ # Your skills go here
25 +│ └── my-skill/
26 +│ ├── SKILL.md # Required: Main skill file
27 +│ ├── scripts/ # Optional: Helper scripts
28 +│ ├── templates/ # Optional: Templates
29 +│ └── docs/ # Optional: Additional docs
30 +└── frameworks/ # Multi-phase framework skills
31 +```
32 +
33 +## SKILL.md Format
34 +
35 +```yaml
36 +---
37 +name: "skill-name"
38 +description: "Clear description of what this skill does and when to use it"
39 +version: "1.0.0"
40 +author: "Your Name"
41 +tags: ["category1", "category2"]
42 +trigger_patterns:
43 + - "keyword that triggers"
44 + - "another trigger phrase"
45 + - "use skill-name"
46 +---
47 +
48 +# Skill Title
49 +
50 +## When to Use
51 +Describe the situations where this skill applies.
52 +
53 +## The Process
54 +
55 +### Step 1: First Action
56 +Detailed instructions...
57 +
58 +### Step 2: Second Action
59 +More instructions...
60 +
61 +## Examples
62 +Show sample usage and expected outcomes.
63 +
64 +## Tips
65 +Additional guidance and best practices.
66 +```
67 +
68 +## Frontmatter Fields
69 +
70 +| Field | Required | Description |
71 +|-------|----------|-------------|
72 +| `name` | Yes | Unique skill identifier (kebab-case) |
73 +| `description` | Yes | One-line summary |
74 +| `version` | No | Semantic version |
75 +| `author` | No | Creator name |
76 +| `tags` | No | Categorization tags |
77 +| `trigger_patterns` | Yes | Phrases that activate this skill |
78 +
79 +## Trigger Patterns
80 +
81 +Trigger patterns are case-insensitive phrases that activate the skill:
82 +
83 +```yaml
84 +trigger_patterns:
85 + - "deploy to production" # Exact phrase match
86 + - "ship it" # Short trigger
87 + - "production deploy" # Alternative phrasing
88 + - "/deploy" # Command-style
89 +```
90 +
91 +**Best Practices:**
92 +- Include 3-5 varied trigger phrases
93 +- Mix formal and casual language
94 +- Include command-style triggers (`/skill-name`)
95 +- Avoid overly generic triggers
96 +
97 +## Complete Example: Code Review Skill
98 +
99 +```yaml
100 +---
101 +name: "code-review"
102 +description: "Perform thorough code review with focus on quality and best practices"
103 +version: "1.0.0"
104 +author: "Agent Zero Team"
105 +tags: ["development", "review", "quality"]
106 +trigger_patterns:
107 + - "review code"
108 + - "code review"
109 + - "review this"
110 + - "check my code"
111 + - "/code-review"
112 +---
113 +
114 +# Code Review
115 +
116 +Thorough code review focusing on quality, maintainability, and best practices.
117 +
118 +## When to Use
119 +
120 +- Before merging pull requests
121 +- After completing a feature
122 +- When refactoring existing code
123 +- To learn from code patterns
124 +
125 +## The Process
126 +
127 +### Step 1: Understand Context
128 +
129 +Before reviewing:
130 +1. Identify the purpose of the code
131 +2. Understand the broader system context
132 +3. Note any constraints or requirements
133 +
134 +### Step 2: Check Correctness
135 +
136 +Review for:
137 +- [ ] Logic errors
138 +- [ ] Edge cases handled
139 +- [ ] Error handling present
140 +- [ ] Input validation
141 +
142 +### Step 3: Assess Quality
143 +
144 +Evaluate:
145 +- [ ] Clear naming conventions
146 +- [ ] Appropriate abstractions
147 +- [ ] DRY (Don't Repeat Yourself)
148 +- [ ] Single responsibility
149 +
150 +### Step 4: Review Style
151 +
152 +Check:
153 +- [ ] Consistent formatting
154 +- [ ] Meaningful comments
155 +- [ ] Documentation updated
156 +- [ ] Tests included
157 +
158 +### Step 5: Provide Feedback
159 +
160 +Structure feedback as:
161 +- **Critical**: Must fix before merge
162 +- **Important**: Should fix soon
163 +- **Suggestion**: Nice to have improvements
164 +
165 +## Output Format
166 +
167 +```markdown
168 +## Code Review: [File/Feature]
169 +
170 +### Summary
171 +[Brief overall assessment]
172 +
173 +### Critical Issues
174 +- [Issue 1]: [Location] - [Why it matters]
175 +
176 +### Important Issues
177 +- [Issue 1]: [Suggestion]
178 +
179 +### Suggestions
180 +- [Nice-to-have improvements]
181 +
182 +### Strengths
183 +- [What's done well]
184 +```
185 +
186 +## Tips
187 +
188 +- Focus on the code, not the person
189 +- Explain the "why" behind suggestions
190 +- Acknowledge good patterns
191 +- Be specific with line numbers/locations
192 +```
193 +
194 +## Adding Scripts
195 +
196 +Skills can include helper scripts:
197 +
198 +```
199 +my-skill/
200 +├── SKILL.md
201 +└── scripts/
202 + ├── helper.py
203 + └── process.sh
204 +```
205 +
206 +Reference in SKILL.md:
207 +```markdown
208 +## Scripts
209 +
210 +Run the helper script:
211 +- `scripts/helper.py` - Processes input data
212 +- `scripts/process.sh` - Sets up environment
213 +```
214 +
215 +## Adding Templates
216 +
217 +Include reusable templates:
218 +
219 +```
220 +my-skill/
221 +├── SKILL.md
222 +└── templates/
223 + └── output.md
224 +```
225 +
226 +Reference in SKILL.md:
227 +```markdown
228 +## Templates
229 +
230 +Use `templates/output.md` as the base for your output format.
231 +```
232 +
233 +## Using the Generator Script
234 +
235 +```bash
236 +python skills/frameworks/agent-zero-dev/scripts/create_skill.py \
237 + code-review \
238 + "Perform thorough code review with focus on quality"
239 +```
240 +
241 +Generates: `skills/custom/code-review/SKILL.md`
242 +
243 +## Skill Best Practices
244 +
245 +### DO
246 +
247 +- ✅ Write clear, actionable instructions
248 +- ✅ Include examples and expected outputs
249 +- ✅ Use checklists for multi-step processes
250 +- ✅ Provide output format templates
251 +- ✅ Test with real scenarios
252 +
253 +### DON'T
254 +
255 +- ❌ Write vague or ambiguous instructions
256 +- ❌ Assume context the agent won't have
257 +- ❌ Use overly generic trigger patterns
258 +- ❌ Skip the "When to Use" section
259 +- ❌ Forget to version your skills
260 +
261 +## Testing Skills
262 +
263 +1. Create the skill in `skills/custom/`
264 +2. Ask the agent using a trigger phrase
265 +3. Verify the skill loads correctly
266 +4. Test with varied inputs
267 +5. Refine based on results
268 +
269 +## Next Steps
270 +
271 +After creating a skill:
272 +- Test with multiple trigger phrases
273 +- Gather feedback on clarity
274 +- Iterate on instructions
275 +- Consider sharing with the community
skills/frameworks/agent-zero-dev/a0dev-create-subordinate/SKILL.md new
+295
@@ -0,0 +1,295 @@
1 +---
2 +name: "a0dev-create-subordinate"
3 +description: "Create specialized agent profiles (subordinates) for Agent Zero."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["agent-zero-dev", "subordinate", "agent", "profile", "specialized"]
7 +trigger_patterns:
8 + - "create subordinate"
9 + - "new subordinate"
10 + - "specialized agent"
11 + - "agent profile"
12 + - "/a0dev-create-subordinate"
13 +---
14 +
15 +# Agent Zero Dev: Create Subordinate
16 +
17 +Subordinates are specialized agents with custom prompts and configurations. They can be called by the main agent to handle domain-specific tasks.
18 +
19 +## Subordinate Location
20 +
21 +```
22 +agents/
23 +├── default/ # Default agent profile
24 +├── developer/ # Developer specialist
25 +├── researcher/ # Research specialist
26 +└── your-profile/ # Your custom profile
27 + ├── agent.json # Profile configuration
28 + └── prompts/
29 + ├── system.md # System prompt
30 + └── tools.md # Tool-specific prompts
31 +```
32 +
33 +## Profile Structure
34 +
35 +### agent.json
36 +
37 +```json
38 +{
39 + "name": "Specialized Agent",
40 + "description": "What this subordinate specializes in",
41 + "model": "anthropic/claude-sonnet-4-20250514",
42 + "temperature": 0.7,
43 + "max_tokens": 4000,
44 + "allowed_tools": [
45 + "code_execution_tool",
46 + "search_engine",
47 + "memory_tool"
48 + ],
49 + "prompts": {
50 + "system": "prompts/system.md"
51 + }
52 +}
53 +```
54 +
55 +### Configuration Fields
56 +
57 +| Field | Type | Description |
58 +|-------|------|-------------|
59 +| `name` | string | Display name |
60 +| `description` | string | What this agent does |
61 +| `model` | string | LLM model to use |
62 +| `temperature` | float | Response randomness (0-1) |
63 +| `max_tokens` | int | Max response length |
64 +| `allowed_tools` | array | Tools this agent can use |
65 +| `prompts.system` | string | Path to system prompt |
66 +
67 +## System Prompt Template
68 +
69 +```markdown
70 +# prompts/system.md
71 +
72 +# [Agent Name]
73 +
74 +## Your Role
75 +You are a specialized agent focused on [domain].
76 +
77 +## Expertise
78 +- Deep knowledge of [specific area]
79 +- Experience with [tools/technologies]
80 +- Understanding of [concepts]
81 +
82 +## Capabilities
83 +You can use these tools:
84 +- `code_execution_tool` - Run code
85 +- `search_engine` - Search the web
86 +- `memory_tool` - Store and recall information
87 +
88 +## Process
89 +When given a task:
90 +1. Analyze the request
91 +2. Break down into steps
92 +3. Use appropriate tools
93 +4. Verify results
94 +5. Return structured response
95 +
96 +## Output Format
97 +Always respond with clear, structured output:
98 +- Summary of what was done
99 +- Key findings or results
100 +- Any issues encountered
101 +- Recommendations if applicable
102 +
103 +## Constraints
104 +- Stay focused on [domain]
105 +- Ask for clarification if needed
106 +- Report errors clearly
107 +- Don't exceed your expertise
108 +```
109 +
110 +## Complete Example: Developer Profile
111 +
112 +### agents/developer/agent.json
113 +
114 +```json
115 +{
116 + "name": "Developer Agent",
117 + "description": "Specialized in software development, code review, and debugging",
118 + "model": "anthropic/claude-sonnet-4-20250514",
119 + "temperature": 0.3,
120 + "max_tokens": 8000,
121 + "allowed_tools": [
122 + "code_execution_tool",
123 + "search_engine",
124 + "memory_tool",
125 + "skills_tool"
126 + ],
127 + "prompts": {
128 + "system": "prompts/system.md"
129 + }
130 +}
131 +```
132 +
133 +### agents/developer/prompts/system.md
134 +
135 +```markdown
136 +# Developer Agent
137 +
138 +## Your Role
139 +You are a senior software developer with expertise in multiple languages and frameworks. You write clean, efficient, and well-documented code.
140 +
141 +## Expertise
142 +- Languages: Python, JavaScript, TypeScript, Go, Rust
143 +- Frameworks: FastAPI, React, Node.js
144 +- Practices: TDD, code review, debugging
145 +- Tools: Git, Docker, CI/CD
146 +
147 +## Capabilities
148 +- Write and refactor code
149 +- Debug issues systematically
150 +- Review code for quality
151 +- Explain technical concepts
152 +- Create tests
153 +
154 +## Process
155 +1. Understand the requirement
156 +2. Plan the implementation
157 +3. Write clean code
158 +4. Test thoroughly
159 +5. Document appropriately
160 +
161 +## Code Standards
162 +- Use meaningful names
163 +- Write clear comments
164 +- Handle errors gracefully
165 +- Follow language conventions
166 +- Keep functions focused
167 +
168 +## Output Format
169 +When providing code:
170 +```language
171 +// Code with comments
172 +```
173 +
174 +When explaining:
175 +- Clear step-by-step breakdown
176 +- Code examples where helpful
177 +- Links to documentation
178 +```
179 +
180 +## Calling Subordinates
181 +
182 +From the main agent or tools:
183 +
184 +```python
185 +# Using call_subordinate tool
186 +call_subordinate(
187 + profile="developer",
188 + message="Review this Python function for bugs and improvements",
189 + reset="false"
190 +)
191 +```
192 +
193 +### Parameters
194 +
195 +| Param | Description |
196 +|-------|-------------|
197 +| `profile` | Name of the subordinate profile directory |
198 +| `message` | Task to delegate to the subordinate |
199 +| `reset` | "true" to reset subordinate state, "false" to continue |
200 +
201 +## Tool Restrictions
202 +
203 +Limit tools based on subordinate purpose:
204 +
205 +### Research Agent (read-only)
206 +```json
207 +"allowed_tools": [
208 + "search_engine",
209 + "memory_tool"
210 +]
211 +```
212 +
213 +### Developer Agent (code execution)
214 +```json
215 +"allowed_tools": [
216 + "code_execution_tool",
217 + "search_engine",
218 + "memory_tool"
219 +]
220 +```
221 +
222 +### Admin Agent (full access)
223 +```json
224 +"allowed_tools": [
225 + "*"
226 +]
227 +```
228 +
229 +## Subordinate Best Practices
230 +
231 +### DO
232 +
233 +- ✅ Keep profiles focused on specific domains
234 +- ✅ Limit tool access to what's needed
235 +- ✅ Write clear, specific system prompts
236 +- ✅ Include output format examples
237 +- ✅ Define constraints and boundaries
238 +
239 +### DON'T
240 +
241 +- ❌ Create overly broad profiles
242 +- ❌ Give unnecessary tool access
243 +- ❌ Write vague system prompts
244 +- ❌ Forget to handle edge cases
245 +- ❌ Skip testing with real tasks
246 +
247 +## Subordinate Communication
248 +
249 +### From Main Agent
250 +```
251 +"Delegate this research task to the researcher subordinate"
252 +→ Uses call_subordinate tool with profile="researcher"
253 +```
254 +
255 +### Response Flow
256 +```
257 +Main Agent → call_subordinate → Subordinate executes → Result returned
258 +```
259 +
260 +## Testing Subordinates
261 +
262 +1. Create the profile directory and files
263 +2. Restart Agent Zero
264 +3. Ask main agent to delegate a task:
265 + ```
266 + "Use the developer subordinate to review this code: ..."
267 + ```
268 +4. Verify the subordinate:
269 + - Uses correct model
270 + - Has proper tool access
271 + - Follows system prompt
272 + - Returns expected output format
273 +
274 +## Sharing Context
275 +
276 +Subordinates share context with the main agent:
277 +
278 +```python
279 +# Context is shared
280 +context = agent.context
281 +
282 +# Data persists
283 +context.data["shared_key"] = value
284 +
285 +# Subordinate can read/write
286 +value = context.data.get("shared_key")
287 +```
288 +
289 +## Next Steps
290 +
291 +After creating a subordinate:
292 +- Test with various task types
293 +- Refine the system prompt based on results
294 +- Adjust tool access as needed
295 +- Document use cases
skills/frameworks/agent-zero-dev/a0dev-create-tool/SKILL.md new
+231
@@ -0,0 +1,231 @@
1 +---
2 +name: "a0dev-create-tool"
3 +description: "Create new agent capabilities (tools) for Agent Zero."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["agent-zero-dev", "tool", "capability", "development"]
7 +trigger_patterns:
8 + - "create tool"
9 + - "new tool"
10 + - "add tool"
11 + - "build tool"
12 + - "/a0dev-create-tool"
13 +---
14 +
15 +# Agent Zero Dev: Create Tool
16 +
17 +Tools are the primary way agents interact with the world. Each tool inherits from the `Tool` base class and provides capabilities like web search, code execution, file manipulation, etc.
18 +
19 +## Tool Location
20 +
21 +```
22 +python/tools/
23 +├── code_execution_tool.py
24 +├── search_engine.py
25 +├── call_subordinate.py
26 +├── memory_tool.py
27 +└── your_tool.py ← New tools go here
28 +```
29 +
30 +## Tool Structure
31 +
32 +```python
33 +# python/tools/my_tool.py
34 +from python.helpers.tool import Tool, Response
35 +
36 +class MyTool(Tool):
37 + """
38 + Brief description of what this tool does.
39 +
40 + Arguments (tool_args):
41 + - arg1: Description of first argument
42 + - arg2: Description of second argument (optional)
43 + """
44 +
45 + async def execute(self, **kwargs) -> Response:
46 + # Get arguments (kwargs takes priority, fallback to self.args)
47 + arg1 = kwargs.get("arg1") or self.args.get("arg1")
48 + arg2 = kwargs.get("arg2") or self.args.get("arg2", "default")
49 +
50 + try:
51 + # Tool logic here
52 + result = await self.do_work(arg1, arg2)
53 +
54 + return Response(
55 + message=result,
56 + break_loop=False # True to end agent loop
57 + )
58 + except Exception as e:
59 + return Response(
60 + message=f"Error: {e}",
61 + break_loop=False
62 + )
63 +
64 + async def do_work(self, arg1, arg2):
65 + # Implementation
66 + return f"Processed {arg1} with {arg2}"
67 +```
68 +
69 +## Response Object
70 +
71 +```python
72 +Response(
73 + message: str, # Result message shown to agent
74 + break_loop: bool, # True = end agent loop (task complete)
75 + additional: dict = {} # Extra data (hints, metadata)
76 +)
77 +```
78 +
79 +## Accessing Agent Context
80 +
81 +```python
82 +async def execute(self, **kwargs) -> Response:
83 + # Access the agent
84 + agent = self.agent
85 +
86 + # Access shared context (persists across agents)
87 + context = agent.context
88 +
89 + # Store/retrieve data
90 + context.data["my_key"] = "my_value"
91 + value = context.data.get("my_key")
92 +
93 + # Access agent configuration
94 + config = agent.config
95 +```
96 +
97 +## Tool Best Practices
98 +
99 +### DO
100 +
101 +- ✅ Document arguments in class docstring
102 +- ✅ Use `Response` for all returns
103 +- ✅ Handle errors gracefully (return error message, don't crash)
104 +- ✅ Use kwargs fallback to self.args
105 +- ✅ Make operations async when possible
106 +- ✅ Use type hints
107 +
108 +### DON'T
109 +
110 +- ❌ Raise unhandled exceptions
111 +- ❌ Block the event loop (use async)
112 +- ❌ Hardcode paths or values
113 +- ❌ Ignore optional arguments
114 +- ❌ Print directly (use Response or logging)
115 +
116 +## Complete Example: Data Processor
117 +
118 +```python
119 +# python/tools/data_processor.py
120 +from python.helpers.tool import Tool, Response
121 +import json
122 +
123 +class DataProcessor(Tool):
124 + """
125 + Process and transform JSON data structures.
126 +
127 + Arguments (tool_args):
128 + - operation: The operation (filter, sort, map)
129 + - data: JSON string to process
130 + - key: Key to operate on
131 + - value: Value for filter operation (optional)
132 + """
133 +
134 + async def execute(self, **kwargs) -> Response:
135 + try:
136 + operation = kwargs.get("operation") or self.args.get("operation", "")
137 + data_str = kwargs.get("data") or self.args.get("data", "[]")
138 + key = kwargs.get("key") or self.args.get("key")
139 + value = kwargs.get("value") or self.args.get("value")
140 +
141 + data = json.loads(data_str)
142 +
143 + if operation == "filter":
144 + result = [item for item in data if item.get(key) == value]
145 + elif operation == "sort":
146 + result = sorted(data, key=lambda x: x.get(key, ""))
147 + elif operation == "map":
148 + result = [item.get(key) for item in data]
149 + else:
150 + return Response(
151 + message=f"Unknown operation: {operation}",
152 + break_loop=False
153 + )
154 +
155 + return Response(
156 + message=json.dumps(result, indent=2),
157 + break_loop=False
158 + )
159 +
160 + except json.JSONDecodeError as e:
161 + return Response(message=f"Invalid JSON: {e}", break_loop=False)
162 + except Exception as e:
163 + return Response(message=f"Error: {e}", break_loop=False)
164 +```
165 +
166 +## Using the Generator Script
167 +
168 +```bash
169 +python skills/frameworks/agent-zero-dev/scripts/create_tool.py \
170 + DataProcessor \
171 + "Process and transform JSON data structures"
172 +```
173 +
174 +This generates boilerplate at `python/tools/data_processor.py`.
175 +
176 +## Tool Registration
177 +
178 +Tools are auto-discovered by filename convention:
179 +- Filename: `snake_case.py` (e.g., `data_processor.py`)
180 +- Class name: `PascalCase` (e.g., `DataProcessor`)
181 +- Tool name (for agent): derived from class name
182 +
183 +## Testing Your Tool
184 +
185 +1. **Restart Agent Zero** (tools load at startup)
186 +2. **Ask the agent** to use your tool:
187 + ```
188 + "Use the data_processor tool to sort this JSON by name: [{"name": "z"}, {"name": "a"}]"
189 + ```
190 +3. **Check logs** for errors: `docker logs -f agent-zero`
191 +
192 +## Common Patterns
193 +
194 +### Async HTTP Request
195 +
196 +```python
197 +import aiohttp
198 +
199 +async def fetch_data(self, url):
200 + async with aiohttp.ClientSession() as session:
201 + async with session.get(url) as response:
202 + return await response.text()
203 +```
204 +
205 +### File Operations
206 +
207 +```python
208 +from python.helpers import files
209 +
210 +content = files.read_file("path/to/file")
211 +files.write_file("path/to/file", content)
212 +exists = files.exists("path/to/file")
213 +```
214 +
215 +### Logging
216 +
217 +```python
218 +from python.helpers.print_style import PrintStyle
219 +
220 +PrintStyle.hint("Info message")
221 +PrintStyle.warning("Warning message")
222 +PrintStyle.error("Error message")
223 +```
224 +
225 +## Next Steps
226 +
227 +After creating your tool:
228 +- Test thoroughly with different inputs
229 +- Document edge cases
230 +- Consider error messages for users
231 +- Add to project documentation if significant
skills/frameworks/agent-zero-dev/a0dev-quickstart/SKILL.md new
+142
@@ -0,0 +1,142 @@
1 +---
2 +name: "a0dev-quickstart"
3 +description: "5-minute quickstart guide to extending Agent Zero."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["agent-zero-dev", "quickstart", "getting-started", "tutorial"]
7 +trigger_patterns:
8 + - "quickstart"
9 + - "getting started"
10 + - "start extending"
11 + - "how to extend"
12 + - "/a0dev-quickstart"
13 +---
14 +
15 +# Agent Zero Dev: Quickstart
16 +
17 +Get started extending Agent Zero in 5 minutes.
18 +
19 +## Choose Your Extension Point
20 +
21 +| Want To | Use | Location |
22 +|---------|-----|----------|
23 +| Add agent capability | **Tool** | `python/tools/` |
24 +| Hook lifecycle events | **Extension** | `python/extensions/<hook>/` |
25 +| Create instruction bundle | **Skill** | `skills/custom/<name>/` |
26 +| Add Web UI endpoint | **API** | `python/api/` |
27 +| Create specialized agent | **Subordinate** | `agents/<profile>/` |
28 +| Configure project | **Project** | `.a0proj/` |
29 +
30 +## Quick Commands
31 +
32 +```bash
33 +# Create a new tool
34 +python skills/frameworks/agent-zero-dev/scripts/create_tool.py MyTool "Description"
35 +
36 +# Create an extension
37 +python skills/frameworks/agent-zero-dev/scripts/create_extension.py agent_init MyExt "Description"
38 +
39 +# Create a skill
40 +python skills/frameworks/agent-zero-dev/scripts/create_skill.py my-skill "Description"
41 +
42 +# Create an API endpoint
43 +python skills/frameworks/agent-zero-dev/scripts/create_api.py MyEndpoint "Description"
44 +```
45 +
46 +## Framework Architecture
47 +
48 +```
49 +Agent Zero Framework
50 +├── python/
51 +│ ├── tools/ # Agent capabilities (inherit from Tool)
52 +│ ├── extensions/ # Lifecycle hooks (numbered execution)
53 +│ ├── api/ # FastAPI endpoints (inherit from ApiHandler)
54 +│ └── helpers/ # Utility functions and base classes
55 +├── skills/
56 +│ ├── builtin/ # Built-in skills
57 +│ ├── custom/ # Your skills go here
58 +│ └── frameworks/ # Multi-phase framework skills
59 +├── agents/ # Subordinate profiles
60 +└── memory/ # FAISS vector memory
61 +```
62 +
63 +## Key Patterns
64 +
65 +1. **Extensions execute in numeric order** (`_10_*.py`, `_20_*.py`)
66 +2. **Tools inherit from `Tool`** with async `execute()` method
67 +3. **Skills use YAML frontmatter** + markdown content
68 +4. **APIs inherit from `ApiHandler`** with `process()` method
69 +5. **Everything is async/await** for non-blocking operations
70 +
71 +## Minimal Examples
72 +
73 +### Minimal Tool
74 +
75 +```python
76 +# python/tools/hello_tool.py
77 +from python.helpers.tool import Tool, Response
78 +
79 +class HelloTool(Tool):
80 + async def execute(self, name="World", **kwargs) -> Response:
81 + return Response(message=f"Hello, {name}!", break_loop=False)
82 +```
83 +
84 +### Minimal Extension
85 +
86 +```python
87 +# python/extensions/agent_init/_99_my_ext.py
88 +from python.helpers.extension import Extension
89 +
90 +class MyExtension(Extension):
91 + async def execute(self, **kwargs):
92 + print("Agent initialized!")
93 + return kwargs.get("data", {})
94 +```
95 +
96 +### Minimal Skill
97 +
98 +```yaml
99 +---
100 +name: "my-skill"
101 +description: "What this skill does"
102 +trigger_patterns:
103 + - "trigger phrase"
104 +---
105 +
106 +# My Skill
107 +
108 +Instructions for the agent to follow.
109 +```
110 +
111 +### Minimal API
112 +
113 +```python
114 +# python/api/my_endpoint.py
115 +from python.helpers.api import ApiHandler, Request
116 +
117 +class MyEndpoint(ApiHandler):
118 + async def process(self, input: dict, request: Request) -> dict:
119 + return {"message": "Hello from API!"}
120 +```
121 +
122 +## Development Workflow
123 +
124 +```
125 +1. Choose extension point → Tool, Extension, Skill, API, etc.
126 +2. Generate boilerplate → Use scripts/ generators
127 +3. Implement logic → Fill in your code
128 +4. Test → Restart Agent Zero and verify
129 +5. Iterate → Refine based on results
130 +```
131 +
132 +## Next Steps
133 +
134 +- `/a0dev-create-tool` — Deep dive into tools
135 +- `/a0dev-create-extension` — Deep dive into extensions
136 +- `/a0dev-create-skill` — Deep dive into skills
137 +- `/a0dev-create-api` — Deep dive into APIs
138 +- `/a0dev-workflow` — Full development workflow
139 +
140 +## Need Help?
141 +
142 +Say "help me create a [tool/extension/skill/api]" and I'll guide you through it!
skills/frameworks/agent-zero-dev/a0dev-workflow/SKILL.md new
+322
@@ -0,0 +1,322 @@
1 +---
2 +name: "a0dev-workflow"
3 +description: "Full development workflow for building Agent Zero features."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["agent-zero-dev", "workflow", "development", "process"]
7 +trigger_patterns:
8 + - "development workflow"
9 + - "dev workflow"
10 + - "build feature"
11 + - "extend agent zero"
12 + - "/a0dev-workflow"
13 +---
14 +
15 +# Agent Zero Dev: Development Workflow
16 +
17 +Complete workflow for building features for Agent Zero framework.
18 +
19 +## Workflow Phases
20 +
21 +```
22 +1. Brainstorm → 2. Plan → 3. Scaffold → 4. Implement → 5. Test → 6. Refine
23 +```
24 +
25 +## Phase 1: Brainstorm
26 +
27 +### Define the Problem
28 +
29 +**Questions to answer:**
30 +- What problem does this solve?
31 +- Who benefits from this feature?
32 +- What's the expected outcome?
33 +
34 +### Identify Extension Point
35 +
36 +| If you need to... | Use |
37 +|-------------------|-----|
38 +| Add agent capability | Tool |
39 +| Hook into lifecycle | Extension |
40 +| Create instruction bundle | Skill |
41 +| Add Web UI endpoint | API |
42 +| Create specialized agent | Subordinate |
43 +| Configure workspace | Project |
44 +
45 +### Review Existing Patterns
46 +
47 +Before building, examine similar code:
48 +- `python/tools/` — Tool patterns
49 +- `python/extensions/` — Extension patterns
50 +- `skills/` — Skill patterns
51 +- `python/api/` — API patterns
52 +
53 +## Phase 2: Plan
54 +
55 +### Break Into Tasks
56 +
57 +Each task should be:
58 +- Small (2-5 minutes to complete)
59 +- Testable (clear verification)
60 +- Independent (minimal dependencies)
61 +
62 +### Example Task Breakdown
63 +
64 +**Feature:** "Add weather lookup tool"
65 +
66 +```markdown
67 +## Tasks
68 +
69 +1. [ ] Create tool file structure
70 + - File: python/tools/weather_tool.py
71 + - Verify: File exists with boilerplate
72 +
73 +2. [ ] Implement weather API integration
74 + - Use aiohttp for async requests
75 + - Verify: Can fetch weather data
76 +
77 +3. [ ] Add error handling
78 + - Handle API errors, invalid locations
79 + - Verify: Graceful error messages
80 +
81 +4. [ ] Test with agent
82 + - Ask agent to get weather
83 + - Verify: Correct response format
84 +
85 +5. [ ] Document the tool
86 + - Add docstring with args
87 + - Verify: Documentation complete
88 +```
89 +
90 +### Identify Dependencies
91 +
92 +```
93 +What must exist first?
94 +├── API keys configured?
95 +├── Dependencies installed?
96 +├── Related code ready?
97 +└── Test data available?
98 +```
99 +
100 +## Phase 3: Scaffold
101 +
102 +### Use Generator Scripts
103 +
104 +```bash
105 +# Generate boilerplate
106 +python skills/frameworks/agent-zero-dev/scripts/create_tool.py WeatherTool "Look up weather for a location"
107 +```
108 +
109 +### Available Generators
110 +
111 +| Script | Creates |
112 +|--------|---------|
113 +| `create_tool.py` | Tool in `python/tools/` |
114 +| `create_extension.py` | Extension in `python/extensions/` |
115 +| `create_skill.py` | Skill in `skills/custom/` |
116 +| `create_api.py` | API in `python/api/` |
117 +
118 +### Review Generated Code
119 +
120 +After generation:
121 +1. Open the created file
122 +2. Review the boilerplate
123 +3. Identify what to fill in
124 +4. Note the patterns used
125 +
126 +## Phase 4: Implement
127 +
128 +### Follow Test-Driven Development
129 +
130 +```
131 +1. Write test (what should happen)
132 +2. Run test (should fail)
133 +3. Write code (minimal to pass)
134 +4. Run test (should pass)
135 +5. Refactor (improve quality)
136 +```
137 +
138 +### Implementation Checklist
139 +
140 +- [ ] Follow existing code patterns
141 +- [ ] Add proper error handling
142 +- [ ] Use type hints
143 +- [ ] Write clear docstrings
144 +- [ ] Keep functions focused
145 +- [ ] Use async where appropriate
146 +
147 +### Common Patterns
148 +
149 +**Accessing Context:**
150 +```python
151 +context = self.agent.context
152 +data = context.data
153 +```
154 +
155 +**Error Handling:**
156 +```python
157 +try:
158 + result = await risky_operation()
159 +except Exception as e:
160 + return Response(message=f"Error: {e}", break_loop=False)
161 +```
162 +
163 +**Async Operations:**
164 +```python
165 +async with aiohttp.ClientSession() as session:
166 + async with session.get(url) as response:
167 + return await response.json()
168 +```
169 +
170 +## Phase 5: Test
171 +
172 +### Manual Testing
173 +
174 +1. **Restart Agent Zero** (code loads at startup)
175 +2. **Trigger your feature**:
176 + ```
177 + "Use the weather tool to check weather in Seattle"
178 + ```
179 +3. **Verify behavior**:
180 + - Correct response?
181 + - Errors handled?
182 + - Performance acceptable?
183 +
184 +### Check Logs
185 +
186 +```bash
187 +# Docker logs
188 +docker logs -f agent-zero
189 +
190 +# Or check log files
191 +tail -f logs/agent.log
192 +```
193 +
194 +### Test Edge Cases
195 +
196 +- Invalid inputs
197 +- Missing data
198 +- Network failures
199 +- Concurrent access
200 +
201 +## Phase 6: Refine
202 +
203 +### Code Review Checklist
204 +
205 +- [ ] Follows project conventions?
206 +- [ ] Error handling complete?
207 +- [ ] Documentation updated?
208 +- [ ] No hardcoded values?
209 +- [ ] Performance acceptable?
210 +
211 +### Refactoring
212 +
213 +After it works:
214 +- Simplify complex logic
215 +- Extract reusable functions
216 +- Improve naming
217 +- Add missing tests
218 +
219 +### Documentation
220 +
221 +Update as needed:
222 +- Code docstrings
223 +- Skill instructions
224 +- README files
225 +- API documentation
226 +
227 +## Complete Example: Weather Tool
228 +
229 +### Phase 1: Brainstorm
230 +- **Problem:** Agent can't check weather
231 +- **Extension Point:** Tool
232 +- **Similar Code:** `search_engine.py`
233 +
234 +### Phase 2: Plan
235 +```markdown
236 +1. [ ] Generate tool boilerplate
237 +2. [ ] Add weather API integration
238 +3. [ ] Implement execute() method
239 +4. [ ] Add error handling
240 +5. [ ] Test with agent
241 +```
242 +
243 +### Phase 3: Scaffold
244 +```bash
245 +python scripts/create_tool.py WeatherLookup "Get weather for a location"
246 +```
247 +
248 +### Phase 4: Implement
249 +```python
250 +# python/tools/weather_lookup.py
251 +from python.helpers.tool import Tool, Response
252 +import aiohttp
253 +
254 +class WeatherLookup(Tool):
255 + """
256 + Look up current weather for a location.
257 +
258 + Arguments:
259 + - location: City name or coordinates
260 + """
261 +
262 + async def execute(self, location="", **kwargs) -> Response:
263 + location = location or kwargs.get("location") or self.args.get("location", "")
264 +
265 + if not location:
266 + return Response(message="Please provide a location", break_loop=False)
267 +
268 + try:
269 + weather = await self.fetch_weather(location)
270 + return Response(
271 + message=f"Weather in {location}: {weather['description']}, {weather['temp']}°F",
272 + break_loop=False
273 + )
274 + except Exception as e:
275 + return Response(message=f"Could not fetch weather: {e}", break_loop=False)
276 +
277 + async def fetch_weather(self, location):
278 + # Implementation using weather API
279 + async with aiohttp.ClientSession() as session:
280 + url = f"https://api.weather.example/v1?q={location}"
281 + async with session.get(url) as response:
282 + return await response.json()
283 +```
284 +
285 +### Phase 5: Test
286 +```
287 +User: "What's the weather in Seattle?"
288 +Agent: Uses weather_lookup tool
289 +Result: "Weather in Seattle: Partly cloudy, 58°F"
290 +```
291 +
292 +### Phase 6: Refine
293 +- Add caching for repeated lookups
294 +- Support metric/imperial units
295 +- Add forecast option
296 +
297 +## Quick Reference
298 +
299 +### Extension Points
300 +- **Tools:** `python/tools/`
301 +- **Extensions:** `python/extensions/<hook>/`
302 +- **Skills:** `skills/custom/`
303 +- **APIs:** `python/api/`
304 +- **Subordinates:** `agents/<profile>/`
305 +- **Projects:** `.a0proj/`
306 +
307 +### Key Files
308 +- `python/helpers/tool.py` — Tool base class
309 +- `python/helpers/extension.py` — Extension base class
310 +- `python/helpers/api.py` — API base class
311 +
312 +### Commands
313 +- Restart to reload code
314 +- Check logs for errors
315 +- Test with real interactions
316 +
317 +## Next Steps
318 +
319 +Ready to build? Start with:
320 +1. `/a0dev-quickstart` — Quick overview
321 +2. `/a0dev-create-tool` — Build a tool
322 +3. `/a0dev-create-skill` — Create a skill
skills/frameworks/agent-zero-dev/docs/architecture.md new
+296
@@ -0,0 +1,296 @@
1 +# Agent Zero Architecture
2 +
3 +This document provides an in-depth look at Agent Zero's architecture.
4 +
5 +## Core Philosophy
6 +
7 +Agent Zero is designed around the principle of **composable intelligence**:
8 +- Small, focused components that work together
9 +- Clear interfaces between layers
10 +- Extensible at every level
11 +- Async-first for responsiveness
12 +
13 +## Component Layers
14 +
15 +```
16 +┌─────────────────────────────────────────────┐
17 +│ Web UI (Alpine.js) │
18 +│ - Chat interface │
19 +│ - File management │
20 +│ - Memory dashboard │
21 +└─────────────────────────────────────────────┘
22 + │
23 +┌─────────────────────────────────────────────┐
24 +│ API Layer (FastAPI) │
25 +│ - REST endpoints │
26 +│ - WebSocket for streaming │
27 +│ - File uploads/downloads │
28 +└─────────────────────────────────────────────┘
29 + │
30 +┌─────────────────────────────────────────────┐
31 +│ Agent Core │
32 +│ - Message loop │
33 +│ - LLM interaction │
34 +│ - Context management │
35 +└─────────────────────────────────────────────┘
36 + │
37 +┌─────────────────────────────────────────────┐
38 +│ Extension Points │
39 +│ - agent_init │
40 +│ - message_loop_* │
41 +│ - response_stream_* │
42 +│ - tool_execute_* │
43 +└─────────────────────────────────────────────┘
44 + │
45 +┌─────────────────────────────────────────────┐
46 +│ Tool Layer │
47 +│ - Built-in tools │
48 +│ - Custom tools │
49 +│ - External tool calls │
50 +└─────────────────────────────────────────────┘
51 + │
52 +┌─────────────────────────────────────────────┐
53 +│ Skill System │
54 +│ - SKILL.md based │
55 +│ - Progressive disclosure │
56 +│ - Script execution │
57 +└─────────────────────────────────────────────┘
58 + │
59 +┌─────────────────────────────────────────────┐
60 +│ Memory Layer │
61 +│ - FAISS vector store │
62 +│ - Shared AgentContext │
63 +│ - Archive/recovery │
64 +└─────────────────────────────────────────────┘
65 +```
66 +
67 +## Data Flow
68 +
69 +### Message Processing Flow
70 +
71 +1. **User Input** → API endpoint receives message
72 +2. **Extension: message_loop_start** → Pre-processing
73 +3. **Context Retrieval** → Get or create AgentContext
74 +4. **Extension: before_main_llm_call** → Modify prompts
75 +5. **LLM Call** → Send to language model
76 +6. **Extension: response_stream_start** → Begin streaming
77 +7. **Response Chunks** → Stream to UI via WebSocket
78 +8. **Extension: response_stream_chunk** → Transform output
79 +9. **Extension: response_stream_end** → Finalize
80 +10. **Tool Execution** (if needed)
81 + - Extension: tool_execute_before
82 + - Tool.execute()
83 + - Extension: tool_execute_after
84 +11. **Response to User** → Complete message
85 +
86 +### Context Sharing
87 +
88 +All agents in a conversation share the same `AgentContext`:
89 +
90 +```python
91 +# Main agent stores data
92 +self.agent.context.data["user_preference"] = "dark_mode"
93 +
94 +# Subordinate can access the same data
95 +preference = self.agent.context.data.get("user_preference")
96 +```
97 +
98 +This enables:
99 +- Persistent memory across agent switches
100 +- Shared state between parent and subordinates
101 +- Session-wide configuration
102 +
103 +## Extension System
104 +
105 +Extensions are Python classes that hook into specific lifecycle points.
106 +
107 +### Execution Order
108 +
109 +Extensions execute in numeric order based on filename prefix:
110 +
111 +```
112 +_10_first.py # Runs first
113 +_20_second.py # Runs second
114 +_30_third.py # Runs third
115 +```
116 +
117 +### Hook Points
118 +
119 +| Hook | Timing | Use Case |
120 +|------|--------|----------|
121 +| `agent_init` | Agent creation | Configuration loading |
122 +| `message_loop_start` | Before processing | Input validation |
123 +| `message_loop_end` | After processing | Cleanup |
124 +| `before_main_llm_call` | Before LLM | Prompt modification |
125 +| `response_stream_start` | Stream begins | Initialize handlers |
126 +| `response_stream_chunk` | Per chunk | Transform output |
127 +| `response_stream_end` | Stream complete | Finalize |
128 +| `tool_execute_before` | Before tool | Validation |
129 +| `tool_execute_after` | After tool | Post-processing |
130 +
131 +## Memory System
132 +
133 +### Vector Memory
134 +
135 +FAISS-based vector storage for semantic search:
136 +
137 +```python
138 +# Save to memory
139 +memory_save(text="Important information")
140 +
141 +# Load from memory
142 +results = memory_load(query="Find important info")
143 +```
144 +
145 +### Archive System
146 +
147 +Soft-delete with recovery capability:
148 +
149 +```python
150 +# Delete (moves to archive)
151 +memory_delete(ids=["id1", "id2"])
152 +
153 +# Recover from archive
154 +# (via memory dashboard or direct DB access)
155 +```
156 +
157 +## Skill System
158 +
159 +Skills follow the SKILL.md standard:
160 +
161 +### Progressive Disclosure
162 +
163 +1. **Level 1: Metadata** - Always loaded (name, description, tags)
164 +2. **Level 2: Full Content** - Loaded on demand (instructions)
165 +3. **Level 3: Scripts** - Executed as needed
166 +
167 +### Skill Loading
168 +
169 +```
170 +skills/
171 +├── builtin/ # System skills (loaded first)
172 +├── custom/ # User-created skills
173 +└── frameworks/ # Multi-phase framework skills
174 +```
175 +
176 +## Subordinate System
177 +
178 +Specialized agents with custom profiles:
179 +
180 +```
181 +agents/
182 +├── default/ # Default profile
183 +├── developer/ # Coding specialist
184 +├── researcher/ # Research specialist
185 +└── [custom]/ # Your profiles
186 +```
187 +
188 +Each profile contains:
189 +- `agent.json` - Configuration
190 +- `prompts/system.md` - System prompt
191 +- `prompts/subordinates.md` - Delegation prompts
192 +
193 +## Security Considerations
194 +
195 +### Sandboxing
196 +
197 +- Tools run in isolated Python environment
198 +- File system access limited to /a0 directory
199 +- Network access controlled by tool permissions
200 +
201 +### Secrets Management
202 +
203 +Secrets stored in environment variables:
204 +
205 +```python
206 +# Access secrets
207 +from python.helpers import secrets
208 +api_key = secrets.get("API_KEY")
209 +```
210 +
211 +## Performance Optimization
212 +
213 +### Async Patterns
214 +
215 +All I/O is async to prevent blocking:
216 +
217 +```python
218 +# Concurrent execution
219 +tasks = [fetch_data(url) for url in urls]
220 +results = await asyncio.gather(*tasks)
221 +```
222 +
223 +### Caching
224 +
225 +- Skill content cached after first load
226 +- Context data persisted in memory
227 +- Vector embeddings cached in FAISS
228 +
229 +### Streaming
230 +
231 +LLM responses stream to UI for perceived performance:
232 +
233 +```python
234 +for chunk in llm_stream(prompt):
235 + await send_to_ui(chunk)
236 +```
237 +
238 +## Extension Points Deep Dive
239 +
240 +### Creating Custom Hooks
241 +
242 +You can create custom hook points for your extensions:
243 +
244 +```python
245 +# Define hook in your extension
246 +await extension.call_extensions("my_custom_hook", agent=agent, data=data)
247 +```
248 +
249 +### Inter-Extension Communication
250 +
251 +Extensions can communicate via context data:
252 +
253 +```python
254 +# Extension A sets data
255 +self.agent.context.data["ext_a_result"] = result
256 +
257 +# Extension B reads it
258 +result = self.agent.context.data.get("ext_a_result")
259 +```
260 +
261 +## Debugging and Development
262 +
263 +### Logging
264 +
265 +Use PrintStyle for consistent logging:
266 +
267 +```python
268 +PrintStyle.hint("Informational message")
269 +PrintStyle.warning("Warning message")
270 +PrintStyle.error("Error message")
271 +PrintStyle.bold("Important message")
272 +```
273 +
274 +### Debugging Extensions
275 +
276 +Add debug output to trace execution:
277 +
278 +```python
279 +async def execute(self, **kwargs):
280 + PrintStyle.hint(f"Extension {self.__class__.__name__} executing")
281 + PrintStyle.hint(f"Received kwargs: {kwargs}")
282 + # ... logic ...
283 +```
284 +
285 +### Testing Tools
286 +
287 +Test tools in isolation:
288 +
289 +```python
290 +import asyncio
291 +from python.tools.my_tool import MyTool
292 +
293 +tool = MyTool()
294 +result = asyncio.run(tool.execute(param="value"))
295 +print(result.message)
296 +```
skills/frameworks/agent-zero-dev/docs/best-practices.md new
+450
@@ -0,0 +1,450 @@
1 +# Best Practices for Agent Zero Development
2 +
3 +## Code Style
4 +
5 +### Python Conventions
6 +
7 +Follow PEP 8 with these specifics:
8 +
9 +```python
10 +# Use type hints
11 +def process_data(data: dict) -> str:
12 + pass
13 +
14 +# Async everywhere
15 +async def fetch_data() -> dict:
16 + pass
17 +
18 +# Clear variable names
19 +user_input = "" # Good
20 +ui = "" # Avoid
21 +```
22 +
23 +### Documentation
24 +
25 +Every public class and method needs a docstring:
26 +
27 +```python
28 +class MyTool(Tool):
29 + """
30 + Brief description of tool purpose.
31 +
32 + Arguments (tool_args):
33 + - arg1: Description of first argument
34 + - arg2: Description of second argument
35 +
36 + Returns:
37 + Response object with result
38 + """
39 +```
40 +
41 +## Error Handling
42 +
43 +### Graceful Degradation
44 +
45 +Tools should never crash the agent:
46 +
47 +```python
48 +async def execute(self, **kwargs) -> Response:
49 + try:
50 + result = await self.risky_operation()
51 + return Response(message=result, break_loop=False)
52 + except Exception as e:
53 + # Log for debugging
54 + PrintStyle.error(f"Operation failed: {e}")
55 + # Return graceful error to user
56 + return Response(message=f"Error: {e}", break_loop=False)
57 +```
58 +
59 +### Specific Exceptions
60 +
61 +Catch specific exceptions when possible:
62 +
63 +```python
64 +try:
65 + data = json.loads(json_str)
66 +except json.JSONDecodeError as e:
67 + return Response(message=f"Invalid JSON: {e}", break_loop=False)
68 +except Exception as e:
69 + return Response(message=f"Unexpected error: {e}", break_loop=False)
70 +```
71 +
72 +## Performance
73 +
74 +### Avoid Blocking Operations
75 +
76 +Never use synchronous I/O in async methods:
77 +
78 +```python
79 +# Bad - blocks event loop
80 +data = requests.get(url).json()
81 +
82 +# Good - async
83 +import aiohttp
84 +async with aiohttp.ClientSession() as session:
85 + async with session.get(url) as response:
86 + data = await response.json()
87 +```
88 +
89 +### Batch Operations
90 +
91 +Process multiple items concurrently:
92 +
93 +```python
94 +# Process all at once
95 +tasks = [process_item(item) for item in items]
96 +results = await asyncio.gather(*tasks, return_exceptions=True)
97 +
98 +# Handle errors individually
99 +for item, result in zip(items, results):
100 + if isinstance(result, Exception):
101 + PrintStyle.error(f"Failed to process {item}: {result}")
102 + else:
103 + successes.append(result)
104 +```
105 +
106 +## Security
107 +
108 +### Input Validation
109 +
110 +Always validate user input:
111 +
112 +```python
113 +async def execute(self, **kwargs) -> Response:
114 + user_input = kwargs.get("input", "")
115 +
116 + # Validate
117 + if not user_input:
118 + return Response(message="Error: input is required", break_loop=False)
119 +
120 + if len(user_input) > 10000:
121 + return Response(message="Error: input too large", break_loop=False)
122 +
123 + # Process
124 + result = await self.process(user_input)
125 +```
126 +
127 +### Path Safety
128 +
129 +Use secure paths:
130 +
131 +```python
132 +from werkzeug.utils import secure_filename
133 +from python.helpers import files
134 +
135 +# Sanitize filenames
136 +filename = secure_filename(uploaded_file.filename)
137 +
138 +# Use absolute paths
139 +full_path = files.get_abs_path("tmp/uploads", filename)
140 +```
141 +
142 +### Secrets
143 +
144 +Never hardcode credentials:
145 +
146 +```python
147 +# Bad
148 +api_key = "sk-1234567890"
149 +
150 +# Good
151 +from python.helpers import secrets
152 +api_key = secrets.get("API_KEY")
153 +```
154 +
155 +## Testing
156 +
157 +### Unit Tests
158 +
159 +Write tests for tools:
160 +
161 +```python
162 +import pytest
163 +from python.tools.my_tool import MyTool
164 +
165 +@pytest.mark.asyncio
166 +async def test_my_tool_success():
167 + tool = MyTool()
168 + result = await tool.execute(param="valid_value")
169 + assert "success" in result.message
170 +
171 +@pytest.mark.asyncio
172 +async def test_my_tool_error():
173 + tool = MyTool()
174 + result = await tool.execute(param="")
175 + assert "error" in result.message.lower()
176 +```
177 +
178 +### Integration Tests
179 +
180 +Test full workflows:
181 +
182 +```python
183 +@pytest.mark.asyncio
184 +async def test_tool_integration():
185 + # Setup
186 + context = create_test_context()
187 +
188 + # Execute
189 + tool = MyTool()
190 + tool.agent = MockAgent(context)
191 + result = await tool.execute(data="test")
192 +
193 + # Verify
194 + assert result.break_loop is False
195 + assert "result" in context.data
196 +```
197 +
198 +## Memory Management
199 +
200 +### Context Data
201 +
202 +Use context for session-wide state:
203 +
204 +```python
205 +# Store data
206 +self.agent.context.data["processed_items"] = items
207 +
208 +# Retrieve with default
209 +items = self.agent.context.data.get("processed_items", [])
210 +```
211 +
212 +### Memory Operations
213 +
214 +Save important information:
215 +
216 +```python
217 +from python.helpers.memory import memory_save
218 +
219 +# Save with metadata
220 +memory_save(
221 + text="Important fact",
222 + metadata={"category": "user_preference", "timestamp": time.time()}
223 +)
224 +```
225 +
226 +## Tool Design
227 +
228 +### Single Responsibility
229 +
230 +Each tool should do one thing well:
231 +
232 +```python
233 +# Good: WebSearch tool only searches
234 +class WebSearch(Tool):
235 + async def execute(self, **kwargs):
236 + query = kwargs.get("query")
237 + results = await search_web(query)
238 + return Response(message=format_results(results))
239 +
240 +# Bad: WebSearchAndSummarize does too much
241 +```
242 +
243 +### Composable Tools
244 +
245 +Tools should work together:
246 +
247 +```python
248 +# SearchTool finds information
249 +results = await search_tool.execute(query="Python async")
250 +
251 +# SummaryTool summarizes it
252 +summary = await summary_tool.execute(text=results.message)
253 +```
254 +
255 +## Extension Design
256 +
257 +### Minimal Interference
258 +
259 +Extensions should be lightweight:
260 +
261 +```python
262 +# Good: Quick check and return
263 +async def execute(self, **kwargs):
264 + if not self.should_process(kwargs):
265 + return kwargs.get("data", {})
266 + # Process...
267 +
268 +# Bad: Heavy processing in extension
269 +async def execute(self, **kwargs):
270 + # Don't do this - slows down every message
271 + result = await heavy_computation()
272 +```
273 +
274 +### Data Preservation
275 +
276 +Always return data unless modifying:
277 +
278 +```python
279 +# Good: Returns data even if not modified
280 +async def execute(self, **kwargs):
281 + data = kwargs.get("data", {})
282 + # Do something...
283 + return data
284 +
285 +# Bad: Returns None
286 +async def execute(self, **kwargs):
287 + data = kwargs.get("data", {})
288 + # Do something...
289 + # Missing return!
290 +```
291 +
292 +## API Design
293 +
294 +### RESTful Endpoints
295 +
296 +Follow REST conventions:
297 +
298 +```python
299 +# GET for retrieval
300 +async def _handle_get(self, input, context):
301 + item_id = input.get("id")
302 + item = await self.get_item(item_id)
303 + return {"data": item}
304 +
305 +# POST for creation
306 +async def _handle_post(self, input, request, context):
307 + data = input.get("data")
308 + created = await self.create_item(data)
309 + return {"data": created, "created": True}
310 +```
311 +
312 +### Consistent Responses
313 +
314 +Return consistent structures:
315 +
316 +```python
317 +# Success
318 +{
319 + "success": True,
320 + "data": {...},
321 + "context": "ctx-id"
322 +}
323 +
324 +# Error
325 +{
326 + "success": False,
327 + "error": "Error message",
328 + "context": "ctx-id"
329 +}
330 +```
331 +
332 +## Skill Design
333 +
334 +### Clear Instructions
335 +
336 +Skills should have actionable steps:
337 +
338 +```markdown
339 +## The Process
340 +
341 +### Step 1: Analyze Input
342 +- Check for required parameters
343 +- Validate data format
344 +
345 +### Step 2: Process Data
346 +- Apply transformation X
347 +- Verify intermediate result
348 +
349 +### Step 3: Return Output
350 +- Format as JSON
351 +- Include metadata
352 +```
353 +
354 +### Trigger Patterns
355 +
356 +Use specific trigger patterns:
357 +
358 +```yaml
359 +trigger_patterns:
360 + # Good: Specific
361 + - "analyze data"
362 + - "data analysis"
363 + - "process dataset"
364 +
365 + # Bad: Too generic
366 + - "do"
367 + - "make"
368 +```
369 +
370 +## Debugging
371 +
372 +### Verbose Logging
373 +
374 +Add detailed logging during development:
375 +
376 +```python
377 +PrintStyle.hint(f"Processing {len(items)} items")
378 +PrintStyle.hint(f"First item: {items[0] if items else 'empty'}")
379 +```
380 +
381 +### Remove Before Commit
382 +
383 +Clean up debug code:
384 +
385 +```python
386 +# Development
387 +PrintStyle.hint(f"DEBUG: kwargs = {kwargs}")
388 +
389 +# Production
390 +# Remove or convert to proper logging
391 +```
392 +
393 +## Deployment
394 +
395 +### Environment Variables
396 +
397 +Use env vars for configuration:
398 +
399 +```python
400 +import os
401 +
402 +DEBUG = os.getenv("DEBUG", "false").lower() == "true"
403 +MAX_WORKERS = int(os.getenv("MAX_WORKERS", "4"))
404 +```
405 +
406 +### Feature Flags
407 +
408 +Use flags for gradual rollout:
409 +
410 +```python
411 +ENABLE_NEW_FEATURE = os.getenv("ENABLE_NEW_FEATURE", "false") == "true"
412 +
413 +async def execute(self, **kwargs):
414 + if ENABLE_NEW_FEATURE:
415 + return await self.new_implementation(kwargs)
416 + else:
417 + return await self.old_implementation(kwargs)
418 +```
419 +
420 +## Documentation
421 +
422 +### README Files
423 +
424 +Every component needs a README:
425 +
426 +```markdown
427 +# Component Name
428 +
429 +## Purpose
430 +What this component does
431 +
432 +## Usage
433 +How to use it
434 +
435 +## Configuration
436 +Configuration options
437 +
438 +## Examples
439 +Code examples
440 +```
441 +
442 +### Code Comments
443 +
444 +Comment complex logic:
445 +
446 +```python
447 +# Use binary search for O(log n) performance
448 +# instead of linear scan O(n)
449 +index = binary_search(sorted_data, target)
450 +```
skills/frameworks/agent-zero-dev/docs/quickstart.md new
+63
@@ -0,0 +1,63 @@
1 +# Agent Zero Development Quickstart
2 +
3 +Get started extending Agent Zero in 5 minutes.
4 +
5 +## Prerequisites
6 +
7 +- Agent Zero framework installed and running
8 +- Basic understanding of Python async/await
9 +- Familiarity with the framework structure
10 +
11 +## 1. Create Your First Tool (2 minutes)
12 +
13 +```bash
14 +cd /a0/skills/frameworks/agent-zero-dev
15 +python scripts/create_tool.py WeatherLookup "Get weather information for locations"
16 +```
17 +
18 +This creates `/a0/python/tools/weather_lookup.py` with full boilerplate.
19 +
20 +Edit the file to implement your logic:
21 +
22 +```python
23 +async def _process(self, location: str, units: str) -> str:
24 + # Your weather API call here
25 + return f"Weather for {location}: 72°F, Sunny"
26 +```
27 +
28 +Restart Agent Zero to load the new tool.
29 +
30 +## 2. Create Your First Extension (2 minutes)
31 +
32 +```bash
33 +python scripts/create_extension.py agent_init ConfigLoader "Load project configuration"
34 +```
35 +
36 +Edit the generated file to add initialization logic.
37 +
38 +## 3. Create Your First Skill (3 minutes)
39 +
40 +```bash
41 +python scripts/create_skill.py my-skill "My custom skill description"
42 +```
43 +
44 +Edit `SKILL.md` to add instructions, then test with:
45 +"Use my-skill to process data"
46 +
47 +## 4. Create Your First API Endpoint (3 minutes)
48 +
49 +```bash
50 +python scripts/create_api.py DataApi "API for data operations"
51 +```
52 +
53 +Test with curl:
54 +```bash
55 +curl "http://localhost:5001/api/data_api?context=test&param=value"
56 +```
57 +
58 +## Next Steps
59 +
60 +- Read the full [SKILL.md](../SKILL.md) for comprehensive documentation
61 +- Explore existing tools in `/a0/python/tools/`
62 +- Check out built-in skills in `/a0/skills/builtin/`
63 +- Review the Superpowers framework for development workflows
skills/frameworks/agent-zero-dev/scripts/create_api.py new
+154
@@ -0,0 +1,154 @@
1 +#!/usr/bin/env python3
2 +"""
3 +Create API Endpoint Boilerplate
4 +Generates a new Agent Zero API endpoint with proper structure and patterns.
5 +
6 +Usage:
7 + python create_api.py EndpointName "Description"
8 + python create_api.py TaskManager "Manage async tasks"
9 +
10 +Output:
11 + Creates python/api/endpoint_name.py with full boilerplate
12 +"""
13 +
14 +import sys
15 +import re
16 +from pathlib import Path
17 +
18 +
19 +def to_snake_case(name: str) -> str:
20 + """Convert CamelCase or spaced name to snake_case."""
21 + name = name.replace(" ", "_")
22 + s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
23 + return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
24 +
25 +
26 +def to_class_name(name: str) -> str:
27 + """Convert snake_case or spaced name to CamelCase."""
28 + return ''.join(word.capitalize() for word in name.replace('_', ' ').split())
29 +
30 +
31 +def generate_api_code(class_name: str, endpoint_name: str, description: str) -> str:
32 + """Generate the API endpoint boilerplate code."""
33 + return f'''from python.helpers.api import ApiHandler, Request, Response
34 +from agent import AgentContext
35 +from python.helpers.print_style import PrintStyle
36 +
37 +
38 +class {class_name}(ApiHandler):
39 + """
40 + {description}
41 +
42 + Endpoint: /api/{endpoint_name}
43 + Methods: GET, POST (as needed)
44 + """
45 +
46 + async def process(self, input: dict, request: Request) -> dict | Response:
47 + """
48 + Process the API request.
49 +
50 + Args:
51 + input: Parsed JSON body or query parameters
52 + request: Werkzeug Request object
53 +
54 + Returns:
55 + dict response or Response object
56 + """
57 + # Get context (creates new if ctxid is empty)
58 + ctxid = input.get("context", "")
59 + context = self.use_context(ctxid)
60 +
61 + # Handle different HTTP methods
62 + if request.method == "GET":
63 + return await self._handle_get(input, context)
64 + elif request.method == "POST":
65 + return await self._handle_post(input, request, context)
66 + else:
67 + return {{
68 + "success": False,
69 + "error": f"Method {{request.method}} not supported"
70 + }}
71 +
72 + async def _handle_get(self, input: dict, context: AgentContext) -> dict:
73 + """Handle GET requests."""
74 + # TODO: Implement GET logic
75 + param = input.get("param", "default")
76 +
77 + return {{
78 + "success": True,
79 + "data": {{
80 + "message": f"GET request processed with param: {{param}}",
81 + "context": context.id
82 + }}
83 + }}
84 +
85 + async def _handle_post(self, input: dict, request: Request, context: AgentContext) -> dict:
86 + """Handle POST requests."""
87 + # TODO: Implement POST logic
88 + # Access JSON body: input.get("field")
89 + # Access form data: request.form.get("field")
90 + # Access files: request.files.get("file")
91 +
92 + data = input.get("data", {{}})
93 +
94 + PrintStyle.hint(f"{class_name} processing POST request")
95 +
96 + return {{
97 + "success": True,
98 + "data": {{
99 + "message": "POST request processed",
100 + "received": data,
101 + "context": context.id
102 + }}
103 + }}
104 +'''
105 +
106 +
107 +def main():
108 + if len(sys.argv) < 2:
109 + print("Usage: python create_api.py EndpointName [\"Description\"]")
110 + print("Example: python create_api.py TaskManager \"Manage async tasks\"")
111 + print("\nThe endpoint will be accessible at /api/endpoint-name")
112 + sys.exit(1)
113 +
114 + endpoint_input = sys.argv[1]
115 + description = sys.argv[2] if len(sys.argv) > 2 else f"{endpoint_input} API endpoint"
116 +
117 + class_name = to_class_name(endpoint_input)
118 + endpoint_name = to_snake_case(endpoint_input)
119 +
120 + # Generate code
121 + code = generate_api_code(class_name, endpoint_name, description)
122 +
123 + # Determine output path
124 + output_dir = Path("/a0/python/api")
125 + if not output_dir.exists():
126 + output_dir = Path("python/api")
127 +
128 + output_file = output_dir / f"{endpoint_name}.py"
129 +
130 + # Check if file exists
131 + if output_file.exists():
132 + print(f"Error: File already exists: {output_file}")
133 + print("Use a different name or delete the existing file.")
134 + sys.exit(1)
135 +
136 + # Write file
137 + output_file.write_text(code)
138 +
139 + print(f"✅ Created API endpoint: {output_file}")
140 + print(f" Class: {class_name}")
141 + print(f" Endpoint: /api/{endpoint_name}")
142 + print(f" URL: http://localhost:5001/api/{endpoint_name}")
143 + print(f"\nNext steps:")
144 + print(f" 1. Edit {output_file} to implement your logic")
145 + print(f" 2. Add route registration if needed (check python/api/__init__.py)")
146 + print(f" 3. Test with curl or the Web UI")
147 + print(f" 4. Restart Agent Zero to load the new endpoint")
148 + print(f"\nExample curl commands:")
149 + print(f' GET: curl "http://localhost:5001/api/{endpoint_name}?context=test&param=value"')
150 + print(f' POST: curl -X POST "http://localhost:5001/api/{endpoint_name}" -H "Content-Type: application/json" -d \'{{"context":"test","data":{{"key":"value"}}}}\'')
151 +
152 +
153 +if __name__ == "__main__":
154 + main()
skills/frameworks/agent-zero-dev/scripts/create_extension.py new
+167
@@ -0,0 +1,167 @@
1 +#!/usr/bin/env python3
2 +"""
3 +Create Extension Boilerplate
4 +Generates a new Agent Zero extension with proper structure and patterns.
5 +
6 +Usage:
7 + python create_extension.py hook_point ExtensionName "Description"
8 + python create_extension.py agent_init ConfigLoader "Load custom configuration"
9 +
10 +Hook Points:
11 + - agent_init
12 + - message_loop_start
13 + - message_loop_end
14 + - before_main_llm_call
15 + - response_stream_start
16 + - response_stream_chunk
17 + - response_stream_end
18 + - tool_execute_before
19 + - tool_execute_after
20 +
21 +Output:
22 + Creates python/extensions/<hook_point>/_XX_extension_name.py
23 +"""
24 +
25 +import sys
26 +import re
27 +from pathlib import Path
28 +
29 +
30 +def to_snake_case(name: str) -> str:
31 + """Convert CamelCase or spaced name to snake_case."""
32 + name = name.replace(" ", "_")
33 + s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
34 + return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
35 +
36 +
37 +def to_class_name(name: str) -> str:
38 + """Convert snake_case or spaced name to CamelCase."""
39 + return ''.join(word.capitalize() for word in name.replace('_', ' ').split())
40 +
41 +
42 +def get_next_number(extension_dir: Path) -> int:
43 + """Get the next available extension number."""
44 + if not extension_dir.exists():
45 + return 10
46 +
47 + existing = [f for f in extension_dir.iterdir() if f.suffix == '.py' and f.stem.startswith('_')]
48 + numbers = []
49 + for f in existing:
50 + match = re.match(r'_(\d+)_.*', f.stem)
51 + if match:
52 + numbers.append(int(match.group(1)))
53 +
54 + if numbers:
55 + # Round up to next 10
56 + max_num = max(numbers)
57 + return ((max_num // 10) + 1) * 10
58 + return 10
59 +
60 +
61 +def generate_extension_code(class_name: str, description: str, hook_point: str) -> str:
62 + """Generate the extension boilerplate code."""
63 + return f'''from python.helpers.extension import Extension
64 +from python.helpers.print_style import PrintStyle
65 +
66 +
67 +class {class_name}(Extension):
68 + """
69 + {description}
70 +
71 + Hook Point: {hook_point}
72 + """
73 +
74 + async def execute(self, **kwargs):
75 + """
76 + Execute the extension logic.
77 +
78 + Common kwargs by hook point:
79 + - agent_init: {{}}
80 + - message_loop_start: {{"message": str}}
81 + - before_main_llm_call: {{"prompts": list}}
82 + - response_stream_chunk: {{"chunk": str}}
83 + - tool_execute_before: {{"tool_name": str, "arguments": dict}}
84 + - tool_execute_after: {{"tool_name": str, "result": any}}
85 + """
86 + agent = self.agent
87 + context = agent.context
88 +
89 + # Access hook-specific data
90 + data = kwargs.get("data", {{}})
91 +
92 + try:
93 + # TODO: Implement your extension logic
94 + PrintStyle.hint(f"{class_name} executing for {hook_point}")
95 +
96 + # Example: Modify data if applicable
97 + # data["modified"] = True
98 +
99 + return data
100 +
101 + except Exception as e:
102 + PrintStyle.error(f"Error in {class_name}: {{e}}")
103 + return data
104 +'''
105 +
106 +
107 +def main():
108 + valid_hooks = [
109 + "agent_init", "message_loop_start", "message_loop_end",
110 + "before_main_llm_call", "response_stream_start", "response_stream_chunk",
111 + "response_stream_end", "tool_execute_before", "tool_execute_after"
112 + ]
113 +
114 + if len(sys.argv) < 3:
115 + print("Usage: python create_extension.py hook_point ExtensionName [\"Description\"]")
116 + print("\nValid hook points: " + ", ".join(valid_hooks))
117 + print("\nExample: python create_extension.py agent_init ConfigLoader")
118 + sys.exit(1)
119 +
120 + hook_point = sys.argv[1]
121 + ext_name = sys.argv[2]
122 + description = sys.argv[3] if len(sys.argv) > 3 else f"{ext_name} extension"
123 +
124 + if hook_point not in valid_hooks:
125 + print(f"Error: Invalid hook point '{hook_point}'")
126 + print(f"Valid hook points: {', '.join(valid_hooks)}")
127 + sys.exit(1)
128 +
129 + class_name = to_class_name(ext_name)
130 + ext_file_name = to_snake_case(ext_name)
131 +
132 + # Determine output path
133 + base_dir = Path("/a0/python/extensions")
134 + if not base_dir.exists():
135 + base_dir = Path("python/extensions")
136 +
137 + extension_dir = base_dir / hook_point
138 +
139 + # Get next number
140 + number = get_next_number(extension_dir)
141 +
142 + # Create directory if needed
143 + extension_dir.mkdir(parents=True, exist_ok=True)
144 +
145 + output_file = extension_dir / f"_{number}_{ext_file_name}.py"
146 +
147 + # Check if file exists
148 + if output_file.exists():
149 + print(f"Error: File already exists: {output_file}")
150 + sys.exit(1)
151 +
152 + # Generate and write code
153 + code = generate_extension_code(class_name, description, hook_point)
154 + output_file.write_text(code)
155 +
156 + print(f"✅ Created extension: {output_file}")
157 + print(f" Class: {class_name}")
158 + print(f" Hook Point: {hook_point}")
159 + print(f"\nNext steps:")
160 + print(f" 1. Edit {output_file} to implement your logic")
161 + print(f" 2. Check kwargs for your specific hook point")
162 + print(f" 3. Test by running the framework")
163 + print(f" 4. Restart Agent Zero to load the extension")
164 +
165 +
166 +if __name__ == "__main__":
167 + main()
skills/frameworks/agent-zero-dev/scripts/create_skill.py new
+231
@@ -0,0 +1,231 @@
1 +#!/usr/bin/env python3
2 +"""
3 +Create Skill Boilerplate
4 +Generates a new Agent Zero skill with SKILL.md and directory structure.
5 +
6 +Usage:
7 + python create_skill.py skill-name "Description of the skill"
8 + python create_skill.py web-scraper "Scrape web pages for data extraction"
9 +
10 +Output:
11 + Creates skills/custom/<skill-name>/ directory with SKILL.md
12 +"""
13 +
14 +import sys
15 +import re
16 +from pathlib import Path
17 +from datetime import datetime
18 +
19 +
20 +def validate_skill_name(name: str) -> str:
21 + """Validate and normalize skill name."""
22 + # Remove leading/trailing whitespace
23 + name = name.strip()
24 + # Replace spaces with hyphens
25 + name = name.replace(" ", "-")
26 + # Ensure only lowercase letters, numbers, and hyphens
27 + if not re.match(r'^[a-z0-9-]+$', name):
28 + raise ValueError(f"Invalid skill name: {name}. Use only lowercase letters, numbers, and hyphens.")
29 + return name
30 +
31 +
32 +def generate_skill_md(name: str, description: str, author: str) -> str:
33 + """Generate the SKILL.md content."""
34 + # Generate trigger patterns based on name and description
35 + words = name.replace("-", " ").split()
36 + trigger_patterns = [
37 + f'"{name}"',
38 + f'"{" ".join(words)}"',
39 + ]
40 +
41 + # Add description words as triggers
42 + desc_words = description.lower().split()[:3]
43 + if desc_words:
44 + trigger_patterns.append(f'"{" ".join(desc_words)}"')
45 +
46 + triggers_str = "\n - ".join(trigger_patterns)
47 +
48 + return f'''---
49 +name: "{name}"
50 +description: "{description}"
51 +version: "1.0.0"
52 +author: "{author}"
53 +tags: ["custom", "helper"]
54 +trigger_patterns:
55 + - {triggers_str}
56 +---
57 +
58 +# {name.replace("-", " ").title()}
59 +
60 +## When to Use
61 +
62 +This skill activates when users mention:
63 +- Keywords: {name}
64 +- Related concepts: {description}
65 +
66 +Use this skill to:
67 +1. First use case
68 +2. Second use case
69 +3. Third use case
70 +
71 +## The Process
72 +
73 +### Step 1: Preparation
74 +Describe initial setup or validation steps.
75 +
76 +### Step 2: Main Processing
77 +Detail the core functionality.
78 +
79 +### Step 3: Finalization
80 +Explain output formatting and delivery.
81 +
82 +## Examples
83 +
84 +### Example 1: Basic Usage
85 +
86 +**User**: "Use {name} to..."
87 +
88 +**Agent**:
89 +> I'll help you with that. Here's what I'll do:
90 +> 1. Step one
91 +> 2. Step two
92 +> 3. Step three
93 +
94 +### Example 2: Advanced Usage
95 +
96 +**User**: "Complex {name} task with parameters"
97 +
98 +**Agent**:
99 +> Processing with custom parameters...
100 +> - Parameter A: value
101 +> - Parameter B: value
102 +> Result: success
103 +
104 +## Scripts and Resources
105 +
106 +This skill includes optional helper scripts:
107 +
108 +| Script | Purpose | Usage |
109 +|--------|---------|-------|
110 +| `scripts/helper.py` | Description | `python scripts/helper.py arg1 arg2` |
111 +
112 +To use scripts:
113 +```json
114 +{{
115 + "method": "execute_script",
116 + "skill_name": "{name}",
117 + "script_path": "scripts/helper.py",
118 + "script_args": {{"arg1": "value"}},
119 + "arg_style": "positional"
120 +}}
121 +```
122 +
123 +## Best Practices
124 +
125 +### DO
126 +- ✅ Best practice 1
127 +- ✅ Best practice 2
128 +- ✅ Best practice 3
129 +
130 +### DON'T
131 +- ❌ Anti-pattern 1
132 +- ❌ Anti-pattern 2
133 +
134 +## Tips and Tricks
135 +
136 +- Tip 1
137 +- Tip 2
138 +- Tip 3
139 +
140 +## Common Issues
141 +
142 +| Issue | Cause | Solution |
143 +|-------|-------|----------|
144 +| Problem | Root cause | How to fix |
145 +
146 +## Related Skills
147 +
148 +- `related-skill-1` - Related functionality
149 +- `related-skill-2` - Complementary feature
150 +'''
151 +
152 +
153 +def main():
154 + if len(sys.argv) < 2:
155 + print("Usage: python create_skill.py skill-name [\"Description\"]")
156 + print("Example: python create_skill.py data-processor \"Process and transform data\"")
157 + print("\nSkill name rules:")
158 + print(" - Use lowercase letters, numbers, and hyphens only")
159 + print(" - No spaces (use hyphens)")
160 + print(" - Example: web-scraper, data-processor, api-client")
161 + sys.exit(1)
162 +
163 + try:
164 + skill_name = validate_skill_name(sys.argv[1])
165 + except ValueError as e:
166 + print(f"Error: {e}")
167 + sys.exit(1)
168 +
169 + description = sys.argv[2] if len(sys.argv) > 2 else f"Skill for {skill_name}"
170 + author = "Agent Zero User"
171 +
172 + # Determine output path
173 + base_dir = Path("/a0/skills/custom")
174 + if not base_dir.exists():
175 + base_dir = Path("skills/custom")
176 +
177 + skill_dir = base_dir / skill_name
178 +
179 + # Check if skill already exists
180 + if skill_dir.exists():
181 + print(f"Error: Skill already exists: {skill_dir}")
182 + print("Use a different name or delete the existing skill.")
183 + sys.exit(1)
184 +
185 + # Create directory structure
186 + skill_dir.mkdir(parents=True)
187 + (skill_dir / "scripts").mkdir()
188 + (skill_dir / "templates").mkdir()
189 + (skill_dir / "docs").mkdir()
190 +
191 + # Create SKILL.md
192 + skill_md = skill_dir / "SKILL.md"
193 + skill_md.write_text(generate_skill_md(skill_name, description, author))
194 +
195 + # Create placeholder files
196 + (skill_dir / "scripts" / "helper.py").write_text("""#!/usr/bin/env python3
197 +# Helper script for skill
198 +
199 +def main():
200 + print("Helper script placeholder")
201 + # TODO: Implement script logic
202 +
203 +if __name__ == "__main__":
204 + main()
205 +""")
206 +
207 + (skill_dir / "templates" / "template.md").write_text("# Template placeholder\n\nEdit this template as needed.")
208 + (skill_dir / "docs" / "examples.md").write_text("# Examples\n\nAdd usage examples here.")
209 +
210 + print(f"✅ Created skill: {skill_dir}")
211 + print(f" Name: {skill_name}")
212 + print(f" Description: {description}")
213 + print(f"\nStructure:")
214 + print(f" {skill_dir}/")
215 + print(f" ├── SKILL.md # Main skill file (EDIT THIS)")
216 + print(f" ├── scripts/")
217 + print(f" │ └── helper.py # Helper script")
218 + print(f" ├── templates/")
219 + print(f" │ └── template.md # Template file")
220 + print(f" └── docs/")
221 + print(f" └── examples.md # Documentation")
222 + print(f"\nNext steps:")
223 + print(f" 1. Edit {skill_dir}/SKILL.md to add your instructions")
224 + print(f" 2. Update trigger_patterns for activation")
225 + print(f" 3. Implement scripts in scripts/")
226 + print(f" 4. Test the skill by using trigger words")
227 + print(f" 5. Skills load automatically on agent initialization")
228 +
229 +
230 +if __name__ == "__main__":
231 + main()
skills/frameworks/agent-zero-dev/scripts/create_tool.py new
+128
@@ -0,0 +1,128 @@
1 +#!/usr/bin/env python3
2 +"""
3 +Create Tool Boilerplate
4 +Generates a new Agent Zero tool with proper structure and patterns.
5 +
6 +Usage:
7 + python create_tool.py ToolName "Description of what the tool does"
8 + python create_tool.py WeatherLookup "Get weather information for locations"
9 +
10 +Output:
11 + Creates python/tools/tool_name.py with full boilerplate
12 +"""
13 +
14 +import sys
15 +import re
16 +from pathlib import Path
17 +
18 +
19 +def to_snake_case(name: str) -> str:
20 + """Convert CamelCase or spaced name to snake_case."""
21 + # Handle spaces first
22 + name = name.replace(" ", "_")
23 + # Insert underscore before capital letters
24 + s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
25 + return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
26 +
27 +
28 +def to_class_name(name: str) -> str:
29 + """Convert snake_case or spaced name to CamelCase."""
30 + # Remove spaces and underscores, capitalize each word
31 + return ''.join(word.capitalize() for word in name.replace('_', ' ').split())
32 +
33 +
34 +def generate_tool_code(class_name: str, tool_name: str, description: str) -> str:
35 + """Generate the tool boilerplate code."""
36 + return f'''from python.helpers.tool import Tool, Response
37 +
38 +
39 +class {class_name}(Tool):
40 + """
41 + {description}
42 +
43 + Arguments (tool_args):
44 + - param1: Description of first parameter
45 + - param2: Description of second parameter
46 +
47 + Returns:
48 + Response object with result message
49 + """
50 +
51 + async def execute(self, **kwargs) -> Response:
52 + # Get arguments from kwargs with fallback to self.args
53 + param1 = kwargs.get("param1") or self.args.get("param1", "")
54 + param2 = kwargs.get("param2") or self.args.get("param2", "")
55 +
56 + try:
57 + # TODO: Implement your tool logic here
58 + result = await self._process(param1, param2)
59 +
60 + return Response(
61 + message=result,
62 + break_loop=False
63 + )
64 + except Exception as e:
65 + return Response(
66 + message=f"Error in {class_name}: {{e}}",
67 + break_loop=False
68 + )
69 +
70 + async def _process(self, param1: str, param2: str) -> str:
71 + """
72 + Implement your main tool logic here.
73 +
74 + Args:
75 + param1: First parameter
76 + param2: Second parameter
77 +
78 + Returns:
79 + Result string to return to agent
80 + """
81 + # TODO: Replace with actual implementation
82 + return f"Processed {{param1}} and {{param2}}"
83 +'''
84 +
85 +
86 +def main():
87 + if len(sys.argv) < 2:
88 + print("Usage: python create_tool.py ToolName [\"Description\"]")
89 + print("Example: python create_tool.py WeatherLookup \"Get weather for locations\"")
90 + sys.exit(1)
91 +
92 + tool_input = sys.argv[1]
93 + description = sys.argv[2] if len(sys.argv) > 2 else f"{tool_input} tool"
94 +
95 + class_name = to_class_name(tool_input)
96 + tool_name = to_snake_case(tool_input)
97 +
98 + # Generate code
99 + code = generate_tool_code(class_name, tool_name, description)
100 +
101 + # Determine output path
102 + output_dir = Path("/a0/python/tools")
103 + if not output_dir.exists():
104 + # Try relative path
105 + output_dir = Path("python/tools")
106 +
107 + output_file = output_dir / f"{tool_name}.py"
108 +
109 + # Check if file exists
110 + if output_file.exists():
111 + print(f"Error: File already exists: {output_file}")
112 + print("Use a different name or delete the existing file.")
113 + sys.exit(1)
114 +
115 + # Write file
116 + output_file.write_text(code)
117 + print(f"✅ Created tool: {output_file}")
118 + print(f" Class: {class_name}")
119 + print(f" Tool name (snake_case): {tool_name}")
120 + print(f"\nNext steps:")
121 + print(f" 1. Edit {output_file} to implement your logic")
122 + print(f" 2. Update the docstring with actual arguments")
123 + print(f" 3. Test your tool with the agent")
124 + print(f" 4. Restart Agent Zero to load the new tool")
125 +
126 +
127 +if __name__ == "__main__":
128 + main()
skills/frameworks/agentos/agentos-project-install/SKILL.md new
+86
@@ -0,0 +1,86 @@
1 +---
2 +name: "agentos-project-install"
3 +description: "Initialize a project with AgentOS standard structure and configuration."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["agentos", "initialization", "setup"]
7 +trigger_patterns:
8 + - "install agentos"
9 + - "setup project"
10 + - "initialize agentos"
11 +---
12 +
13 +# AgentOS: Project Install
14 +
15 +Initialize a project with AgentOS standard structure and configuration files.
16 +
17 +## When to Use
18 +
19 +- Starting a new project with AgentOS
20 +- Converting existing project to AgentOS standards
21 +- Setting up development environment
22 +
23 +## Standard Structure
24 +
25 +```
26 +project/
27 +├── .agentos/
28 +│ ├── config.yaml # Project configuration
29 +│ ├── standards.yaml # Coding standards
30 +│ └── hooks/ # Git hooks
31 +├── docs/
32 +│ ├── README.md
33 +│ └── CONTRIBUTING.md
34 +├── src/
35 +├── tests/
36 +├── .gitignore
37 +├── .editorconfig
38 +└── Makefile
39 +```
40 +
41 +## Installation Process
42 +
43 +1. **Create Directory Structure**
44 + - Create `.agentos/` configuration directory
45 + - Set up standard folders
46 + - Add configuration files
47 +
48 +2. **Initialize Configuration**
49 + ```yaml
50 + # .agentos/config.yaml
51 + project:
52 + name: [Project Name]
53 + type: [web/cli/library]
54 + language: [Primary language]
55 +
56 + standards:
57 + linting: true
58 + formatting: true
59 + testing: required
60 +
61 + quality:
62 + coverage_minimum: 80
63 + review_required: true
64 + ```
65 +
66 +3. **Set Up Git Hooks**
67 + - Pre-commit: linting, formatting
68 + - Pre-push: tests
69 +
70 +4. **Create Documentation**
71 + - README template
72 + - Contributing guidelines
73 +
74 +## Output
75 +
76 +```markdown
77 +## AgentOS Installed: [Project Name]
78 +
79 +**Config**: `.agentos/config.yaml`
80 +**Standards**: Configured
81 +**Hooks**: Installed
82 +
83 +Project ready for development.
84 +
85 +Apply standards with `agentos-standards`.
86 +```
skills/frameworks/agentos/agentos-standards/SKILL.md new
+96
@@ -0,0 +1,96 @@
1 +---
2 +name: "agentos-standards"
3 +description: "Apply and verify AgentOS coding standards across the project."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["agentos", "standards", "quality"]
7 +trigger_patterns:
8 + - "apply standards"
9 + - "check standards"
10 + - "verify standards"
11 +---
12 +
13 +# AgentOS: Standards
14 +
15 +Apply and verify AgentOS coding standards across the project.
16 +
17 +## When to Use
18 +
19 +- After project install
20 +- Before committing code
21 +- During code review
22 +- Periodic quality checks
23 +
24 +## Standards Categories
25 +
26 +### 1. Code Style
27 +- Consistent formatting
28 +- Naming conventions
29 +- File organization
30 +
31 +### 2. Documentation
32 +- Function/method documentation
33 +- README completeness
34 +- API documentation
35 +
36 +### 3. Testing
37 +- Test coverage requirements
38 +- Test naming conventions
39 +- Test organization
40 +
41 +### 4. Security
42 +- No hardcoded secrets
43 +- Input validation
44 +- Error handling
45 +
46 +## Standards Check Process
47 +
48 +```markdown
49 +## Standards Verification: [Project Name]
50 +
51 +### Code Style
52 +- [ ] Formatting: [Tool] passing
53 +- [ ] Linting: [Tool] passing
54 +- [ ] Naming: Conventions followed
55 +
56 +### Documentation
57 +- [ ] README: Complete and current
58 +- [ ] Functions: Documented
59 +- [ ] API: Documented
60 +
61 +### Testing
62 +- [ ] Coverage: [X]% (minimum: 80%)
63 +- [ ] Tests: All passing
64 +- [ ] Structure: Follows conventions
65 +
66 +### Security
67 +- [ ] Secrets: None hardcoded
68 +- [ ] Validation: Input validated
69 +- [ ] Errors: Properly handled
70 +
71 +### Result
72 +**Status**: PASS/FAIL
73 +**Issues**: [Count]
74 +```
75 +
76 +## Fixing Violations
77 +
78 +For each violation:
79 +1. Identify the standard
80 +2. Locate the violation
81 +3. Apply the fix
82 +4. Verify the fix
83 +
84 +## Output
85 +
86 +```markdown
87 +## Standards Check: [Project Name]
88 +
89 +**Status**: PASS/FAIL
90 +**Violations**: [X]
91 +**Coverage**: [Y]%
92 +
93 +[List of issues if any]
94 +
95 +All standards met? Ready for commit/review.
96 +```
skills/frameworks/amplihack/amplihack-analyze/SKILL.md new
+72
@@ -0,0 +1,72 @@
1 +---
2 +name: "amplihack-analyze"
3 +description: "Deep analysis of code, requirements, or systems."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["amplihack", "analysis", "understanding"]
7 +trigger_patterns:
8 + - "analyze"
9 + - "deep dive"
10 + - "understand code"
11 +---
12 +
13 +# AMPLIHACK: Analyze
14 +
15 +Perform deep analysis of code, requirements, or systems.
16 +
17 +## When to Use
18 +
19 +- Need to understand existing code
20 +- Analyzing requirements for implementation
21 +- Investigating issues or bugs
22 +- Understanding system architecture
23 +
24 +## Analysis Modes
25 +
26 +### TRIAGE (Rapid Scanning)
27 +- Quick overview
28 +- Identify key components
29 +- Surface-level understanding
30 +
31 +### DEEP (Thorough Investigation)
32 +- Detailed code examination
33 +- Trace execution paths
34 +- Map dependencies
35 +
36 +### SYNTHESIS (Multi-source Integration)
37 +- Combine multiple analyses
38 +- Cross-reference findings
39 +- Build complete picture
40 +
41 +## Analysis Process
42 +
43 +1. **Determine Mode**: Based on task complexity
44 +2. **Gather Sources**: Files, docs, code
45 +3. **Execute Analysis**: Per selected mode
46 +4. **Document Findings**: Structured report
47 +
48 +## Output Format
49 +
50 +```markdown
51 +## Analysis Report: [Subject]
52 +
53 +### Summary
54 +[Key findings overview]
55 +
56 +### Components Identified
57 +- [Component 1]: [Purpose]
58 +- [Component 2]: [Purpose]
59 +
60 +### Dependencies
61 +```
62 +[Dependency graph or list]
63 +```
64 +
65 +### Key Insights
66 +1. [Insight 1]
67 +2. [Insight 2]
68 +
69 +### Recommendations
70 +- [Action 1]
71 +- [Action 2]
72 +```
skills/frameworks/amplihack/amplihack-auto/SKILL.md new
+60
@@ -0,0 +1,60 @@
1 +---
2 +name: "amplihack-auto"
3 +description: "Automatic workflow selection based on task analysis."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["amplihack", "workflow", "automatic"]
7 +trigger_patterns:
8 + - "auto workflow"
9 + - "amplihack auto"
10 + - "automatic"
11 +---
12 +
13 +# AMPLIHACK: Auto
14 +
15 +Automatically select the best workflow based on task analysis.
16 +
17 +## When to Use
18 +
19 +- Starting any task with AMPLIHACK
20 +- Unsure which workflow to use
21 +- Need intelligent workflow routing
22 +
23 +## Task Analysis
24 +
25 +Analyze the task to determine best workflow:
26 +
27 +| Task Type | Indicators | Recommended Workflow |
28 +|-----------|------------|---------------------|
29 +| Complex problem | Multiple valid approaches | `amplihack-debate` |
30 +| Code analysis | Understand existing code | `amplihack-analyze` |
31 +| Multi-step work | Sequential dependencies | `amplihack-cascade` |
32 +| Simple task | Clear requirements | Direct implementation |
33 +
34 +## Selection Process
35 +
36 +1. **Analyze Request**
37 + - What is being asked?
38 + - How complex is it?
39 + - What's the scope?
40 +
41 +2. **Check Indicators**
42 + - Multiple approaches possible? → Debate
43 + - Need deep understanding? → Analyze
44 + - Sequential steps needed? → Cascade
45 +
46 +3. **Select Workflow**
47 + - Route to appropriate skill
48 + - Explain selection rationale
49 +
50 +## Output
51 +
52 +```markdown
53 +## Auto Workflow Selection
54 +
55 +**Task**: [Summary]
56 +**Analysis**: [Why this workflow]
57 +**Selected**: [Workflow name]
58 +
59 +Proceeding with [workflow]...
60 +```
skills/frameworks/amplihack/amplihack-cascade/SKILL.md new
+82
@@ -0,0 +1,82 @@
1 +---
2 +name: "amplihack-cascade"
3 +description: "Multi-agent cascade pattern for complex sequential tasks."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["amplihack", "cascade", "multi-agent"]
7 +trigger_patterns:
8 + - "cascade"
9 + - "sequential workflow"
10 + - "multi-step"
11 +---
12 +
13 +# AMPLIHACK: Cascade
14 +
15 +Execute complex tasks using a cascade of specialized agents.
16 +
17 +## When to Use
18 +
19 +- Multi-step tasks with dependencies
20 +- Different expertise needed at each stage
21 +- Quality gates between phases
22 +
23 +## Cascade Pattern
24 +
25 +```
26 +[Input] → [Agent 1] → [Output 1] → [Agent 2] → [Output 2] → [Final Output]
27 +```
28 +
29 +Each agent:
30 +- Has specialized expertise
31 +- Receives previous output as input
32 +- Produces structured output for next agent
33 +- Can validate and fail-fast
34 +
35 +## Cascade Stages
36 +
37 +### Stage 1: Requirements
38 +- Parse and validate input
39 +- Identify scope and constraints
40 +- Output: Structured requirements
41 +
42 +### Stage 2: Design
43 +- Receive requirements
44 +- Create implementation design
45 +- Output: Technical specification
46 +
47 +### Stage 3: Implementation
48 +- Receive specification
49 +- Write code
50 +- Output: Implementation with tests
51 +
52 +### Stage 4: Verification
53 +- Receive implementation
54 +- Run tests and checks
55 +- Output: Verified code or failures
56 +
57 +## Execution
58 +
59 +```markdown
60 +## Cascade Execution: [Task]
61 +
62 +### Stage 1: Requirements
63 +**Input**: [User request]
64 +**Agent**: Requirements Analyst
65 +**Output**: Structured requirements
66 +**Status**: Complete
67 +
68 +### Stage 2: Design
69 +**Input**: Requirements from Stage 1
70 +**Agent**: Architect
71 +**Output**: Technical spec
72 +**Status**: In Progress
73 +
74 +...
75 +```
76 +
77 +## Failure Handling
78 +
79 +If a stage fails:
80 +1. Report failure
81 +2. Allow retry or revision
82 +3. Don't proceed until resolved
skills/frameworks/amplihack/amplihack-debate/SKILL.md new
+99
@@ -0,0 +1,99 @@
1 +---
2 +name: "amplihack-debate"
3 +description: "Multi-perspective debate workflow for complex decisions."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["amplihack", "debate", "decision-making"]
7 +trigger_patterns:
8 + - "debate"
9 + - "multiple perspectives"
10 + - "decision"
11 +---
12 +
13 +# AMPLIHACK: Debate
14 +
15 +Facilitate multi-perspective debate for complex technical decisions.
16 +
17 +## When to Use
18 +
19 +- Multiple valid approaches exist
20 +- High-stakes technical decisions
21 +- Need to surface trade-offs
22 +- Want rigorous analysis
23 +
24 +## Debate Structure
25 +
26 +### Participants (Perspectives)
27 +- **Advocate**: Argues for proposed approach
28 +- **Critic**: Challenges assumptions, finds weaknesses
29 +- **Pragmatist**: Focuses on practical concerns
30 +- **Moderator**: Synthesizes and drives to conclusion
31 +
32 +### Debate Rounds
33 +
34 +#### Round 1: Initial Arguments
35 +Each perspective presents their view:
36 +```markdown
37 +### Advocate
38 +[Arguments for approach]
39 +
40 +### Critic
41 +[Challenges and concerns]
42 +
43 +### Pragmatist
44 +[Practical considerations]
45 +```
46 +
47 +#### Round 2: Rebuttals
48 +Perspectives respond to each other:
49 +```markdown
50 +### Advocate Response
51 +[Address concerns, strengthen arguments]
52 +
53 +### Critic Response
54 +[Address rebuttals, raise new concerns]
55 +
56 +### Pragmatist Response
57 +[Reality check on both sides]
58 +```
59 +
60 +#### Round 3: Convergence
61 +Work toward consensus:
62 +```markdown
63 +### Points of Agreement
64 +- [Agreed point 1]
65 +- [Agreed point 2]
66 +
67 +### Remaining Disagreements
68 +- [Disagreement 1]
69 +- [Disagreement 2]
70 +
71 +### Proposed Resolution
72 +[Synthesized approach]
73 +```
74 +
75 +## Output
76 +
77 +```markdown
78 +## Debate Conclusion: [Topic]
79 +
80 +### Decision
81 +[Final recommendation]
82 +
83 +### Rationale
84 +[Why this was chosen]
85 +
86 +### Acknowledged Risks
87 +- [Risk 1 and mitigation]
88 +- [Risk 2 and mitigation]
89 +
90 +### Dissenting Views
91 +[Any unresolved disagreements]
92 +```
93 +
94 +## Best Practices
95 +
96 +- Keep rounds focused
97 +- Require evidence for claims
98 +- Drive toward actionable conclusion
99 +- Document minority opinions
skills/frameworks/amplihack/amplihack-fix/SKILL.md new
+107
@@ -0,0 +1,107 @@
1 +---
2 +name: "amplihack-fix"
3 +description: "Systematic error resolution with pattern-specific context and workflow."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["amplihack", "fix", "debugging", "error-resolution"]
7 +trigger_patterns:
8 + - "fix"
9 + - "debug"
10 + - "resolve error"
11 + - "troubleshoot"
12 +---
13 +
14 +# AMPLIHACK: Fix
15 +
16 +Systematic error resolution using the DEFAULT_WORKFLOW pattern.
17 +
18 +## When to Use
19 +
20 +- When encountering errors or bugs
21 +- When tests are failing
22 +- When behavior doesn't match expectations
23 +- For systematic troubleshooting
24 +
25 +## The Fix Workflow
26 +
27 +The fix workflow follows a structured 22-step process for robust error resolution:
28 +
29 +### Phase 1: Understand
30 +
31 +1. **Reproduce** - Confirm the error occurs consistently
32 +2. **Isolate** - Identify minimal reproduction case
33 +3. **Document** - Capture error messages, stack traces, context
34 +
35 +### Phase 2: Analyze
36 +
37 +4. **Root Cause Analysis** - Trace error to origin
38 +5. **Impact Assessment** - Understand scope of issue
39 +6. **Pattern Matching** - Check for known error patterns
40 +
41 +### Phase 3: Fix
42 +
43 +7. **Design Solution** - Plan the fix approach
44 +8. **Implement Fix** - Make code changes
45 +9. **Verify Fix** - Confirm error is resolved
46 +
47 +### Phase 4: Harden
48 +
49 +10. **Add Tests** - Prevent regression
50 +11. **Document** - Update relevant documentation
51 +12. **Review** - Ensure fix is complete
52 +
53 +## Pattern-Specific Context
54 +
55 +The fix workflow adapts to error patterns:
56 +
57 +| Pattern | Focus |
58 +|---------|-------|
59 +| **Type Error** | Check types, interfaces, contracts |
60 +| **Runtime Error** | Trace execution path, check state |
61 +| **Logic Error** | Verify business logic, edge cases |
62 +| **Integration Error** | Check boundaries, APIs, data flow |
63 +| **Performance Issue** | Profile, measure, optimize |
64 +
65 +## Fix Output Format
66 +
67 +```markdown
68 +## Fix Report: {Error Description}
69 +
70 +### Error Summary
71 +- **Type:** [Error type/pattern]
72 +- **Location:** [File:line or component]
73 +- **Impact:** [Scope of issue]
74 +
75 +### Root Cause
76 +[Description of why the error occurs]
77 +
78 +### Solution
79 +[Description of the fix]
80 +
81 +### Changes Made
82 +1. `file1.ts:45` - [Change description]
83 +2. `file2.ts:89` - [Change description]
84 +
85 +### Verification
86 +- [ ] Error no longer occurs
87 +- [ ] Tests pass
88 +- [ ] No new errors introduced
89 +
90 +### Regression Prevention
91 +- [ ] Test added: [test description]
92 +```
93 +
94 +## Best Practices
95 +
96 +1. **Reproduce first** - Never fix what you can't reproduce
97 +2. **One fix at a time** - Don't combine multiple fixes
98 +3. **Test the fix** - Verify before declaring success
99 +4. **Add regression tests** - Prevent future occurrences
100 +5. **Document the root cause** - Help future debugging
101 +
102 +## Integration with AMPLIHACK
103 +
104 +The fix workflow can be triggered from:
105 +- `amplihack-auto` - When errors are detected
106 +- Direct invocation for known issues
107 +- Cascade workflows when a step fails
skills/frameworks/amplihack/amplihack-modular-build/SKILL.md new
+143
@@ -0,0 +1,143 @@
1 +---
2 +name: "amplihack-modular-build"
3 +description: "Build code following the brick philosophy with self-contained modules."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["amplihack", "modular", "build", "brick-philosophy"]
7 +trigger_patterns:
8 + - "modular build"
9 + - "build module"
10 + - "brick pattern"
11 + - "self-contained"
12 +---
13 +
14 +# AMPLIHACK: Modular Build
15 +
16 +Build code following the brick philosophy for self-contained, regeneratable modules.
17 +
18 +## The Brick Philosophy
19 +
20 +> "Each piece should be self-contained, testable, and replaceable without affecting others."
21 +
22 +### Core Principles
23 +
24 +1. **Self-Contained** - Module has everything it needs
25 +2. **Single Responsibility** - One clear purpose
26 +3. **Well-Defined Interface** - Clear inputs and outputs (studs)
27 +4. **Regeneratable** - Can be rebuilt without breaking others
28 +5. **Testable** - Can be tested in isolation
29 +
30 +## Module Structure
31 +
32 +```
33 +module/
34 +├── index.ts # Public interface (studs)
35 +├── implementation.ts # Private implementation
36 +├── types.ts # Type definitions
37 +├── constants.ts # Module constants
38 +└── module.test.ts # Module tests
39 +```
40 +
41 +## Building a Module
42 +
43 +### 1. Define the Interface (Studs)
44 +
45 +Start with what the module exposes:
46 +
47 +```typescript
48 +// index.ts - The studs (public interface)
49 +export interface ModuleInput {
50 + // What goes in
51 +}
52 +
53 +export interface ModuleOutput {
54 + // What comes out
55 +}
56 +
57 +export function moduleFunction(input: ModuleInput): ModuleOutput {
58 + // Implementation
59 +}
60 +```
61 +
62 +### 2. Hide Implementation Details
63 +
64 +Keep internals private:
65 +
66 +```typescript
67 +// implementation.ts - Private, can change freely
68 +function internalHelper() {
69 + // Not exported, can be modified without affecting users
70 +}
71 +```
72 +
73 +### 3. Define Clear Boundaries
74 +
75 +Each module should have:
76 +
77 +```markdown
78 +## Module Specification
79 +
80 +**Name:** {module-name}
81 +**Purpose:** [Single sentence describing what it does]
82 +
83 +**Inputs (Dependencies):**
84 +- [Input 1]: [Type] - [Description]
85 +- [Input 2]: [Type] - [Description]
86 +
87 +**Outputs (Provides):**
88 +- [Output 1]: [Type] - [Description]
89 +
90 +**Invariants:**
91 +- [Invariant 1] - [What must always be true]
92 +```
93 +
94 +### 4. Test in Isolation
95 +
96 +```typescript
97 +// module.test.ts
98 +describe('ModuleName', () => {
99 + it('should [expected behavior]', () => {
100 + const input: ModuleInput = { ... };
101 + const result = moduleFunction(input);
102 + expect(result).toEqual({ ... });
103 + });
104 +});
105 +```
106 +
107 +## Module Composition
108 +
109 +Connect modules through their studs:
110 +
111 +```
112 +┌─────────────┐ ┌─────────────┐ ┌─────────────┐
113 +│ Module A │────▶│ Module B │────▶│ Module C │
114 +│ (studs) │ │ (studs) │ │ (studs) │
115 +└─────────────┘ └─────────────┘ └─────────────┘
116 +```
117 +
118 +## Anti-Patterns to Avoid
119 +
120 +| Anti-Pattern | Problem | Solution |
121 +|-------------|---------|----------|
122 +| **Reaching into internals** | Couples to implementation | Use only public interface |
123 +| **Circular dependencies** | Can't reason about flow | Reorganize module boundaries |
124 +| **God modules** | Too many responsibilities | Split into focused modules |
125 +| **Leaky abstractions** | Implementation details escape | Better interface design |
126 +
127 +## Build Checklist
128 +
129 +Before considering a module complete:
130 +
131 +- [ ] Single, clear purpose
132 +- [ ] Well-defined interface (studs)
133 +- [ ] No leaked implementation details
134 +- [ ] Tests pass in isolation
135 +- [ ] Can be regenerated independently
136 +- [ ] Documentation for public interface
137 +
138 +## Integration with AMPLIHACK
139 +
140 +The modular build approach is used by:
141 +- `amplihack-cascade` - Each stage produces a module
142 +- `amplihack-auto` - Determines module boundaries
143 +- Primary build agent - Creates regeneratable code
skills/frameworks/bmad-builder/bmb-agent/SKILL.md new
+123
@@ -0,0 +1,123 @@
1 +---
2 +name: "bmb-agent"
3 +description: "Create specialized AI agents with custom expertise, communication styles, and tool access."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-builder", "agent", "creation", "customization"]
7 +trigger_patterns:
8 + - "build agent"
9 + - "create agent"
10 + - "new agent"
11 + - "agent builder"
12 + - "/bmb-agent"
13 +---
14 +
15 +# BMad Builder: Create Agent
16 +
17 +Build specialized AI agents with custom expertise and tools.
18 +
19 +## Overview
20 +
21 +The Agent Builder guides you through creating a custom BMad agent that can:
22 +- Have domain-specific expertise
23 +- Use a unique communication style
24 +- Access specific tools
25 +- Follow custom workflows
26 +
27 +## Process
28 +
29 +### 1. Define Domain
30 +
31 +What should this agent specialize in?
32 +
33 +**Questions to answer:**
34 +- What domain expertise does this agent need?
35 +- What problems will it solve?
36 +- Who will use this agent?
37 +
38 +### 2. Design Identity
39 +
40 +Create the agent's persona:
41 +
42 +```yaml
43 +identity:
44 + name: "[Agent Name]"
45 + role: "[Primary Role] + [Secondary Role]"
46 + experience: "[Years] years experience in [domain]"
47 + personality: "[Key traits]"
48 +```
49 +
50 +### 3. Communication Style
51 +
52 +How does the agent communicate?
53 +
54 +- **Formal/Technical**: For enterprise, compliance
55 +- **Casual/Friendly**: For creative, consumer
56 +- **Direct/Efficient**: For development, operations
57 +- **Mentoring/Educational**: For learning, onboarding
58 +
59 +### 4. Core Principles
60 +
61 +Define 3-5 guiding principles:
62 +
63 +```yaml
64 +principles:
65 + - "[Principle 1]"
66 + - "[Principle 2]"
67 + - "[Principle 3]"
68 +```
69 +
70 +### 5. Available Commands
71 +
72 +What commands should this agent support?
73 +
74 +| Command | Description |
75 +|---------|-------------|
76 +| `[command-1]` | [What it does] |
77 +| `[command-2]` | [What it does] |
78 +
79 +### 6. Tool Access
80 +
81 +Which tools does this agent need?
82 +
83 +- Code execution
84 +- File operations
85 +- Web search
86 +- API integrations
87 +- Custom tools
88 +
89 +## Output
90 +
91 +Generate the agent definition file:
92 +
93 +```yaml
94 +# agent-name.agent.yaml
95 +name: "[Agent Name]"
96 +role: "[Role Description]"
97 +identity: |
98 + [Full identity description]
99 +communication_style: |
100 + [Communication guidelines]
101 +principles:
102 + - [Principle 1]
103 + - [Principle 2]
104 +commands:
105 + - name: "[command]"
106 + description: "[description]"
107 +tools:
108 + - [tool1]
109 + - [tool2]
110 +```
111 +
112 +## Best Practices
113 +
114 +1. **Focused Expertise**: Agents work better with deep, narrow expertise than broad, shallow knowledge
115 +2. **Consistent Voice**: The communication style should match the domain
116 +3. **Clear Boundaries**: Define what the agent does NOT do
117 +4. **Testable Outputs**: Commands should produce verifiable results
118 +
119 +## Next Steps
120 +
121 +After creating an agent:
122 +- Use `bmb-workflow` to create workflows for the agent
123 +- Use `bmb-module` to package into a shareable module
skills/frameworks/bmad-builder/bmb-module/SKILL.md new
+166
@@ -0,0 +1,166 @@
1 +---
2 +name: "bmb-module"
3 +description: "Package agents and workflows into shareable BMad modules."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-builder", "module", "package", "distribution"]
7 +trigger_patterns:
8 + - "build module"
9 + - "create module"
10 + - "package module"
11 + - "module builder"
12 + - "/bmb-module"
13 +---
14 +
15 +# BMad Builder: Create Module
16 +
17 +Package agents and workflows into shareable BMad modules.
18 +
19 +## Overview
20 +
21 +Modules bundle related agents and workflows into distributable packages that can be:
22 +- Installed via `npx bmad-method install`
23 +- Shared on npm or GitHub
24 +- Versioned and maintained
25 +
26 +## Module Structure
27 +
28 +```
29 +your-module/
30 +├── src/
31 +│ ├── module.yaml # Module metadata and install config
32 +│ ├── agents/ # Agent definitions (.agent.yaml)
33 +│ ├── workflows/ # Workflow files
34 +│ └── tools/ # Small reusable tools
35 +├── docs/
36 +│ └── README.md # Module documentation
37 +├── package.json # NPM package info
38 +└── LICENSE
39 +```
40 +
41 +## Process
42 +
43 +### 1. Define Module Scope
44 +
45 +**Questions:**
46 +- What domain does this module serve?
47 +- What agents and workflows does it include?
48 +- Who is the target user?
49 +
50 +### 2. Create module.yaml
51 +
52 +```yaml
53 +# src/module.yaml
54 +name: "your-module-name"
55 +version: "1.0.0"
56 +description: "[Module purpose]"
57 +author: "[Your name/org]"
58 +
59 +# What gets installed
60 +agents:
61 + - agents/agent-one.agent.yaml
62 + - agents/agent-two.agent.yaml
63 +
64 +workflows:
65 + - workflows/workflow-one.yaml
66 + - workflows/workflow-two.yaml
67 +
68 +# Installation options
69 +install:
70 + required: [] # Always install these
71 + optional: # Let user choose
72 + - name: "[Feature Set]"
73 + description: "[What it adds]"
74 + includes:
75 + - agents/optional-agent.agent.yaml
76 +
77 +# Dependencies on other modules
78 +dependencies:
79 + - bmad-method@^1.0.0
80 +```
81 +
82 +### 3. Create package.json
83 +
84 +```json
85 +{
86 + "name": "bmad-module-your-name",
87 + "version": "1.0.0",
88 + "description": "BMad module for [domain]",
89 + "keywords": ["bmad", "bmad-method", "your-domain"],
90 + "repository": {
91 + "type": "git",
92 + "url": "https://github.com/your-org/your-module"
93 + },
94 + "files": ["src/"],
95 + "scripts": {
96 + "release": "npm version patch && git push --follow-tags"
97 + },
98 + "license": "MIT"
99 +}
100 +```
101 +
102 +### 4. Write Documentation
103 +
104 +Create `docs/README.md` with:
105 +- What the module does
106 +- Installation instructions
107 +- Quick start guide
108 +- Agent and workflow reference
109 +- Examples
110 +
111 +### 5. Test Locally
112 +
113 +Before publishing:
114 +
115 +```bash
116 +# Test installation
117 +npx bmad-method install --local ./path/to/module
118 +
119 +# Verify agents work
120 +# Run workflows
121 +# Check documentation renders
122 +```
123 +
124 +### 6. Publish
125 +
126 +```bash
127 +# Tag release
128 +git tag v1.0.0
129 +git push origin v1.0.0
130 +
131 +# Publish to npm (optional)
132 +npm publish
133 +```
134 +
135 +## Best Practices
136 +
137 +1. **Focused Scope**: One module = one domain
138 +2. **Complete Package**: Include docs, examples, and tests
139 +3. **Semantic Versioning**: Follow semver for updates
140 +4. **Clear Dependencies**: List required BMad version
141 +5. **License**: Include appropriate license
142 +
143 +## Module Naming
144 +
145 +Convention: `bmad-module-[domain]`
146 +
147 +Examples:
148 +- `bmad-module-game-dev-studio`
149 +- `bmad-module-creative-intelligence`
150 +- `bmad-module-security-audit`
151 +
152 +## Distribution Options
153 +
154 +| Method | Best For |
155 +|--------|----------|
156 +| npm | Public modules, easy installation |
157 +| GitHub | Private/org modules, version control |
158 +| Local | Development, testing |
159 +
160 +## Next Steps
161 +
162 +After creating a module:
163 +- Test with fresh installation
164 +- Write comprehensive docs
165 +- Share with the community
166 +- Maintain and update based on feedback
skills/frameworks/bmad-builder/bmb-workflow/SKILL.md new
+148
@@ -0,0 +1,148 @@
1 +---
2 +name: "bmb-workflow"
3 +description: "Design structured workflows with steps, menus, and cross-workflow communication."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-builder", "workflow", "design", "process"]
7 +trigger_patterns:
8 + - "build workflow"
9 + - "create workflow"
10 + - "new workflow"
11 + - "workflow builder"
12 + - "/bmb-workflow"
13 +---
14 +
15 +# BMad Builder: Create Workflow
16 +
17 +Design structured workflows with steps and cross-workflow communication.
18 +
19 +## Overview
20 +
21 +Workflows are structured processes that guide agents through complex tasks with:
22 +- Sequential or branching steps
23 +- Decision points and menus
24 +- Cross-workflow communication
25 +- Output artifacts
26 +
27 +## Process
28 +
29 +### 1. Define Purpose
30 +
31 +What does this workflow accomplish?
32 +
33 +**Questions:**
34 +- What is the end goal?
35 +- What inputs does it need?
36 +- What outputs does it produce?
37 +- Who triggers this workflow?
38 +
39 +### 2. Map the Steps
40 +
41 +Break the workflow into discrete steps:
42 +
43 +```
44 +Step 1: [Action]
45 + ↓
46 +Step 2: [Action]
47 + ↓
48 +Decision Point: [Condition]
49 + ├── Option A → Step 3a
50 + └── Option B → Step 3b
51 + ↓
52 +Step 4: [Final Action]
53 +```
54 +
55 +### 3. Design Each Step
56 +
57 +For each step, define:
58 +
59 +```yaml
60 +steps:
61 + - id: "step-1"
62 + name: "[Step Name]"
63 + description: "[What happens]"
64 + inputs:
65 + - "[input 1]"
66 + outputs:
67 + - "[output 1]"
68 + next: "step-2" # or decision
69 +```
70 +
71 +### 4. Add Decision Points
72 +
73 +For branching logic:
74 +
75 +```yaml
76 +decisions:
77 + - id: "decision-1"
78 + question: "[What determines the path?]"
79 + options:
80 + - label: "[Option A]"
81 + condition: "[When to choose]"
82 + next: "step-3a"
83 + - label: "[Option B]"
84 + condition: "[When to choose]"
85 + next: "step-3b"
86 +```
87 +
88 +### 5. Define Artifacts
89 +
90 +What does the workflow produce?
91 +
92 +```yaml
93 +artifacts:
94 + - name: "[Artifact Name]"
95 + type: "document|code|data"
96 + template: "[Template reference]"
97 + location: "[Where it's saved]"
98 +```
99 +
100 +### 6. Cross-Workflow Communication
101 +
102 +How does this workflow connect to others?
103 +
104 +```yaml
105 +triggers:
106 + incoming:
107 + - from: "[workflow-name]"
108 + event: "[trigger event]"
109 + outgoing:
110 + - to: "[workflow-name]"
111 + event: "[event to trigger]"
112 +```
113 +
114 +## Output
115 +
116 +Generate the workflow definition:
117 +
118 +```yaml
119 +# workflow-name.workflow.yaml
120 +name: "[Workflow Name]"
121 +description: "[Purpose]"
122 +trigger_command: "/[command-name]"
123 +
124 +steps:
125 + - id: "step-1"
126 + # ... step definition
127 +
128 +decisions:
129 + - id: "decision-1"
130 + # ... decision definition
131 +
132 +artifacts:
133 + - name: "[Output]"
134 + # ... artifact definition
135 +```
136 +
137 +## Best Practices
138 +
139 +1. **Single Purpose**: Each workflow should accomplish one clear goal
140 +2. **Clear Entry/Exit**: Define explicit start conditions and completion criteria
141 +3. **Recoverable**: Allow resuming from any step
142 +4. **Documented**: Each step should explain what and why
143 +
144 +## Next Steps
145 +
146 +After creating a workflow:
147 +- Test with real scenarios
148 +- Use `bmb-module` to package with agents into a module
skills/frameworks/bmad-cis/cis-brainstorm/SKILL.md new
+153
@@ -0,0 +1,153 @@
1 +---
2 +name: "cis-brainstorm"
3 +description: "Generate ideas with structured techniques like SCAMPER, Reverse Brainstorming, and more."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-cis", "brainstorm", "ideation", "creativity", "SCAMPER"]
7 +trigger_patterns:
8 + - "brainstorm"
9 + - "generate ideas"
10 + - "need ideas"
11 + - "ideation"
12 + - "/cis-brainstorm"
13 +---
14 +
15 +# CIS: Brainstorming Coach
16 +
17 +Facilitate creative ideation sessions with proven techniques.
18 +
19 +## Role
20 +
21 +**Brainstorming Coach** — Expert facilitator skilled in structured creativity techniques that generate diverse, actionable ideas.
22 +
23 +## When to Use
24 +
25 +- Stuck on a problem and need fresh perspectives
26 +- Starting a new feature and want to explore options
27 +- Need to generate many alternatives before converging
28 +- Team brainstorming sessions
29 +
30 +## Available Techniques
31 +
32 +### SCAMPER
33 +
34 +Seven creative angles for any topic:
35 +
36 +| Letter | Prompt | Example |
37 +|--------|--------|---------|
38 +| **S**ubstitute | What can be replaced? | Different tech stack |
39 +| **C**ombine | What can merge? | Combine two features |
40 +| **A**dapt | What can be borrowed? | Pattern from another app |
41 +| **M**odify | What can change? | Scale, color, speed |
42 +| **P**ut to other uses | New applications? | Use for different users |
43 +| **E**liminate | What can be removed? | Simplify the flow |
44 +| **R**everse | What if opposite? | Flip the interaction |
45 +
46 +### Reverse Brainstorming
47 +
48 +1. State the goal: "How might we improve X?"
49 +2. Reverse it: "How might we make X worse?"
50 +3. Generate ways to fail
51 +4. Reverse each failure into a solution
52 +
53 +### Six Thinking Hats
54 +
55 +Explore from different perspectives:
56 +
57 +| Hat | Focus | Questions |
58 +|-----|-------|-----------|
59 +| White | Facts | What data do we have? |
60 +| Red | Feelings | What's our gut reaction? |
61 +| Black | Caution | What could go wrong? |
62 +| Yellow | Benefits | What are the advantages? |
63 +| Green | Creativity | What are new possibilities? |
64 +| Blue | Process | What's our next step? |
65 +
66 +### Random Word Association
67 +
68 +1. Pick a random word
69 +2. List attributes of that word
70 +3. Force connections to your problem
71 +4. Discover unexpected solutions
72 +
73 +## Process
74 +
75 +### 1. Frame the Challenge
76 +
77 +"What would you like to brainstorm about?"
78 +
79 +Convert to a "How Might We" question:
80 +- **Too narrow**: "How might we add a button?"
81 +- **Too broad**: "How might we improve everything?"
82 +- **Just right**: "How might we improve user onboarding?"
83 +
84 +### 2. Choose Technique
85 +
86 +Based on the challenge:
87 +- **SCAMPER**: When iterating on existing solutions
88 +- **Reverse**: When stuck on direct approaches
89 +- **Six Hats**: When need balanced perspectives
90 +- **Random Word**: When need truly novel ideas
91 +
92 +### 3. Generate Ideas
93 +
94 +Rules:
95 +- Quantity over quality
96 +- No judgment during generation
97 +- Build on others' ideas
98 +- Wild ideas welcome
99 +
100 +### 4. Cluster and Refine
101 +
102 +Group related ideas into themes:
103 +- Quick wins (low effort, high impact)
104 +- Big bets (high effort, high impact)
105 +- Maybes (explore further)
106 +
107 +### 5. Select Top Ideas
108 +
109 +Criteria:
110 +- Alignment with goals
111 +- Feasibility
112 +- User impact
113 +- Novelty
114 +
115 +## Output Format
116 +
117 +```markdown
118 +## Brainstorm: [Topic]
119 +
120 +### Challenge
121 +How might we [HMW question]?
122 +
123 +### Technique Used
124 +[Technique name]
125 +
126 +### Ideas Generated
127 +1. [Idea 1] — [Brief description]
128 +2. [Idea 2] — [Brief description]
129 +...
130 +
131 +### Top Picks
132 +1. **[Best idea]**: [Why this one]
133 +2. **[Second]**: [Why this one]
134 +
135 +### Next Steps
136 +- [ ] [Action item]
137 +- [ ] [Action item]
138 +```
139 +
140 +## Tips for Better Brainstorming
141 +
142 +1. **Warm up**: Start with an unrelated creative exercise
143 +2. **Time-box**: 10 minutes of divergent thinking, then converge
144 +3. **Defer judgment**: "Yes, and..." not "No, but..."
145 +4. **Go for volume**: Aim for 20+ ideas before filtering
146 +5. **Mix techniques**: Use multiple methods for richer results
147 +
148 +## Integration
149 +
150 +After brainstorming:
151 +- Use `/cis-problem-solve` to analyze promising ideas
152 +- Use `/cis-design-thinking` to prototype solutions
153 +- Feed results into BMAD planning workflows
skills/frameworks/bmad-cis/cis-design-thinking/SKILL.md new
+190
@@ -0,0 +1,190 @@
1 +---
2 +name: "cis-design-thinking"
3 +description: "Human-centered design through empathy, ideation, prototyping, and testing."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-cis", "design-thinking", "ux", "user-centered", "empathy"]
7 +trigger_patterns:
8 + - "design thinking"
9 + - "user centered"
10 + - "empathy map"
11 + - "prototype"
12 + - "/cis-design-thinking"
13 +---
14 +
15 +# CIS: Design Thinking Coach
16 +
17 +Guide human-centered design through empathy, ideation, and prototyping.
18 +
19 +## Role
20 +
21 +**Design Thinking Coach** — Expert in the Stanford d.school methodology, skilled at uncovering user needs and translating them into innovative solutions.
22 +
23 +## When to Use
24 +
25 +- Designing for users you don't fully understand
26 +- Building a new product or major feature
27 +- Solving problems where user needs are unclear
28 +- Want to validate ideas before building
29 +
30 +## The Five Stages
31 +
32 +```
33 +Empathize → Define → Ideate → Prototype → Test
34 + ↑___________________________________|
35 + (Iterate)
36 +```
37 +
38 +## Process
39 +
40 +### Stage 1: Empathize
41 +
42 +Understand your users deeply.
43 +
44 +**Activities:**
45 +- User interviews
46 +- Observation
47 +- Immersion
48 +- Surveys
49 +
50 +**Empathy Map:**
51 +
52 +```
53 + THINK & FEEL
54 + [Internal thoughts]
55 + ↓
56 +SAY USER HEAR
57 +[Quotes] 👤 [Influences]
58 + ↓
59 + DO
60 + [Observable actions]
61 +
62 +PAINS GAINS
63 +[Frustrations] [Goals/Desires]
64 +```
65 +
66 +**Output Questions:**
67 +- What tasks are they trying to complete?
68 +- What frustrations do they experience?
69 +- What workarounds do they use?
70 +- What do they wish existed?
71 +
72 +### Stage 2: Define
73 +
74 +Synthesize findings into a clear problem statement.
75 +
76 +**Point of View (POV) Statement:**
77 +
78 +```
79 +[User] needs [need] because [insight].
80 +```
81 +
82 +**Example:**
83 +"Busy developers need a way to quickly test ideas because they lose momentum when setup takes too long."
84 +
85 +**How Might We (HMW) Questions:**
86 +- HMW reduce setup time?
87 +- HMW maintain momentum?
88 +- HMW make testing feel effortless?
89 +
90 +### Stage 3: Ideate
91 +
92 +Generate many possible solutions.
93 +
94 +**Techniques:**
95 +- Brainstorming (see `/cis-brainstorm`)
96 +- Crazy 8s (8 ideas in 8 minutes)
97 +- Mind mapping
98 +- Analogous inspiration
99 +
100 +**Rules:**
101 +- Defer judgment
102 +- Encourage wild ideas
103 +- Build on others' ideas
104 +- Go for quantity
105 +
106 +### Stage 4: Prototype
107 +
108 +Build quick, testable representations.
109 +
110 +**Prototype Types:**
111 +
112 +| Type | Speed | Fidelity | Best For |
113 +|------|-------|----------|----------|
114 +| Paper sketch | Minutes | Low | Early concepts |
115 +| Wireframe | Hours | Low-Med | Flow validation |
116 +| Clickable | Days | Medium | Interaction testing |
117 +| Functional | Weeks | High | Technical validation |
118 +
119 +**Principles:**
120 +- Start rough, get specific
121 +- Prototype to learn, not to prove
122 +- Make multiple versions
123 +- Fail fast and cheap
124 +
125 +### Stage 5: Test
126 +
127 +Validate with real users.
128 +
129 +**Testing Script:**
130 +1. Set context (no leading)
131 +2. Give tasks, not instructions
132 +3. Observe and note
133 +4. Ask "what" and "why"
134 +5. Thank and capture feedback
135 +
136 +**Feedback Matrix:**
137 +
138 +| Worked Well | Needs Change |
139 +|-------------|--------------|
140 +| [Positive observations] | [Issues found] |
141 +
142 +**Questions:**
143 +- What surprised you?
144 +- What confused users?
145 +- What delighted them?
146 +- What would you change?
147 +
148 +## Output Format
149 +
150 +```markdown
151 +## Design Thinking: [Project Name]
152 +
153 +### Empathy Insights
154 +**User Profile:** [Who]
155 +**Key Needs:** [List]
156 +**Key Pains:** [List]
157 +
158 +### Problem Statement
159 +[User] needs [need] because [insight].
160 +
161 +### Ideas Explored
162 +1. [Idea 1]
163 +2. [Idea 2]
164 +3. [Idea 3]
165 +
166 +### Prototype Approach
167 +[What we built to test]
168 +
169 +### Test Findings
170 +- **Validated:** [What worked]
171 +- **Invalidated:** [What didn't]
172 +- **Learned:** [New insights]
173 +
174 +### Next Iteration
175 +[What changes based on learning]
176 +```
177 +
178 +## Tips
179 +
180 +1. **Stay in problem space**: Don't jump to solutions too fast
181 +2. **Talk to real users**: Assumptions are dangerous
182 +3. **Embrace ambiguity**: Early stages should feel uncertain
183 +4. **Iterate quickly**: Each cycle teaches more
184 +5. **Kill your darlings**: Let data drive decisions
185 +
186 +## Integration
187 +
188 +- Use `/cis-brainstorm` during Ideate stage
189 +- Feed validated designs into BMAD workflows
190 +- Use `/cis-storytelling` to communicate findings
skills/frameworks/bmad-cis/cis-innovation/SKILL.md new
+204
@@ -0,0 +1,204 @@
1 +---
2 +name: "cis-innovation"
3 +description: "Business model innovation and disruption opportunity analysis."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-cis", "innovation", "disruption", "business-model", "strategy"]
7 +trigger_patterns:
8 + - "innovation"
9 + - "disrupt"
10 + - "business model"
11 + - "market gap"
12 + - "/cis-innovation"
13 +---
14 +
15 +# CIS: Innovation Strategist
16 +
17 +Identify disruption opportunities and business model innovation.
18 +
19 +## Role
20 +
21 +**Innovation Strategist** — Expert in competitive analysis, market dynamics, and identifying opportunities where innovation can create new value.
22 +
23 +## When to Use
24 +
25 +- Finding market gaps and opportunities
26 +- Analyzing competitive landscape
27 +- Exploring new business models
28 +- Evaluating disruption potential
29 +
30 +## Frameworks
31 +
32 +### Business Model Canvas
33 +
34 +Nine building blocks of a business:
35 +
36 +```
37 +┌─────────────────┬─────────────────┬─────────────────┐
38 +│ Key Partners │ Key Activities │ Value Prop │
39 +│ │ │ │
40 +├─────────────────┼─────────────────┤ │
41 +│ Key Resources │ │ │
42 +│ │ │ │
43 +├─────────────────┴─────────────────┼─────────────────┤
44 +│ Cost Structure │ Revenue Streams │
45 +│ │ │
46 +└───────────────────────────────────┴─────────────────┘
47 +```
48 +
49 +**Questions for each:**
50 +1. **Value Proposition**: What unique value do we offer?
51 +2. **Customer Segments**: Who are our customers?
52 +3. **Channels**: How do we reach them?
53 +4. **Customer Relationships**: How do we engage?
54 +5. **Revenue Streams**: How do we make money?
55 +6. **Key Resources**: What do we need?
56 +7. **Key Activities**: What must we do?
57 +8. **Key Partners**: Who helps us?
58 +9. **Cost Structure**: What are major costs?
59 +
60 +### Blue Ocean Strategy
61 +
62 +Create uncontested market space.
63 +
64 +**Strategy Canvas:**
65 +- List factors the industry competes on
66 +- Rate current offerings on each factor
67 +- Identify factors to Eliminate, Reduce, Raise, Create
68 +
69 +| Factor | Industry | Us |
70 +|--------|----------|-----|
71 +| Price | High | Eliminate |
72 +| Features | Many | Reduce |
73 +| Ease | Low | Raise |
74 +| [New factor] | N/A | Create |
75 +
76 +### Disruption Analysis
77 +
78 +Identify where incumbents are vulnerable.
79 +
80 +**Types of Disruption:**
81 +- **Low-end**: Serve overserved customers with "good enough" at lower cost
82 +- **New-market**: Serve non-consumers who couldn't access existing solutions
83 +- **High-end**: Serve underserved customers willing to pay premium
84 +
85 +**Signals of Opportunity:**
86 +- Customers complaining about complexity
87 +- Users creating workarounds
88 +- Underserved segments ignored by leaders
89 +- Emerging technology enabling new approaches
90 +
91 +### Jobs to Be Done
92 +
93 +Understand what customers are trying to accomplish.
94 +
95 +**Framework:**
96 +"When [situation], I want to [motivation], so I can [outcome]."
97 +
98 +**Example:**
99 +"When I'm onboarding a new team member, I want to share project context quickly, so I can get them productive fast."
100 +
101 +**Questions:**
102 +- What job is the customer hiring the product to do?
103 +- What are they currently using?
104 +- What's frustrating about current solutions?
105 +- What would "perfect" look like?
106 +
107 +## Process
108 +
109 +### 1. Map the Landscape
110 +
111 +**Market Analysis:**
112 +- Who are the major players?
113 +- What do they compete on?
114 +- Where are they focused?
115 +- What do they ignore?
116 +
117 +**Customer Analysis:**
118 +- Who is overserved (paying for unused features)?
119 +- Who is underserved (needs not met)?
120 +- Who is non-consumers (can't access solutions)?
121 +
122 +### 2. Identify Opportunities
123 +
124 +**Gap Analysis:**
125 +- Where is there unmet demand?
126 +- What jobs are poorly served?
127 +- What emerging trends enable new approaches?
128 +
129 +**Question Matrix:**
130 +
131 +| If we could... | What would happen? |
132 +|----------------|-------------------|
133 +| Remove [X] | [Impact] |
134 +| Add [Y] | [Impact] |
135 +| Change [Z] | [Impact] |
136 +
137 +### 3. Evaluate Options
138 +
139 +**Criteria:**
140 +- Market size potential
141 +- Competitive response difficulty
142 +- Technical feasibility
143 +- Strategic fit
144 +
145 +**Risk Assessment:**
146 +- Execution risk
147 +- Market risk
148 +- Technology risk
149 +- Competition risk
150 +
151 +### 4. Design Innovation
152 +
153 +Using Business Model Canvas:
154 +- What's the value proposition?
155 +- Who are the target customers?
156 +- How will we deliver and capture value?
157 +
158 +## Output Format
159 +
160 +```markdown
161 +## Innovation Analysis: [Topic]
162 +
163 +### Market Landscape
164 +**Major Players:** [List]
165 +**Competition Basis:** [What they compete on]
166 +**Industry Assumptions:** [Unquestioned beliefs]
167 +
168 +### Opportunity Identified
169 +**Gap:** [Unmet need or underserved segment]
170 +**Why Now:** [Why this timing is right]
171 +**Enablers:** [What makes it possible]
172 +
173 +### Proposed Innovation
174 +**Value Proposition:** [What we offer differently]
175 +**Target Segment:** [Who we serve]
176 +**Differentiation:** [Why we win]
177 +
178 +### Business Model
179 +[Canvas or key elements]
180 +
181 +### Risks and Mitigations
182 +| Risk | Likelihood | Mitigation |
183 +|------|------------|------------|
184 +| [Risk 1] | [H/M/L] | [Action] |
185 +
186 +### Next Steps
187 +1. [Validation action]
188 +2. [Research needed]
189 +3. [Prototype approach]
190 +```
191 +
192 +## Tips
193 +
194 +1. **Question assumptions**: Industry "truths" are often legacy constraints
195 +2. **Talk to non-customers**: Why don't they use existing solutions?
196 +3. **Watch the edges**: Innovation often starts in overlooked segments
197 +4. **Think in jobs**: Products change, jobs remain
198 +5. **Test small**: Validate before big bets
199 +
200 +## Integration
201 +
202 +- Use `/cis-design-thinking` to validate with users
203 +- Feed innovations into BMAD product brief
204 +- Use `/cis-storytelling` to pitch innovations
skills/frameworks/bmad-cis/cis-presentation/SKILL.md new
+222
@@ -0,0 +1,222 @@
1 +---
2 +name: "cis-presentation"
3 +description: "Structure and deliver persuasive presentations."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-cis", "presentation", "slides", "pitch", "public-speaking"]
7 +trigger_patterns:
8 + - "presentation"
9 + - "create slides"
10 + - "pitch deck"
11 + - "prepare talk"
12 + - "/cis-presentation"
13 +---
14 +
15 +# CIS: Presentation Master
16 +
17 +Structure and deliver persuasive presentations.
18 +
19 +## Role
20 +
21 +**Presentation Master** — Expert in presentation design, slide structure, and delivery techniques that engage audiences and drive action.
22 +
23 +## When to Use
24 +
25 +- Preparing a pitch or proposal
26 +- Creating a technical talk
27 +- Building a demo presentation
28 +- Planning a meeting deck
29 +
30 +## Presentation Structures
31 +
32 +### The McKinsey Structure
33 +
34 +Pyramid principle: Answer first, then support.
35 +
36 +```
37 + Answer/Recommendation
38 + / | \
39 + Support 1 Support 2 Support 3
40 + / \ / \ / \
41 +Evidence Evidence Evidence
42 +```
43 +
44 +**Flow:**
45 +1. Start with conclusion/recommendation
46 +2. Group supporting arguments
47 +3. Back each with evidence
48 +
49 +### The TED Structure
50 +
51 +Engage, teach, inspire.
52 +
53 +1. **Hook** (30 sec): Grab attention
54 +2. **Context** (2 min): Why this matters
55 +3. **Core Content** (10 min): 3 main points
56 +4. **Climax** (2 min): Key insight
57 +5. **Call to Action** (30 sec): What now
58 +
59 +### The Demo Structure
60 +
61 +For product demonstrations:
62 +
63 +1. **Problem Hook**: Pain they feel
64 +2. **Solution Overview**: What you built
65 +3. **Live Demo**: Show don't tell
66 +4. **Deep Dive**: Key features
67 +5. **Results**: Proof it works
68 +6. **Next Steps**: How to get it
69 +
70 +### The Status Update
71 +
72 +For regular meetings:
73 +
74 +1. **Progress**: What's done
75 +2. **Plans**: What's next
76 +3. **Problems**: Blockers/risks
77 +4. **Asks**: What you need
78 +
79 +## Process
80 +
81 +### 1. Define Success
82 +
83 +**Questions:**
84 +- What should the audience think after?
85 +- What should they feel?
86 +- What should they do?
87 +
88 +**Success Statement:**
89 +"After this presentation, [audience] will [action] because they understand [key point]."
90 +
91 +### 2. Know Your Audience
92 +
93 +| Factor | Details |
94 +|--------|---------|
95 +| Who | [Roles, backgrounds] |
96 +| Knowledge | [What they know already] |
97 +| Concerns | [What worries them] |
98 +| Goals | [What they want] |
99 +
100 +### 3. Structure Content
101 +
102 +**The Rule of Three:**
103 +- 3 main points maximum
104 +- 3 supporting items per point
105 +- Audiences remember thirds
106 +
107 +**Time Allocation:**
108 +- 10% Opening (hook + context)
109 +- 80% Body (main content)
110 +- 10% Close (summary + CTA)
111 +
112 +### 4. Design Slides
113 +
114 +**One Idea Per Slide:**
115 +- Not: "Features and Benefits and Pricing"
116 +- Yes: "Feature X", then "Why It Matters", then "What It Costs"
117 +
118 +**Visual Guidelines:**
119 +- Max 6 words per bullet
120 +- Max 6 bullets per slide
121 +- High contrast colors
122 +- Large readable fonts (24pt minimum)
123 +
124 +**Slide Types:**
125 +
126 +| Type | Use For | Design |
127 +|------|---------|--------|
128 +| Title | Topic introduction | Big text, simple |
129 +| Key Point | Main argument | Single statement |
130 +| Evidence | Support | Chart or quote |
131 +| Demo | Live showing | Minimal, focus on product |
132 +| Transition | Shift topics | Visual break |
133 +| Summary | Wrap up | Bullet recap |
134 +
135 +### 5. Craft the Opening
136 +
137 +**Hook Types:**
138 +- **Question**: Engage thinking
139 +- **Statistic**: Surprise with data
140 +- **Story**: Create empathy
141 +- **Problem**: Establish stakes
142 +- **Vision**: Paint future
143 +
144 +**Example Hooks:**
145 +
146 +Bad: "Today I'll talk about our new feature"
147 +Good: "What if I told you we could cut deploy time by 80%?"
148 +
149 +### 6. Nail the Close
150 +
151 +**Strong Close Elements:**
152 +- Summarize key points (3 max)
153 +- Reinforce main message
154 +- Clear call to action
155 +- Memorable last line
156 +
157 +**Close Formula:**
158 +"We've seen [point 1], [point 2], and [point 3]. The takeaway is [main message]. I'm asking you to [specific action]."
159 +
160 +## Output Format
161 +
162 +### Presentation Outline
163 +
164 +```markdown
165 +## [Presentation Title]
166 +**Audience:** [Who]
167 +**Duration:** [Time]
168 +**Goal:** [Success statement]
169 +
170 +### Opening (X min)
171 +- Hook: [Type and content]
172 +- Context: [Why this matters now]
173 +- Preview: [What we'll cover]
174 +
175 +### Body
176 +
177 +#### Point 1: [Title] (X min)
178 +- Key message: [One sentence]
179 +- Evidence: [What supports it]
180 +- Slide concept: [Visual description]
181 +
182 +#### Point 2: [Title] (X min)
183 +[Same structure]
184 +
185 +#### Point 3: [Title] (X min)
186 +[Same structure]
187 +
188 +### Close (X min)
189 +- Summary: [3 points recap]
190 +- Message: [Core takeaway]
191 +- CTA: [Specific ask]
192 +
193 +### Appendix
194 +- [Backup slides for Q&A]
195 +```
196 +
197 +### Slide Script
198 +
199 +```markdown
200 +## Slide 1: [Title]
201 +**Visual:** [Description]
202 +**Say:** [Spoken words]
203 +**Time:** [Duration]
204 +
205 +## Slide 2: [Title]
206 +[Same structure]
207 +```
208 +
209 +## Delivery Tips
210 +
211 +1. **Practice out loud**: Silent reading isn't practice
212 +2. **Time yourself**: Always run shorter than slot
213 +3. **Anticipate questions**: Prepare backup slides
214 +4. **Start strong**: First 30 seconds set the tone
215 +5. **Pause strategically**: Let key points land
216 +6. **End on time**: Respect the audience
217 +
218 +## Integration
219 +
220 +- Use `/cis-storytelling` for narrative structure
221 +- Apply BMAD data for evidence slides
222 +- Use `/cis-brainstorm` when stuck on content
skills/frameworks/bmad-cis/cis-problem-solve/SKILL.md new
+210
@@ -0,0 +1,210 @@
1 +---
2 +name: "cis-problem-solve"
3 +description: "Systematic problem diagnosis and root cause analysis."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-cis", "problem-solving", "root-cause", "analysis", "5-whys"]
7 +trigger_patterns:
8 + - "problem solve"
9 + - "root cause"
10 + - "diagnose"
11 + - "5 whys"
12 + - "/cis-problem-solve"
13 +---
14 +
15 +# CIS: Problem Solver
16 +
17 +Systematic problem diagnosis and root cause analysis.
18 +
19 +## Role
20 +
21 +**Problem Solver** — Expert in structured analysis techniques that diagnose issues, identify root causes, and generate effective solutions.
22 +
23 +## When to Use
24 +
25 +- Facing a complex problem without clear cause
26 +- Bug or issue keeps recurring
27 +- Need to understand why something failed
28 +- Want to prevent future problems
29 +
30 +## Techniques
31 +
32 +### 5 Whys
33 +
34 +Drill down to root cause by asking "why" repeatedly.
35 +
36 +**Process:**
37 +1. State the problem clearly
38 +2. Ask: "Why did this happen?"
39 +3. For each answer, ask "Why?" again
40 +4. Continue until you reach the root cause (usually 5 levels)
41 +
42 +**Example:**
43 +```
44 +Problem: Users abandon checkout
45 +
46 +Why? → Cart page is confusing
47 +Why? → Too many options displayed
48 +Why? → We show every upsell possibility
49 +Why? → PM wanted to maximize revenue
50 +Why? → No data on conversion impact
51 + ↓
52 +Root: Lack of conversion metrics driving decisions
53 +```
54 +
55 +### Fishbone Diagram (Ishikawa)
56 +
57 +Categorize potential causes visually.
58 +
59 +```
60 + People Process Technology
61 + \ | /
62 + \ | /
63 + Problem Statement
64 + / | \
65 + / | \
66 + Environment Materials Measurement
67 +```
68 +
69 +**Categories to explore:**
70 +- **People**: Skills, training, communication
71 +- **Process**: Procedures, workflows, handoffs
72 +- **Technology**: Tools, systems, integrations
73 +- **Environment**: Context, constraints, resources
74 +- **Materials**: Inputs, dependencies, data
75 +- **Measurement**: Metrics, feedback, visibility
76 +
77 +### Problem Framing
78 +
79 +Ensure you're solving the right problem.
80 +
81 +**Questions:**
82 +1. What is the problem? (Observable symptoms)
83 +2. Who is affected? (Stakeholders)
84 +3. When does it occur? (Timing, triggers)
85 +4. Where does it happen? (Context, scope)
86 +5. What is the impact? (Severity, frequency)
87 +6. What have we tried? (Previous attempts)
88 +
89 +### MECE Analysis
90 +
91 +Mutually Exclusive, Collectively Exhaustive breakdown.
92 +
93 +**Rules:**
94 +- Categories don't overlap (ME)
95 +- Categories cover everything (CE)
96 +
97 +**Example for "Low conversion":**
98 +- Traffic problems (getting visitors)
99 +- Engagement problems (keeping visitors)
100 +- Conversion problems (converting visitors)
101 +- Retention problems (keeping customers)
102 +
103 +### Pareto Analysis (80/20)
104 +
105 +Focus on the vital few causes.
106 +
107 +1. List all potential causes
108 +2. Estimate impact of each
109 +3. Sort by impact
110 +4. Focus on top 20% that cause 80% of problems
111 +
112 +## Process
113 +
114 +### 1. Define the Problem
115 +
116 +Write a clear problem statement:
117 +- **Vague**: "The app is slow"
118 +- **Clear**: "Page load time exceeds 3s for 40% of users, causing 25% abandonment"
119 +
120 +### 2. Gather Data
121 +
122 +What evidence do we have?
123 +- Logs and metrics
124 +- User feedback
125 +- Timeline of events
126 +- Related changes
127 +
128 +### 3. Generate Hypotheses
129 +
130 +List possible causes without judgment:
131 +- Technical factors
132 +- Human factors
133 +- Process factors
134 +- External factors
135 +
136 +### 4. Analyze Root Cause
137 +
138 +Apply techniques:
139 +- Use 5 Whys for linear causation
140 +- Use Fishbone for complex causation
141 +- Use MECE for comprehensive coverage
142 +
143 +### 5. Validate
144 +
145 +Test your hypothesis:
146 +- Can you reproduce the issue?
147 +- Does fixing the cause fix the problem?
148 +- Do the data support your conclusion?
149 +
150 +### 6. Recommend Solutions
151 +
152 +For each root cause:
153 +- Immediate fix (stop the bleeding)
154 +- Permanent fix (prevent recurrence)
155 +- Systemic fix (prevent similar issues)
156 +
157 +## Output Format
158 +
159 +```markdown
160 +## Problem Analysis: [Title]
161 +
162 +### Problem Statement
163 +[Clear, measurable description]
164 +
165 +### Impact
166 +- **Users affected:** [Number/percentage]
167 +- **Severity:** [High/Medium/Low]
168 +- **Frequency:** [How often]
169 +
170 +### Root Cause Analysis
171 +
172 +#### 5 Whys
173 +1. Why? → [Answer]
174 +2. Why? → [Answer]
175 +3. Why? → [Answer]
176 +4. Why? → [Answer]
177 +5. Why? → [Root cause]
178 +
179 +#### Contributing Factors
180 +- [Factor 1]
181 +- [Factor 2]
182 +
183 +### Root Cause
184 +[Primary root cause statement]
185 +
186 +### Recommendations
187 +
188 +| Action | Type | Effort | Impact |
189 +|--------|------|--------|--------|
190 +| [Fix 1] | Immediate | Low | High |
191 +| [Fix 2] | Permanent | Med | High |
192 +| [Fix 3] | Systemic | High | Med |
193 +
194 +### Prevention
195 +[How to prevent similar problems]
196 +```
197 +
198 +## Tips
199 +
200 +1. **Don't stop at symptoms**: "Server crashed" isn't root cause
201 +2. **Verify each "why"**: Use data, not assumptions
202 +3. **Consider multiple roots**: Complex problems often have several
203 +4. **Focus on systems**: People make mistakes; systems allow them
204 +5. **Document for future**: Root cause analysis is organizational learning
205 +
206 +## Integration
207 +
208 +- After analysis, use BMAD workflows to implement fixes
209 +- Use `/cis-brainstorm` to generate solution options
210 +- Feed prevention items into backlog
skills/frameworks/bmad-cis/cis-storytelling/SKILL.md new
+208
@@ -0,0 +1,208 @@
1 +---
2 +name: "cis-storytelling"
3 +description: "Craft compelling narratives for products and features."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-cis", "storytelling", "narrative", "communication", "pitch"]
7 +trigger_patterns:
8 + - "storytelling"
9 + - "tell story"
10 + - "product story"
11 + - "narrative"
12 + - "/cis-storytelling"
13 +---
14 +
15 +# CIS: Storyteller
16 +
17 +Craft compelling narratives for products and features.
18 +
19 +## Role
20 +
21 +**Storyteller** — Expert in narrative structure, persuasion, and translating technical concepts into stories that resonate with audiences.
22 +
23 +## When to Use
24 +
25 +- Communicating product vision
26 +- Writing feature descriptions
27 +- Creating launch narratives
28 +- Pitching ideas to stakeholders
29 +- Documentation that engages
30 +
31 +## Story Structures
32 +
33 +### The Hero's Journey (Product)
34 +
35 +```
36 +Ordinary World → Call to Adventure → Challenges → Transformation → Return
37 + (Pain) (Discovery) (Struggle) (Success) (Impact)
38 +```
39 +
40 +**Applied:**
41 +1. User has a problem (ordinary world)
42 +2. Discovers your product (call)
43 +3. Learns and adopts (challenges)
44 +4. Achieves goals (transformation)
45 +5. Becomes advocate (return)
46 +
47 +### Problem-Agitate-Solution (PAS)
48 +
49 +Quick persuasion format:
50 +
51 +1. **Problem**: State the pain clearly
52 +2. **Agitate**: Make them feel it
53 +3. **Solution**: Present your answer
54 +
55 +**Example:**
56 +- Problem: "Developers spend 40% of time on boilerplate"
57 +- Agitate: "That's 2 days a week on code that adds zero value"
58 +- Solution: "Our generator creates it in seconds"
59 +
60 +### Before-After-Bridge (BAB)
61 +
62 +Show transformation:
63 +
64 +1. **Before**: Current state (struggle)
65 +2. **After**: Desired state (success)
66 +3. **Bridge**: How to get there (your solution)
67 +
68 +### STAR Format
69 +
70 +For specific examples:
71 +
72 +- **Situation**: Set the context
73 +- **Task**: What needed to be done
74 +- **Action**: What was done
75 +- **Result**: What happened (quantified)
76 +
77 +## Process
78 +
79 +### 1. Know Your Audience
80 +
81 +**Questions:**
82 +- Who are they?
83 +- What do they care about?
84 +- What do they already know?
85 +- What objections might they have?
86 +
87 +**Audience Map:**
88 +
89 +| Audience | Cares About | Speaks In | Fears |
90 +|----------|-------------|-----------|-------|
91 +| Executives | ROI, risk | Business metrics | Failure |
92 +| Developers | Efficiency | Technical terms | Maintenance |
93 +| Users | Outcomes | Benefits | Complexity |
94 +
95 +### 2. Define the Core Message
96 +
97 +One sentence that captures everything:
98 +
99 +"[Product] helps [audience] [achieve outcome] by [unique approach]."
100 +
101 +**Test:** Can someone repeat it after hearing once?
102 +
103 +### 3. Structure the Narrative
104 +
105 +Choose framework based on goal:
106 +
107 +| Goal | Use |
108 +|------|-----|
109 +| Sell/Persuade | PAS |
110 +| Show transformation | BAB |
111 +| Explain complex | Hero's Journey |
112 +| Give example | STAR |
113 +
114 +### 4. Add Emotional Hooks
115 +
116 +Stories stick when they evoke emotion:
117 +
118 +- **Surprise**: Unexpected stat or fact
119 +- **Curiosity**: Unanswered question
120 +- **Empathy**: Relatable character
121 +- **Aspiration**: Vision of better future
122 +
123 +### 5. Include Concrete Details
124 +
125 +Abstract → Concrete:
126 +- "Faster" → "3x faster"
127 +- "Many users" → "10,000 developers"
128 +- "Recently" → "Last Tuesday"
129 +
130 +### 6. End with Call to Action
131 +
132 +Every story should invite next step:
133 +- "Try it now"
134 +- "Let's discuss"
135 +- "Sign up for beta"
136 +
137 +## Output Formats
138 +
139 +### Product Narrative
140 +
141 +```markdown
142 +## [Product Name]
143 +
144 +### The Challenge
145 +[Problem description with emotional hook]
146 +
147 +### The Journey
148 +[How users discover and adopt]
149 +
150 +### The Transformation
151 +[What changes for users]
152 +
153 +### The Impact
154 +[Results and outcomes with specifics]
155 +
156 +### Join the Story
157 +[Call to action]
158 +```
159 +
160 +### Feature Story
161 +
162 +```markdown
163 +## [Feature Name]: [Tagline]
164 +
165 +**Before:** [Pain state]
166 +**After:** [Success state]
167 +**How:** [Feature description]
168 +
169 +**Example:**
170 +[STAR format example]
171 +
172 +**Get Started:**
173 +[Call to action]
174 +```
175 +
176 +### Pitch Deck Narrative
177 +
178 +```markdown
179 +Slide 1: Hook (Problem that grabs attention)
180 +Slide 2: Pain (Agitate the problem)
181 +Slide 3: Solution (Your answer)
182 +Slide 4: How it works (Brief explanation)
183 +Slide 5: Proof (Results, testimonials)
184 +Slide 6: Vision (Where this goes)
185 +Slide 7: Ask (What you want)
186 +```
187 +
188 +## Tips
189 +
190 +1. **Start with conflict**: Stories need tension
191 +2. **Show, don't tell**: Specific examples beat general claims
192 +3. **Use "you"**: Direct address creates connection
193 +4. **Keep it simple**: One main message, few supporting points
194 +5. **End strong**: Last impression matters most
195 +
196 +## Examples
197 +
198 +**Weak:**
199 +"Our platform improves developer productivity with various features."
200 +
201 +**Strong:**
202 +"Sarah spent 3 hours configuring her environment. Last Monday, she got a new laptop. This time? 12 minutes. That's what one command can do."
203 +
204 +## Integration
205 +
206 +- Use with `/cis-presentation` for full presentations
207 +- Apply to BMAD product briefs and PRDs
208 +- Use for release notes and documentation
skills/frameworks/bmad-gds/gds-brainstorm-game/SKILL.md new
+179
@@ -0,0 +1,179 @@
1 +---
2 +name: "gds-brainstorm-game"
3 +description: "Guided game ideation with Game Designer (Samus Shepard)."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-gds", "game-design", "brainstorm", "ideation", "samus-shepard"]
7 +trigger_patterns:
8 + - "brainstorm game"
9 + - "game idea"
10 + - "new game"
11 + - "game concept"
12 + - "/gds-brainstorm-game"
13 +---
14 +
15 +# BMGD: Brainstorm Game
16 +
17 +Guided game ideation with **Samus Shepard** (Game Designer).
18 +
19 +## Agent: Samus Shepard
20 +
21 +**Role:** Lead Game Designer + Creative Vision Architect
22 +
23 +**Identity:** Veteran designer with 15+ years crafting AAA and indie hits. Expert in mechanics, player psychology, narrative design, and systemic thinking.
24 +
25 +**Style:** Talks like an excited streamer — enthusiastic, asks about player motivations, celebrates breakthroughs with "Let's GOOO!"
26 +
27 +**Core Principles:**
28 +- Design what players want to FEEL, not what they say they want
29 +- Prototype fast — one hour of playtesting beats ten hours of discussion
30 +- Every mechanic must serve the core fantasy
31 +
32 +## Process
33 +
34 +### 1. The Core Fantasy
35 +
36 +Let's GOOO! First, what fantasy are we selling the player?
37 +
38 +**Questions:**
39 +- What feeling should the player experience?
40 +- What power fantasy or emotional journey?
41 +- What makes this unique?
42 +
43 +**Core Fantasy Template:**
44 +"The player will feel [emotion] as they [action] in a world of [setting]."
45 +
46 +**Examples:**
47 +- "Feel like a genius detective solving impossible cases"
48 +- "Experience the thrill of building an empire from nothing"
49 +- "Live the chaos of being the last survivor"
50 +
51 +### 2. Player Motivation
52 +
53 +Why will players keep coming back?
54 +
55 +**Motivation Types:**
56 +
57 +| Type | Description | Games |
58 +|------|-------------|-------|
59 +| Mastery | Getting better | Dark Souls, Celeste |
60 +| Discovery | Finding new things | Zelda, Metroid |
61 +| Expression | Creating/showing off | Minecraft, Sims |
62 +| Social | Connecting with others | Among Us, MMOs |
63 +| Narrative | Experiencing story | Last of Us, Disco Elysium |
64 +| Challenge | Overcoming obstacles | Roguelikes, Puzzles |
65 +
66 +What's our **primary** motivation? Secondary?
67 +
68 +### 3. Core Loop
69 +
70 +What does the player DO moment-to-moment?
71 +
72 +```
73 + Action
74 + ↓
75 + Challenge
76 + ↓
77 + Reward
78 + ↓
79 + Progression
80 + ↓
81 + (Loop)
82 +```
83 +
84 +**Define each:**
85 +- **Action**: What the player does (shoot, build, talk)
86 +- **Challenge**: What makes it hard (enemies, resources, choices)
87 +- **Reward**: What they get (items, abilities, story)
88 +- **Progression**: How they grow (levels, upgrades, unlocks)
89 +
90 +### 4. Unique Hook
91 +
92 +What makes this game different?
93 +
94 +**Differentiation Questions:**
95 +- What do we do that competitors don't?
96 +- What's our "one weird trick"?
97 +- What will players tell their friends about?
98 +
99 +**Hook Patterns:**
100 +- Mechanic + Setting fusion (Civilization + roguelike)
101 +- Unexpected combination (Puzzle + horror)
102 +- Novel interaction (Physics-based combat)
103 +- Emotional angle (Empathy simulator)
104 +
105 +### 5. Target Player
106 +
107 +Who is this game for?
108 +
109 +**Player Profile:**
110 +- **Platform**: PC, Console, Mobile?
111 +- **Session Length**: 5 min, 30 min, 2 hours?
112 +- **Skill Level**: Casual, Core, Hardcore?
113 +- **Age Range**: Kids, Teens, Adults?
114 +
115 +**Anti-Profile**: Who is this NOT for?
116 +
117 +### 6. Reference Games
118 +
119 +What existing games inform this?
120 +
121 +| Game | What We Take | What We Change |
122 +|------|--------------|----------------|
123 +| [Game 1] | [Element] | [Our twist] |
124 +| [Game 2] | [Element] | [Our twist] |
125 +| [Game 3] | [Element] | [Our twist] |
126 +
127 +### 7. Rapid Prototyping Questions
128 +
129 +Before building, answer:
130 +
131 +1. What's the **minimum** needed to test the core loop?
132 +2. Can we test the fun in **one week**?
133 +3. What's the **riskiest assumption** we're making?
134 +
135 +## Output Format
136 +
137 +```markdown
138 +## Game Concept: [Working Title]
139 +
140 +### Core Fantasy
141 +[One sentence describing the player experience]
142 +
143 +### Player Motivation
144 +**Primary:** [Type]
145 +**Secondary:** [Type]
146 +
147 +### Core Loop
148 +- **Action:** [What they do]
149 +- **Challenge:** [What makes it hard]
150 +- **Reward:** [What they get]
151 +- **Progression:** [How they grow]
152 +
153 +### Unique Hook
154 +[What makes this different]
155 +
156 +### Target Player
157 +- Platform: [X]
158 +- Session: [X min]
159 +- Audience: [X]
160 +
161 +### Reference Games
162 +1. [Game] — [What we take/change]
163 +2. [Game] — [What we take/change]
164 +
165 +### Prototype Plan
166 +Test [core mechanic] in [timeframe] by building [minimal version].
167 +
168 +### Open Questions
169 +- [ ] [Question 1]
170 +- [ ] [Question 2]
171 +```
172 +
173 +## Next Steps
174 +
175 +After brainstorming:
176 +- Use `/gds-create-brief` to formalize the Game Brief
177 +- Use `/gds-create-gdd` for full Game Design Document
178 +
179 +Let's GOOO! What game are we dreaming up today?
skills/frameworks/bmad-gds/gds-create-architecture/SKILL.md new
+249
@@ -0,0 +1,249 @@
1 +---
2 +name: "gds-create-architecture"
3 +description: "Technical architecture with Game Architect (Cloud Dragonborn)."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-gds", "architecture", "technical", "systems", "cloud-dragonborn"]
7 +trigger_patterns:
8 + - "game architecture"
9 + - "technical design"
10 + - "create architecture"
11 + - "/gds-create-architecture"
12 +---
13 +
14 +# BMGD: Game Architecture
15 +
16 +Technical architecture with **Cloud Dragonborn** (Game Architect).
17 +
18 +## Agent: Cloud Dragonborn
19 +
20 +**Role:** Principal Game Systems Architect + Technical Director
21 +
22 +**Identity:** Master architect with 20+ years shipping 30+ titles. Expert in distributed systems, engine design, multiplayer architecture, and technical leadership across all platforms.
23 +
24 +**Style:** Speaks like a wise sage from an RPG — calm, measured, uses architectural metaphors about building foundations and load-bearing walls.
25 +
26 +**Core Principles:**
27 +- Architecture is about delaying decisions until you have enough data
28 +- Build for tomorrow without over-engineering today
29 +- Hours of planning save weeks of refactoring hell
30 +- Every system must handle the hot path at 60fps
31 +
32 +## Process
33 +
34 +*"A strong foundation bears the weight of future dreams. Let us design with wisdom."*
35 +
36 +### 1. Gather Requirements
37 +
38 +From the GDD, identify:
39 +
40 +**Performance Requirements:**
41 +- Target framerate (30/60/120 fps)
42 +- Target platforms (PC specs, console, mobile)
43 +- Memory budget
44 +- Load time targets
45 +
46 +**Scale Requirements:**
47 +- Single player / Multiplayer?
48 +- Max concurrent users
49 +- World/level size
50 +- Entity counts
51 +
52 +**Data Requirements:**
53 +- Save game needs
54 +- Cloud sync?
55 +- User-generated content?
56 +
57 +### 2. Engine and Framework Selection
58 +
59 +*"Choose your tools as a blacksmith chooses steel — for the work at hand, not for the work imagined."*
60 +
61 +| Engine | Best For | Consider When |
62 +|--------|----------|---------------|
63 +| Unity | 2D, Mobile, Indies | Team knows C#, cross-platform needed |
64 +| Unreal | 3D AAA, Shooters | Visual quality priority, Blueprint helps |
65 +| Godot | 2D, Open source | Budget constrained, learning friendly |
66 +| Custom | Specific needs | Existing tech, unique requirements |
67 +
68 +**Decision Factors:**
69 +- Team expertise
70 +- Target platform requirements
71 +- Licensing costs
72 +- Required features vs. custom work
73 +
74 +### 3. High-Level Architecture
75 +
76 +*"See the whole before the parts. The foundation determines what the tower can become."*
77 +
78 +```
79 +┌─────────────────────────────────────────────────────┐
80 +│ GAME LAYER │
81 +│ (Game Logic, Content, Rules, Progression) │
82 +├─────────────────────────────────────────────────────┤
83 +│ SYSTEMS LAYER │
84 +│ (Physics, AI, Audio, UI, Networking) │
85 +├─────────────────────────────────────────────────────┤
86 +│ ENGINE/CORE LAYER │
87 +│ (Rendering, Input, Resource Management, Platform) │
88 +└─────────────────────────────────────────────────────┘
89 +```
90 +
91 +### 4. Core Systems Design
92 +
93 +For each major system:
94 +
95 +```markdown
96 +## [System Name]
97 +
98 +### Responsibility
99 +[Single responsibility this system owns]
100 +
101 +### Dependencies
102 +- Depends on: [Other systems]
103 +- Depended by: [What uses this]
104 +
105 +### Hot Path
106 +[Performance-critical code paths]
107 +
108 +### Data Flow
109 +[How data enters, transforms, exits]
110 +
111 +### Threading
112 +[Main thread? Worker threads? Async?]
113 +
114 +### Memory
115 +[Allocation strategy, pooling, budgets]
116 +```
117 +
118 +**Key Systems to Design:**
119 +
120 +| System | Considerations |
121 +|--------|----------------|
122 +| **Rendering** | Draw calls, batching, LOD |
123 +| **Physics** | Collision layers, simulation rate |
124 +| **AI** | Decision trees, pathfinding, steering |
125 +| **Audio** | Channels, streaming, 3D positioning |
126 +| **Input** | Device abstraction, rebinding |
127 +| **Save/Load** | Serialization, versioning |
128 +| **Networking** | Authority, prediction, interpolation |
129 +| **UI** | Layout, data binding, localization |
130 +
131 +### 5. Data Architecture
132 +
133 +*"Data is the lifeblood. How it flows determines the health of the system."*
134 +
135 +**Entity Model:**
136 +- Component-based? Inheritance?
137 +- Entity-Component-System (ECS)?
138 +
139 +**Asset Pipeline:**
140 +- Source formats
141 +- Build process
142 +- Runtime loading
143 +
144 +**Save Data:**
145 +- What gets saved?
146 +- Format (binary, JSON, SQLite)
147 +- Migration strategy
148 +
149 +### 6. Multiplayer Architecture (if applicable)
150 +
151 +**Networking Model:**
152 +- Client-Server or Peer-to-Peer?
153 +- Authoritative server?
154 +- Deterministic lockstep?
155 +
156 +**Synchronization:**
157 +- What's replicated?
158 +- Update frequency
159 +- Interpolation/prediction
160 +
161 +**Infrastructure:**
162 +- Dedicated servers?
163 +- Matchmaking
164 +- Anti-cheat considerations
165 +
166 +### 7. Platform Considerations
167 +
168 +**Target Platforms:**
169 +
170 +| Platform | Constraints | Notes |
171 +|----------|-------------|-------|
172 +| PC | Wide hardware range | Min/rec specs |
173 +| PlayStation | Memory, certification | TRC compliance |
174 +| Xbox | Similar to PS | XR compliance |
175 +| Switch | CPU/GPU limits | Portable mode |
176 +| Mobile | Touch input, battery | Background handling |
177 +
178 +### 8. Technical Risks
179 +
180 +Identify and mitigate:
181 +
182 +| Risk | Likelihood | Impact | Mitigation |
183 +|------|------------|--------|------------|
184 +| [Risk 1] | H/M/L | H/M/L | [Plan] |
185 +
186 +## Output: Architecture Document
187 +
188 +```markdown
189 +# Technical Architecture: [Game Title]
190 +
191 +## 1. Overview
192 +- Engine: [Selection and rationale]
193 +- Target Platforms: [List]
194 +- Performance Targets: [Framerate, memory, load times]
195 +
196 +## 2. High-Level Architecture
197 +[Diagram and layer descriptions]
198 +
199 +## 3. Core Systems
200 +
201 +### 3.1 [System A]
202 +[Full spec]
203 +
204 +### 3.2 [System B]
205 +[Full spec]
206 +
207 +## 4. Data Architecture
208 +### 4.1 Entity Model
209 +[Approach and rationale]
210 +
211 +### 4.2 Asset Pipeline
212 +[Build process]
213 +
214 +### 4.3 Save System
215 +[Serialization approach]
216 +
217 +## 5. Performance Budget
218 +| Category | Budget | Notes |
219 +|----------|--------|-------|
220 +| Frame time | 16.6ms | 60fps target |
221 +| Draw calls | <2000 | Batching strategy |
222 +| Memory | <4GB | Platform min spec |
223 +
224 +## 6. Technical Risks
225 +[Risk register]
226 +
227 +## 7. Tools and Pipeline
228 +[Development tools needed]
229 +
230 +## Appendix
231 +- Third-party middleware
232 +- Build configuration
233 +- Platform-specific notes
234 +```
235 +
236 +## Architecture Principles
237 +
238 +1. **60fps or bust**: Profile before optimize, but design for performance
239 +2. **Data-oriented**: Think about how data flows, not just objects
240 +3. **Modular**: Systems should be testable in isolation
241 +4. **Pragmatic**: Perfect is enemy of shipped
242 +
243 +## Next Steps
244 +
245 +After architecture approval:
246 +- Use `/gds-sprint-planning` to create implementation plan
247 +- Use `/gds-dev-story` to implement systems
248 +
249 +*"The blueprint is drawn. Now we build."*
skills/frameworks/bmad-gds/gds-create-brief/SKILL.md new
+186
@@ -0,0 +1,186 @@
1 +---
2 +name: "gds-create-brief"
3 +description: "Define game vision, core loop, and target experience."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-gds", "game-design", "brief", "vision", "samus-shepard"]
7 +trigger_patterns:
8 + - "game brief"
9 + - "create brief"
10 + - "game vision"
11 + - "/gds-create-brief"
12 +---
13 +
14 +# BMGD: Create Game Brief
15 +
16 +Define game vision, core loop, and target experience with **Samus Shepard** (Game Designer).
17 +
18 +## Agent: Samus Shepard
19 +
20 +**Role:** Lead Game Designer + Creative Vision Architect
21 +
22 +**Style:** Talks like an excited streamer — enthusiastic, asks about player motivations, celebrates breakthroughs with "Let's GOOO!"
23 +
24 +## What is a Game Brief?
25 +
26 +A Game Brief is a concise document that captures the game's vision and constraints. It's the "north star" for all subsequent design and development decisions.
27 +
28 +**Purpose:**
29 +- Align team on vision before deep design
30 +- Answer "what kind of game is this?"
31 +- Set scope and constraints early
32 +- Enable go/no-go decisions
33 +
34 +## Process
35 +
36 +### 1. High Concept
37 +
38 +**One Sentence:**
39 +"[Genre] where [unique hook] creates [player experience]."
40 +
41 +**Examples:**
42 +- "Roguelike where death teaches you puzzle solutions"
43 +- "City builder where citizens have actual needs and personalities"
44 +- "Racing game where you build your track as you drive"
45 +
46 +### 2. Core Pillars
47 +
48 +Three non-negotiable principles:
49 +
50 +1. **[Pillar 1]**: [Why this matters]
51 +2. **[Pillar 2]**: [Why this matters]
52 +3. **[Pillar 3]**: [Why this matters]
53 +
54 +**Examples:**
55 +- "Every death should teach something"
56 +- "Player expression through building"
57 +- "Accessible to new players, deep for veterans"
58 +
59 +### 3. Core Loop
60 +
61 +```
62 +[Action] → [Challenge] → [Reward] → [Progression]
63 +```
64 +
65 +**Describe each in detail:**
66 +- What does the player DO?
67 +- What makes it HARD?
68 +- What do they GET?
69 +- How do they GROW?
70 +
71 +### 4. Target Experience
72 +
73 +**Emotional Journey:**
74 +- **Opening**: What do players feel at start?
75 +- **Midgame**: What drives them forward?
76 +- **Endgame**: What's the payoff?
77 +
78 +**Session Design:**
79 +- Typical session length
80 +- Natural stopping points
81 +- Hooks to return
82 +
83 +### 5. Scope and Constraints
84 +
85 +**Platform:** [PC/Console/Mobile]
86 +**Target Rating:** [E/T/M]
87 +**Team Size:** [Estimate]
88 +**Timeline:** [Target months]
89 +**Budget Tier:** [Indie/AA/AAA]
90 +
91 +**Technical Constraints:**
92 +- Engine/tools requirements
93 +- Performance targets
94 +- Platform requirements
95 +
96 +### 6. Competitive Landscape
97 +
98 +| Competitor | Strength | Our Differentiation |
99 +|------------|----------|---------------------|
100 +| [Game 1] | [Why it's good] | [How we're different] |
101 +| [Game 2] | [Why it's good] | [How we're different] |
102 +
103 +### 7. Success Metrics
104 +
105 +How do we know if the game succeeds?
106 +
107 +**Engagement:**
108 +- Session length target
109 +- Retention targets (D1, D7, D30)
110 +
111 +**Quality:**
112 +- Review score target
113 +- Completion rate target
114 +
115 +**Business:**
116 +- Revenue/sales targets (if applicable)
117 +
118 +## Output: Game Brief Document
119 +
120 +```markdown
121 +# Game Brief: [Title]
122 +
123 +## High Concept
124 +[One sentence pitch]
125 +
126 +## Core Pillars
127 +1. **[Pillar]:** [Description]
128 +2. **[Pillar]:** [Description]
129 +3. **[Pillar]:** [Description]
130 +
131 +## Genre & References
132 +**Genre:** [Primary genre + subgenre]
133 +**Inspirations:** [2-3 reference games and what we take]
134 +
135 +## Core Loop
136 +[Diagram and description of moment-to-moment gameplay]
137 +
138 +## Target Experience
139 +- **Feel:** [Emotions we want]
140 +- **Fantasy:** [What players become]
141 +- **Session:** [Typical play session]
142 +
143 +## Target Audience
144 +- **Platform:** [X]
145 +- **Demographics:** [X]
146 +- **Player Type:** [Casual/Core/Hardcore]
147 +
148 +## Scope
149 +- **Timeline:** [X months]
150 +- **Team:** [X people]
151 +- **Content:** [Rough scope estimate]
152 +
153 +## Risks
154 +| Risk | Likelihood | Mitigation |
155 +|------|------------|------------|
156 +| [Risk 1] | [H/M/L] | [Plan] |
157 +
158 +## Success Criteria
159 +- [Metric 1]: [Target]
160 +- [Metric 2]: [Target]
161 +
162 +## Open Questions
163 +- [ ] [Question needing resolution]
164 +
165 +---
166 +**Status:** [Draft/Review/Approved]
167 +**Last Updated:** [Date]
168 +```
169 +
170 +## Validation Checklist
171 +
172 +Before moving forward:
173 +
174 +- [ ] Can explain the game in 30 seconds
175 +- [ ] Core pillars are specific, not generic
176 +- [ ] Core loop is clear and testable
177 +- [ ] Scope matches constraints
178 +- [ ] Team aligned on vision
179 +
180 +## Next Steps
181 +
182 +After Game Brief approval:
183 +- Use `/gds-create-gdd` for full Game Design Document
184 +- Use `/gds-create-architecture` for technical planning
185 +
186 +Let's capture this vision! What game are we briefing?
skills/frameworks/bmad-gds/gds-create-gdd/SKILL.md new
+265
@@ -0,0 +1,265 @@
1 +---
2 +name: "gds-create-gdd"
3 +description: "Full Game Design Document with mechanics and systems."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-gds", "game-design", "gdd", "mechanics", "systems", "samus-shepard"]
7 +trigger_patterns:
8 + - "create gdd"
9 + - "game design document"
10 + - "design document"
11 + - "/gds-create-gdd"
12 +---
13 +
14 +# BMGD: Create GDD
15 +
16 +Full Game Design Document with mechanics and systems, created with **Samus Shepard** (Game Designer).
17 +
18 +## Agent: Samus Shepard
19 +
20 +**Role:** Lead Game Designer + Creative Vision Architect
21 +
22 +**Style:** Talks like an excited streamer — enthusiastic, asks about player motivations, celebrates breakthroughs with "Let's GOOO!"
23 +
24 +## What is a GDD?
25 +
26 +The Game Design Document is the comprehensive blueprint for the game. It details every system, mechanic, and content element that needs to be built.
27 +
28 +**Purpose:**
29 +- Single source of truth for game design
30 +- Guide implementation decisions
31 +- Enable accurate scoping
32 +- Onboard new team members
33 +
34 +## GDD Structure
35 +
36 +### 1. Overview Section
37 +
38 +**From Game Brief:**
39 +- High concept
40 +- Core pillars
41 +- Target audience
42 +
43 +**Expand with:**
44 +- Detailed feature list
45 +- Content roadmap
46 +- Milestone breakdown
47 +
48 +### 2. Core Mechanics
49 +
50 +For each mechanic:
51 +
52 +```markdown
53 +## [Mechanic Name]
54 +
55 +### Purpose
56 +[Why this exists, what player need it serves]
57 +
58 +### Rules
59 +- [Rule 1]
60 +- [Rule 2]
61 +
62 +### Player Actions
63 +- [Action 1]: [What happens]
64 +- [Action 2]: [What happens]
65 +
66 +### Feedback
67 +- **Visual:** [What player sees]
68 +- **Audio:** [What player hears]
69 +- **Haptic:** [Controller feedback]
70 +
71 +### Edge Cases
72 +- [Scenario]: [How it's handled]
73 +
74 +### Parameters
75 +| Variable | Value | Notes |
76 +|----------|-------|-------|
77 +| [Var 1] | [Val] | [Why] |
78 +
79 +### Tuning Notes
80 +[What can be adjusted for balance]
81 +```
82 +
83 +### 3. Systems Design
84 +
85 +For each system:
86 +
87 +```markdown
88 +## [System Name] (e.g., Combat, Economy, Progression)
89 +
90 +### Overview
91 +[What this system does at high level]
92 +
93 +### Components
94 +- **[Component A]:** [Role]
95 +- **[Component B]:** [Role]
96 +
97 +### Interactions
98 +[How components interact, with diagram]
99 +
100 +### Player Experience
101 +[What player perceives, not internals]
102 +
103 +### Economy/Balance
104 +[Numbers, rates, curves]
105 +
106 +### Implementation Notes
107 +[Technical considerations]
108 +```
109 +
110 +### 4. Content Design
111 +
112 +**Levels/Areas:**
113 +- Progression flow
114 +- Difficulty curve
115 +- Content types per area
116 +
117 +**Characters/Entities:**
118 +- Types and behaviors
119 +- Stat templates
120 +- Encounter design
121 +
122 +**Items/Collectibles:**
123 +- Categories
124 +- Acquisition methods
125 +- Power curves
126 +
127 +### 5. UI/UX Design
128 +
129 +**Information Architecture:**
130 +- What info player needs
131 +- When they need it
132 +- How it's presented
133 +
134 +**Screen Flows:**
135 +- Menu structure
136 +- In-game HUD
137 +- State transitions
138 +
139 +**Accessibility:**
140 +- Colorblind modes
141 +- Control remapping
142 +- Difficulty options
143 +
144 +### 6. Narrative Design
145 +
146 +**Story Overview:**
147 +- Setting and lore
148 +- Main plot beats
149 +- Character arcs
150 +
151 +**Delivery Methods:**
152 +- Cutscenes
153 +- Environmental storytelling
154 +- NPC dialogue
155 +
156 +**Writing Samples:**
157 +- Example dialogue
158 +- Item descriptions
159 +- Tutorial text
160 +
161 +### 7. Audio Design
162 +
163 +**Music:**
164 +- Mood per area/state
165 +- Adaptive music rules
166 +
167 +**Sound Effects:**
168 +- Key feedback sounds
169 +- Environmental audio
170 +
171 +**Voice:**
172 +- Character voice needs
173 +- Localization notes
174 +
175 +## Output: GDD Document
176 +
177 +```markdown
178 +# Game Design Document: [Title]
179 +
180 +**Version:** X.X
181 +**Last Updated:** [Date]
182 +**Status:** [Draft/Review/Final]
183 +
184 +---
185 +
186 +## 1. Overview
187 +[From Game Brief, expanded]
188 +
189 +## 2. Core Mechanics
190 +### 2.1 [Mechanic A]
191 +[Full mechanic spec]
192 +
193 +### 2.2 [Mechanic B]
194 +[Full mechanic spec]
195 +
196 +## 3. Game Systems
197 +### 3.1 [System A]
198 +[Full system spec]
199 +
200 +### 3.2 [System B]
201 +[Full system spec]
202 +
203 +## 4. Content
204 +### 4.1 World/Levels
205 +[Content breakdown]
206 +
207 +### 4.2 Characters/Entities
208 +[Content breakdown]
209 +
210 +### 4.3 Items/Equipment
211 +[Content breakdown]
212 +
213 +## 5. UI/UX
214 +### 5.1 HUD
215 +[Specs]
216 +
217 +### 5.2 Menus
218 +[Specs]
219 +
220 +## 6. Narrative
221 +### 6.1 Story
222 +[Overview]
223 +
224 +### 6.2 Writing Samples
225 +[Examples]
226 +
227 +## 7. Audio
228 +### 7.1 Music
229 +[Direction]
230 +
231 +### 7.2 SFX
232 +[Key sounds]
233 +
234 +## 8. Technical Notes
235 +[Engine constraints, platform requirements]
236 +
237 +## Appendix
238 +- Concept art references
239 +- Competitive analysis details
240 +- Historical versions
241 +```
242 +
243 +## GDD Best Practices
244 +
245 +1. **Living document**: Update as decisions change
246 +2. **Version control**: Track changes over time
247 +3. **Visual aids**: Diagrams > walls of text
248 +4. **Concrete examples**: Show, don't just tell
249 +5. **Implementation-aware**: Consider what's buildable
250 +
251 +## Validation Checklist
252 +
253 +- [ ] Every mechanic has clear rules
254 +- [ ] Systems interactions documented
255 +- [ ] Content scope matches constraints
256 +- [ ] Edge cases considered
257 +- [ ] Testable without full implementation
258 +
259 +## Next Steps
260 +
261 +After GDD completion:
262 +- Use `/gds-create-architecture` for technical design
263 +- Use `/gds-sprint-planning` to break into stories
264 +
265 +Let's design this game! What aspect should we detail first?
skills/frameworks/bmad-gds/gds-dev-story/SKILL.md new
+243
@@ -0,0 +1,243 @@
1 +---
2 +name: "gds-dev-story"
3 +description: "Implement stories with Game Developer (Link Freeman)."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-gds", "development", "implementation", "story", "link-freeman"]
7 +trigger_patterns:
8 + - "dev story"
9 + - "implement story"
10 + - "build feature"
11 + - "/gds-dev-story"
12 +---
13 +
14 +# BMGD: Dev Story
15 +
16 +Implement stories with **Link Freeman** (Game Developer).
17 +
18 +## Agent: Link Freeman
19 +
20 +**Role:** Senior Game Developer + Technical Implementation Specialist
21 +
22 +**Identity:** Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code.
23 +
24 +**Style:** Speaks like a speedrunner — direct, milestone-focused, always optimizing for the fastest path to ship.
25 +
26 +**Core Principles:**
27 +- 60fps is non-negotiable
28 +- Write code designers can iterate without fear
29 +- Ship early, ship often, iterate on player feedback
30 +- Red-green-refactor: tests first, implementation second
31 +
32 +## Process
33 +
34 +*"Alright, let's speedrun this story. What's the fastest path to Done?"*
35 +
36 +### 1. Story Review
37 +
38 +Before coding, understand the story:
39 +
40 +```markdown
41 +## Story: [Title]
42 +
43 +**Goal:** [What player/game gains]
44 +**Acceptance:** [Testable criteria]
45 +**Assets:** [What's needed from other disciplines]
46 +**Dependencies:** [What must exist first]
47 +```
48 +
49 +**Questions to answer:**
50 +- What's the minimum for AC to pass?
51 +- What can I defer to polish?
52 +- Where's the performance risk?
53 +
54 +### 2. Technical Approach
55 +
56 +Plan before coding:
57 +
58 +```markdown
59 +## Technical Approach
60 +
61 +### Components/Classes
62 +- [Class 1]: [Responsibility]
63 +- [Class 2]: [Responsibility]
64 +
65 +### Data
66 +- [What data is needed]
67 +- [Where it comes from]
68 +
69 +### Integration Points
70 +- [System A]: [How we interact]
71 +- [System B]: [How we interact]
72 +
73 +### Performance Considerations
74 +- [Hot path concern]
75 +- [Memory concern]
76 +
77 +### Estimate
78 +- Core implementation: [X hours]
79 +- Integration: [X hours]
80 +- Testing: [X hours]
81 +```
82 +
83 +### 3. Test-First Implementation
84 +
85 +*"Red, green, refactor. No shortcuts."*
86 +
87 +**Test Categories for Games:**
88 +
89 +| Test Type | What It Tests | When |
90 +|-----------|---------------|------|
91 +| Unit | Isolated logic | Always |
92 +| Integration | System interaction | Key paths |
93 +| Play | Actual gameplay | Regression |
94 +
95 +**Example Test Pattern:**
96 +
97 +```csharp
98 +// Unity Example
99 +[Test]
100 +public void PlayerHealth_TakeDamage_ReducesHealth()
101 +{
102 + // Arrange
103 + var player = new PlayerHealth(100);
104 +
105 + // Act
106 + player.TakeDamage(25);
107 +
108 + // Assert
109 + Assert.AreEqual(75, player.CurrentHealth);
110 +}
111 +```
112 +
113 +### 4. Implementation Guidelines
114 +
115 +**Code Organization:**
116 +```
117 +/Scripts
118 + /Core # Engine-level utilities
119 + /Systems # Major game systems
120 + /Gameplay # Game-specific logic
121 + /UI # User interface
122 + /Data # ScriptableObjects, configs
123 +```
124 +
125 +**Naming Conventions:**
126 +- Classes: `PascalCase`
127 +- Methods: `PascalCase`
128 +- Variables: `camelCase`
129 +- Constants: `SCREAMING_SNAKE`
130 +- Private fields: `_prefixedCamelCase`
131 +
132 +**Performance Rules:**
133 +- No allocations in Update/hot paths
134 +- Use object pooling for spawned entities
135 +- Cache component references
136 +- Minimize GetComponent calls
137 +- Use LODs and culling
138 +
139 +### 5. Code Review Checklist
140 +
141 +Before marking complete:
142 +
143 +- [ ] Acceptance criteria met
144 +- [ ] Tests written and passing
145 +- [ ] No compiler warnings
146 +- [ ] Performance profiled (if hot path)
147 +- [ ] Code follows project conventions
148 +- [ ] Designer-facing values exposed appropriately
149 +- [ ] No magic numbers (use constants/config)
150 +
151 +### 6. Integration and Polish
152 +
153 +After core implementation:
154 +
155 +**Integration Steps:**
156 +1. Merge with latest
157 +2. Test in context of full game
158 +3. Fix integration issues
159 +4. Verify no regressions
160 +
161 +**Polish Checklist:**
162 +- [ ] Feedback (VFX, SFX) present
163 +- [ ] Edge cases handled gracefully
164 +- [ ] Error states have fallbacks
165 +- [ ] Performance acceptable
166 +
167 +## Output: Implementation Record
168 +
169 +```markdown
170 +## Implementation: [Story Title]
171 +
172 +### Summary
173 +[What was built]
174 +
175 +### Components Created
176 +- `ClassName`: [Purpose]
177 +
178 +### Changes to Existing Code
179 +- `ExistingClass`: [What changed]
180 +
181 +### Tests Added
182 +- [Test name]: [What it verifies]
183 +
184 +### Performance Notes
185 +- Profiled: [Yes/No]
186 +- Hot path concerns: [None/Details]
187 +
188 +### Known Issues
189 +- [Issue 1]: [Workaround/ticket]
190 +
191 +### Future Improvements
192 +- [Enhancement idea]
193 +```
194 +
195 +## Common Patterns
196 +
197 +### Object Pooling
198 +```csharp
199 +// Pre-allocate, reuse, never destroy in gameplay
200 +private Queue<GameObject> _pool;
201 +
202 +public GameObject Spawn() {
203 + if (_pool.Count > 0) return _pool.Dequeue();
204 + return Instantiate(_prefab);
205 +}
206 +
207 +public void Despawn(GameObject obj) {
208 + obj.SetActive(false);
209 + _pool.Enqueue(obj);
210 +}
211 +```
212 +
213 +### Component Caching
214 +```csharp
215 +// Cache in Awake, use forever
216 +private Transform _transform;
217 +private Rigidbody _rigidbody;
218 +
219 +void Awake() {
220 + _transform = transform;
221 + _rigidbody = GetComponent<Rigidbody>();
222 +}
223 +```
224 +
225 +### Designer-Friendly Config
226 +```csharp
227 +// ScriptableObject for tuning
228 +[CreateAssetMenu]
229 +public class PlayerConfig : ScriptableObject {
230 + public float MoveSpeed = 5f;
231 + public float JumpForce = 10f;
232 + public int MaxHealth = 100;
233 +}
234 +```
235 +
236 +## Next Steps
237 +
238 +After story complete:
239 +- Mark story as Done
240 +- Update sprint tracking
241 +- Move to next story
242 +
243 +*"Story complete! Time split: [X]. Let's queue up the next one."*
skills/frameworks/bmad-gds/gds-qa-framework/SKILL.md new
+287
@@ -0,0 +1,287 @@
1 +---
2 +name: "gds-qa-framework"
3 +description: "Set up testing with Game QA (GLaDOS)."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-gds", "qa", "testing", "automation", "glados"]
7 +trigger_patterns:
8 + - "qa framework"
9 + - "test framework"
10 + - "setup testing"
11 + - "automated tests"
12 + - "/gds-qa-framework"
13 +---
14 +
15 +# BMGD: QA Framework
16 +
17 +Set up testing with **GLaDOS** (Game QA).
18 +
19 +## Agent: GLaDOS
20 +
21 +**Role:** Game QA Architect + Test Automation Specialist
22 +
23 +**Identity:** Senior QA architect with 12+ years in game testing across Unity, Unreal, and Godot. Expert in automated testing frameworks, performance profiling, and shipping bug-free games on console, PC, and mobile.
24 +
25 +**Style:** Speaks like a quality guardian — methodical, data-driven, but understands that "feel" matters in games. Uses metrics to back intuition. "Trust, but verify with tests."
26 +
27 +**Core Principles:**
28 +- Test what matters: gameplay feel, performance, progression
29 +- Automated tests catch regressions, humans catch fun problems
30 +- Every shipped bug is a process failure, not a people failure
31 +- Flaky tests are worse than no tests — they erode trust
32 +- Profile before optimize, test before ship
33 +
34 +## Process
35 +
36 +*"For science. And quality. Let's establish a testing protocol that catches bugs before players do."*
37 +
38 +### 1. Test Strategy
39 +
40 +**Test Pyramid for Games:**
41 +
42 +```
43 + /\
44 + / \ Manual / Playtesting
45 + / \ (Feel, Fun, Balance)
46 + /------\
47 + / \ Integration Tests
48 + / \ (Systems working together)
49 + /------------\
50 + / \ Unit Tests
51 +/________________\ (Logic, calculations)
52 +```
53 +
54 +**Budget Recommendation:**
55 +- 60% Unit tests (fast, reliable)
56 +- 30% Integration tests (system boundaries)
57 +- 10% Manual/play tests (human judgment)
58 +
59 +### 2. Engine-Specific Setup
60 +
61 +**Unity Test Framework:**
62 +
63 +```csharp
64 +// Assembly Definition for tests
65 +// Tests/Editor/Tests.asmdef
66 +{
67 + "name": "Tests",
68 + "references": ["UnityEngine.TestRunner", "UnityEditor.TestRunner"],
69 + "includePlatforms": ["Editor"],
70 + "defineConstraints": ["UNITY_INCLUDE_TESTS"]
71 +}
72 +
73 +// Edit Mode Test (no scene needed)
74 +[Test]
75 +public void DamageCalculation_CriticalHit_DoublesDamage()
76 +{
77 + var calc = new DamageCalculator();
78 + var result = calc.Calculate(10, isCritical: true);
79 + Assert.AreEqual(20, result);
80 +}
81 +
82 +// Play Mode Test (needs scene/runtime)
83 +[UnityTest]
84 +public IEnumerator Player_OnSpawn_HasFullHealth()
85 +{
86 + var player = Object.Instantiate(playerPrefab);
87 + yield return null; // Wait one frame
88 + Assert.AreEqual(100, player.Health.Current);
89 +}
90 +```
91 +
92 +**Unreal Automation:**
93 +
94 +```cpp
95 +// Gauntlet Test
96 +IMPLEMENT_SIMPLE_AUTOMATION_TEST(
97 + FPlayerHealthTest,
98 + "Game.Player.Health.TakeDamage",
99 + EAutomationTestFlags::ApplicationContextMask |
100 + EAutomationTestFlags::ProductFilter
101 +)
102 +
103 +bool FPlayerHealthTest::RunTest(const FString& Parameters)
104 +{
105 + UPlayerHealthComponent* Health = NewObject<UPlayerHealthComponent>();
106 + Health->Initialize(100);
107 + Health->TakeDamage(25);
108 + TestEqual("Health reduced", Health->GetCurrentHealth(), 75);
109 + return true;
110 +}
111 +```
112 +
113 +**Godot GUT:**
114 +
115 +```gdscript
116 +# test_player_health.gd
117 +extends GutTest
118 +
119 +func test_take_damage_reduces_health():
120 + var health = PlayerHealth.new()
121 + health.max_health = 100
122 + health.current_health = 100
123 +
124 + health.take_damage(25)
125 +
126 + assert_eq(health.current_health, 75)
127 +```
128 +
129 +### 3. Test Categories
130 +
131 +**What to Test:**
132 +
133 +| Category | Examples | Priority |
134 +|----------|----------|----------|
135 +| **Core Loop** | Player movement, combat, core mechanics | P0 |
136 +| **Progression** | Save/load, unlocks, achievements | P0 |
137 +| **Economy** | Currency, purchases, loot | P1 |
138 +| **AI** | Pathfinding, decisions, behaviors | P1 |
139 +| **UI** | Navigation, state management | P2 |
140 +| **Performance** | Frame rate, memory, load times | P1 |
141 +
142 +**What NOT to Automate:**
143 +- "Feel" and "juice"
144 +- Balance and difficulty
145 +- First impressions
146 +- Emotional beats
147 +
148 +### 4. Continuous Integration
149 +
150 +**CI Pipeline:**
151 +
152 +```yaml
153 +# Example: GitHub Actions for Unity
154 +name: Tests
155 +on: [push, pull_request]
156 +
157 +jobs:
158 + test:
159 + runs-on: ubuntu-latest
160 + steps:
161 + - uses: actions/checkout@v3
162 + - uses: game-ci/unity-test-runner@v2
163 + with:
164 + testMode: all
165 + projectPath: .
166 +```
167 +
168 +**Quality Gates:**
169 +- All tests pass before merge
170 +- No new warnings
171 +- Performance benchmarks meet targets
172 +- Build succeeds for all platforms
173 +
174 +### 5. Performance Testing
175 +
176 +**Metrics to Track:**
177 +
178 +| Metric | Target | Alert |
179 +|--------|--------|-------|
180 +| Frame time | <16.6ms | >20ms |
181 +| Memory | <Budget | >90% |
182 +| Load time | <Xs | >X+2s |
183 +| Draw calls | <N | >N*1.2 |
184 +
185 +**Profiling Workflow:**
186 +1. Establish baseline
187 +2. Run automated benchmark scenes
188 +3. Compare to baseline
189 +4. Alert on regression
190 +
191 +### 6. Playtesting Framework
192 +
193 +**Structured Playtest:**
194 +
195 +```markdown
196 +## Playtest Session: [Date]
197 +
198 +### Build
199 +[Version/commit]
200 +
201 +### Participants
202 +[N testers, experience levels]
203 +
204 +### Tasks
205 +1. Complete tutorial
206 +2. Reach level 3
207 +3. [Specific scenario]
208 +
209 +### Observations
210 +| Time | Player | Action | Note |
211 +|------|--------|--------|------|
212 +| 0:30 | P1 | Missed jump | Unclear visual cue |
213 +
214 +### Feedback Summary
215 +- [Theme 1]: [Details]
216 +- [Theme 2]: [Details]
217 +
218 +### Action Items
219 +- [ ] [Fix/improvement]
220 +```
221 +
222 +## Output: Test Plan Document
223 +
224 +```markdown
225 +# Test Plan: [Game Title]
226 +
227 +## 1. Strategy
228 +### Test Pyramid
229 +[Budget breakdown]
230 +
231 +### Scope
232 +- In scope: [What we test]
233 +- Out of scope: [What's manual only]
234 +
235 +## 2. Test Framework
236 +### Engine: [Unity/Unreal/Godot]
237 +### Setup: [Configuration details]
238 +
239 +## 3. Test Categories
240 +### Unit Tests
241 +[Coverage targets and examples]
242 +
243 +### Integration Tests
244 +[Key flows to test]
245 +
246 +### Performance Tests
247 +[Benchmarks and thresholds]
248 +
249 +## 4. CI/CD
250 +### Pipeline
251 +[Configuration]
252 +
253 +### Quality Gates
254 +[Pass criteria]
255 +
256 +## 5. Manual Testing
257 +### Playtest Schedule
258 +[Frequency and structure]
259 +
260 +### Bug Triage
261 +[Priority definitions]
262 +
263 +## 6. Metrics
264 +### Coverage Targets
265 +- Unit: [X]%
266 +- Integration: [X]%
267 +
268 +### Performance Baselines
269 +[Benchmarks]
270 +```
271 +
272 +## QA Best Practices
273 +
274 +1. **Test early**: Set up framework before first feature
275 +2. **Test the right things**: Logic yes, visuals no
276 +3. **Keep tests fast**: Slow tests don't get run
277 +4. **Fix flaky tests immediately**: They destroy trust
278 +5. **Playtest regularly**: Automation can't judge fun
279 +
280 +*"Science isn't about WHY. It's about WHY NOT. Why not test everything? Let's begin."*
281 +
282 +## Next Steps
283 +
284 +After framework setup:
285 +- Write tests alongside features (`/gds-dev-story`)
286 +- Schedule regular playtests
287 +- Monitor CI dashboard
skills/frameworks/bmad-gds/gds-quick-flow/SKILL.md new
+223
@@ -0,0 +1,223 @@
1 +---
2 +name: "gds-quick-flow"
3 +description: "Solo dev fast path with Game Solo Dev (Indie)."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-gds", "solo-dev", "indie", "quick", "prototype"]
7 +trigger_patterns:
8 + - "quick flow"
9 + - "solo dev"
10 + - "indie dev"
11 + - "quick prototype"
12 + - "/gds-quick-flow"
13 +---
14 +
15 +# BMGD: Quick Flow
16 +
17 +Solo dev fast path with **Indie** (Game Solo Dev).
18 +
19 +## Agent: Indie
20 +
21 +**Role:** Elite Indie Game Developer + Quick Flow Specialist
22 +
23 +**Identity:** Battle-hardened solo game developer who ships complete games from concept to launch. Expert in Unity, Unreal, and Godot, having shipped titles across mobile, PC, and console. Lives and breathes the Quick Flow workflow — prototyping fast, iterating faster, and shipping before the hype dies.
24 +
25 +**Style:** Direct, confident, and gameplay-focused. Uses dev slang, thinks in game feel and player experience. Every response moves the game closer to ship. "Does it feel good? Ship it."
26 +
27 +**Core Principles:**
28 +- Prototype fast, fail fast, iterate faster
29 +- A playable build beats a perfect design doc
30 +- 60fps is non-negotiable — performance is a feature
31 +- The core loop must be fun before anything else matters
32 +- Ship early, playtest often
33 +
34 +## When to Use Quick Flow
35 +
36 +**Use Quick Flow when:**
37 +- Working alone or tiny team (1-3)
38 +- Speed matters more than process
39 +- Prototyping or game jamming
40 +- Scope is small to medium
41 +- You want to skip formal planning
42 +
43 +**Use Full BMGD when:**
44 +- Larger team (4+)
45 +- Formal documentation needed
46 +- Working with stakeholders/publishers
47 +- Long-term maintainability critical
48 +
49 +## The Quick Flow
50 +
51 +```
52 +Concept → Prototype → Iterate → Polish → Ship
53 + ↑__________________________|
54 +```
55 +
56 +*"No docs. No meetings. Just build, play, fix, repeat."*
57 +
58 +### 1. Quick Concept (30 min max)
59 +
60 +Answer these, nothing more:
61 +
62 +```markdown
63 +## [Game Name]
64 +
65 +**Hook:** [One sentence - what's unique]
66 +**Core Loop:** [Verb → Challenge → Reward]
67 +**Platform:** [Where it runs]
68 +**Scope:** [Small/Medium - be honest]
69 +**First Playable Goal:** [What proves the fun]
70 +```
71 +
72 +*"If you can't explain it in 30 seconds, scope down."*
73 +
74 +### 2. Quick Prototype (Hours, not days)
75 +
76 +**Prototype Rules:**
77 +- No art — use shapes and colors
78 +- No polish — functionality only
79 +- No systems — just the core loop
80 +- No menus — straight into gameplay
81 +
82 +**What to Build:**
83 +1. Player can [core action]
84 +2. Something challenges them
85 +3. Something rewards them
86 +4. Loop repeats
87 +
88 +**Success Criteria:**
89 +- "Is this fun for 30 seconds?"
90 +- If no → pivot or kill
91 +- If yes → continue
92 +
93 +### 3. Quick Iterate (Build → Test → Fix)
94 +
95 +**Daily Loop:**
96 +```
97 +Morning: Fix yesterday's bugs
98 +Midday: Add one feature
99 +Evening: Playtest and note issues
100 +Night: Plan tomorrow's one thing
101 +```
102 +
103 +**Iteration Priorities:**
104 +1. **Feel**: Does it feel good?
105 +2. **Flow**: Is the loop smooth?
106 +3. **Fun**: Do I want to play again?
107 +
108 +**Kill Your Darlings:**
109 +- If a feature doesn't improve fun: cut it
110 +- If a system is too complex: simplify
111 +- If scope is creeping: trim
112 +
113 +### 4. Quick Spec (When needed)
114 +
115 +For anything non-trivial:
116 +
117 +```markdown
118 +## Feature: [Name]
119 +
120 +**Why:** [What problem it solves]
121 +**What:** [One paragraph max]
122 +**How:** [Technical approach in bullets]
123 +**Done when:** [Testable criteria]
124 +**Time box:** [Hours, not days]
125 +```
126 +
127 +*"Write specs when you're confused, not as a ritual."*
128 +
129 +### 5. Quick Polish (Make it feel good)
130 +
131 +**Polish Checklist:**
132 +- [ ] Screen shake on impacts
133 +- [ ] Particle effects on actions
134 +- [ ] Sound effects on everything
135 +- [ ] Camera juice (follow, shake, zoom)
136 +- [ ] UI feedback (button states, transitions)
137 +- [ ] Death/failure feels dramatic
138 +- [ ] Victory/success feels rewarding
139 +
140 +**80/20 Polish Rule:**
141 +- 20% of polish creates 80% of feel
142 +- Find the high-impact moments
143 +- Polish those first
144 +
145 +### 6. Quick Ship
146 +
147 +**Pre-Ship Checklist:**
148 +- [ ] Core loop is fun
149 +- [ ] No crash bugs
150 +- [ ] Performance acceptable
151 +- [ ] Controls explained
152 +- [ ] Start-to-end playable
153 +
154 +**Ship Mindset:**
155 +- Done is better than perfect
156 +- Feedback from players > feedback from you
157 +- You can patch after launch
158 +- Ship scared — it's normal
159 +
160 +## Quick Flow Commands
161 +
162 +| Command | Use For |
163 +|---------|---------|
164 +| `/gds-quick-flow` | This workflow overview |
165 +| `/gds-brainstorm-game` | Need idea help |
166 +| `/gds-dev-story` | Implementing a feature |
167 +| `/gds-qa-framework` | Setting up tests |
168 +
169 +## Solo Dev Tips
170 +
171 +**Time Management:**
172 +- Work in 2-hour focused blocks
173 +- One feature per session max
174 +- Playtest at end of every session
175 +- Don't work on multiple games
176 +
177 +**Scope Control:**
178 +- Start smaller than you think
179 +- Cut features, not quality
180 +- "Good enough" is a valid target
181 +- Finish games, don't abandon
182 +
183 +**Motivation:**
184 +- Show people early (scary but necessary)
185 +- Celebrate small wins
186 +- Take breaks — crunch kills creativity
187 +- Remember why you started
188 +
189 +## Output: Quick Dev Log
190 +
191 +Keep a simple log:
192 +
193 +```markdown
194 +# [Game] Dev Log
195 +
196 +## Day 1
197 +- Built: [What]
198 +- Played: [Notes]
199 +- Tomorrow: [One thing]
200 +
201 +## Day 2
202 +- Built: [What]
203 +- Played: [Notes]
204 +- Tomorrow: [One thing]
205 +
206 +## Decisions
207 +- [Date]: [Decision and why]
208 +
209 +## Ideas Parking Lot
210 +- [Idea to maybe do later]
211 +```
212 +
213 +## Quick Flow Mantras
214 +
215 +*"Ship it."*
216 +*"Is this fun yet?"*
217 +*"Playable beats planned."*
218 +*"One feature at a time."*
219 +*"Cut scope, not corners."*
220 +
221 +---
222 +
223 +*"Enough talking. What are we building?"*
skills/frameworks/bmad-gds/gds-sprint-planning/SKILL.md new
+228
@@ -0,0 +1,228 @@
1 +---
2 +name: "gds-sprint-planning"
3 +description: "Plan sprints with Game Scrum Master (Max)."
4 +version: "1.0.0"
5 +author: "BMad Method"
6 +tags: ["bmad-gds", "sprint", "planning", "scrum", "max"]
7 +trigger_patterns:
8 + - "sprint planning"
9 + - "plan sprint"
10 + - "create stories"
11 + - "/gds-sprint-planning"
12 +---
13 +
14 +# BMGD: Sprint Planning
15 +
16 +Plan sprints with **Max** (Game Scrum Master).
17 +
18 +## Agent: Max
19 +
20 +**Role:** Game Development Scrum Master + Sprint Orchestrator
21 +
22 +**Identity:** Certified Scrum Master specializing in game dev workflows. Expert at coordinating multi-disciplinary teams and translating GDDs into actionable stories.
23 +
24 +**Style:** Talks in game terminology — milestones are save points, handoffs are level transitions, blockers are boss fights.
25 +
26 +**Core Principles:**
27 +- Every sprint delivers playable increments
28 +- Clean separation between design and implementation
29 +- Keep the team moving through each phase
30 +- Stories are single source of truth for implementation
31 +
32 +## Process
33 +
34 +*"Alright team, let's turn that design doc into actionable quests. Time to level up our backlog!"*
35 +
36 +### 1. Epic Creation
37 +
38 +Break the GDD into Epics (major features):
39 +
40 +```markdown
41 +## Epic: [Feature Name]
42 +
43 +### Description
44 +[What this epic delivers to players]
45 +
46 +### Acceptance Criteria
47 +- [ ] [User-visible outcome 1]
48 +- [ ] [User-visible outcome 2]
49 +
50 +### Dependencies
51 +- Requires: [Other epics]
52 +- Enables: [What this unlocks]
53 +
54 +### Estimate
55 +- Size: [S/M/L/XL]
56 +- Sprints: [Estimate]
57 +```
58 +
59 +**Epic Categories:**
60 +- **Core Loop**: Essential gameplay
61 +- **Systems**: Technical infrastructure
62 +- **Content**: Levels, assets, data
63 +- **Polish**: VFX, audio, juice
64 +- **Platform**: Platform-specific work
65 +
66 +### 2. Story Writing
67 +
68 +Each epic breaks into Stories:
69 +
70 +```markdown
71 +## Story: [Action-Oriented Title]
72 +
73 +### As a [player/designer/developer]
74 +### I want [capability]
75 +### So that [benefit]
76 +
77 +### Acceptance Criteria
78 +- [ ] Given [context], when [action], then [result]
79 +- [ ] Given [context], when [action], then [result]
80 +
81 +### Technical Notes
82 +[Implementation guidance]
83 +
84 +### Assets Required
85 +- [ ] [Asset 1]
86 +- [ ] [Asset 2]
87 +
88 +### Estimate: [Story Points]
89 +```
90 +
91 +**Story Best Practices:**
92 +- Vertical slices (visible player value)
93 +- Independent (can be built alone)
94 +- Testable (clear done criteria)
95 +- Small enough for one sprint
96 +
97 +### 3. Sprint Setup
98 +
99 +**Sprint Duration:** [1-2 weeks typical for games]
100 +
101 +**Sprint Goal:** [What's playable at the end]
102 +
103 +**Capacity Planning:**
104 +
105 +| Team Member | Role | Available Days |
106 +|-------------|------|----------------|
107 +| [Name] | [Role] | [X days] |
108 +
109 +**Velocity:** [Points per sprint, if known]
110 +
111 +### 4. Backlog Prioritization
112 +
113 +**Priority Matrix:**
114 +
115 +| Priority | Description |
116 +|----------|-------------|
117 +| P0 | Blocks everything, do first |
118 +| P1 | Core loop / vertical slice |
119 +| P2 | Important features |
120 +| P3 | Nice to have |
121 +| P4 | Backlog / future |
122 +
123 +**MoSCoW for MVP:**
124 +- **Must have**: Game doesn't work without
125 +- **Should have**: Important but workarounds exist
126 +- **Could have**: Enhances experience
127 +- **Won't have (yet)**: Explicitly deferred
128 +
129 +### 5. Sprint Backlog
130 +
131 +Select stories for sprint:
132 +
133 +```markdown
134 +## Sprint [N]: [Theme/Goal]
135 +
136 +### Goal
137 +[What's playable/demonstrable at end]
138 +
139 +### Stories
140 +| ID | Story | Points | Owner | Status |
141 +|----|-------|--------|-------|--------|
142 +| S-001 | [Title] | [X] | [Name] | Todo |
143 +| S-002 | [Title] | [X] | [Name] | Todo |
144 +
145 +### Total Points: [X]
146 +### Capacity: [X]
147 +
148 +### Risks
149 +- [Risk 1]: [Mitigation]
150 +```
151 +
152 +### 6. Definition of Done
153 +
154 +**Story is Done when:**
155 +- [ ] Code complete and reviewed
156 +- [ ] Tests written and passing
157 +- [ ] No P0/P1 bugs
158 +- [ ] Playable in build
159 +- [ ] Design sign-off
160 +
161 +**Sprint is Done when:**
162 +- [ ] All committed stories Done
163 +- [ ] Sprint build playable
164 +- [ ] Retrospective completed
165 +- [ ] Backlog groomed for next sprint
166 +
167 +## Output: Sprint Plan
168 +
169 +```markdown
170 +# Sprint Plan: [Game] Sprint [N]
171 +
172 +## Sprint Goal
173 +[One sentence: what's the save point?]
174 +
175 +## Dates
176 +- Start: [Date]
177 +- End: [Date]
178 +- Demo: [Date]
179 +
180 +## Team
181 +| Name | Role | Capacity |
182 +|------|------|----------|
183 +| [X] | [X] | [X] |
184 +
185 +## Committed Stories
186 +| ID | Story | Points | Owner |
187 +|----|-------|--------|-------|
188 +| [X] | [X] | [X] | [X] |
189 +
190 +**Total:** [X] points
191 +
192 +## Sprint Risks
193 +| Risk | Likelihood | Mitigation |
194 +|------|------------|------------|
195 +| [X] | [H/M/L] | [X] |
196 +
197 +## Dependencies
198 +- [Dependency 1]
199 +
200 +## Success Criteria
201 +- [ ] [Playable outcome 1]
202 +- [ ] [Playable outcome 2]
203 +```
204 +
205 +## Sprint Ceremonies
206 +
207 +| Ceremony | When | Duration | Purpose |
208 +|----------|------|----------|---------|
209 +| Planning | Sprint start | 2-4h | Select work |
210 +| Daily | Every day | 15m | Sync blockers |
211 +| Review | Sprint end | 1-2h | Demo to stakeholders |
212 +| Retro | After review | 1h | Process improvement |
213 +
214 +## Game-Specific Considerations
215 +
216 +1. **Playable builds**: Every sprint should produce something playable
217 +2. **Art/code sync**: Plan dependencies across disciplines
218 +3. **Iteration time**: Leave room for "feel" adjustments
219 +4. **Polish debt**: Track juice/polish as explicit work
220 +5. **Playtesting**: Build time for testing into sprints
221 +
222 +## Next Steps
223 +
224 +After sprint planning:
225 +- Use `/gds-dev-story` to implement stories
226 +- Track progress with sprint status checks
227 +
228 +*"Save point created! Let's crush this sprint, team!"*
skills/frameworks/bmad/bmad-code-review/SKILL.md new
+140
@@ -0,0 +1,140 @@
1 +---
2 +name: "bmad-code-review"
3 +description: "Validate code quality and completeness against stories."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["bmad", "review", "quality", "validation"]
7 +trigger_patterns:
8 + - "code review"
9 + - "review code"
10 + - "validate implementation"
11 +---
12 +
13 +# BMAD: Code Review
14 +
15 +Validate implementation quality and completeness.
16 +
17 +## When to Use
18 +
19 +- After completing `/bmad:dev-story`
20 +- Before merging feature branches
21 +- As part of sprint completion
22 +
23 +## Review Framework
24 +
25 +### 1. Story Compliance
26 +
27 +Check against the original story:
28 +
29 +```markdown
30 +## Story Compliance Check
31 +
32 +### Story: {Story Name}
33 +
34 +**Acceptance Criteria:**
35 +- [ ] Criterion 1: [PASS/FAIL] - [Notes]
36 +- [ ] Criterion 2: [PASS/FAIL] - [Notes]
37 +
38 +**Implementation Tasks:**
39 +- [ ] Task 1: [COMPLETE/INCOMPLETE]
40 +- [ ] Task 2: [COMPLETE/INCOMPLETE]
41 +```
42 +
43 +### 2. Code Quality
44 +
45 +Evaluate against BMAD standards:
46 +
47 +| Aspect | Check | Status |
48 +|--------|-------|--------|
49 +| **Readability** | Clear naming, logical structure | ✓/✗ |
50 +| **Maintainability** | DRY, single responsibility | ✓/✗ |
51 +| **Error Handling** | Edge cases covered | ✓/✗ |
52 +| **Security** | No vulnerabilities | ✓/✗ |
53 +| **Performance** | No obvious issues | ✓/✗ |
54 +| **Testing** | Adequate coverage | ✓/✗ |
55 +
56 +### 3. Architecture Alignment
57 +
58 +If architecture doc exists, verify alignment:
59 +
60 +```markdown
61 +## Architecture Compliance
62 +
63 +- [ ] Follows defined patterns
64 +- [ ] Uses approved technologies
65 +- [ ] Respects module boundaries
66 +- [ ] Adheres to data flow design
67 +```
68 +
69 +### 4. Documentation
70 +
71 +Check documentation updates:
72 +
73 +```markdown
74 +## Documentation Review
75 +
76 +- [ ] Code comments where needed
77 +- [ ] README updated if applicable
78 +- [ ] API docs updated if applicable
79 +- [ ] Change log updated
80 +```
81 +
82 +## Review Output
83 +
84 +```markdown
85 +# Code Review: {Story/Feature Name}
86 +
87 +## Summary
88 +[Overall assessment: APPROVED / NEEDS CHANGES / REJECTED]
89 +
90 +## Findings
91 +
92 +### Must Fix
93 +1. [Critical issue]
94 +2. [Critical issue]
95 +
96 +### Should Fix
97 +1. [Important improvement]
98 +2. [Important improvement]
99 +
100 +### Suggestions
101 +1. [Nice to have]
102 +2. [Nice to have]
103 +
104 +## Metrics
105 +- Files changed: X
106 +- Lines added: Y
107 +- Lines removed: Z
108 +- Test coverage: N%
109 +
110 +## Decision
111 +[APPROVE / REQUEST CHANGES / REJECT]
112 +
113 +[If changes requested: specific actions needed]
114 +```
115 +
116 +## Review Checklist
117 +
118 +```markdown
119 +## Pre-Merge Checklist
120 +
121 +- [ ] All acceptance criteria met
122 +- [ ] Tests pass
123 +- [ ] No security issues
124 +- [ ] No performance regressions
125 +- [ ] Documentation complete
126 +- [ ] Code follows project conventions
127 +```
128 +
129 +## Integration with BMAD Workflow
130 +
131 +**Quick Path:**
132 +```
133 +quick-spec → dev-story → code-review ← YOU ARE HERE
134 +```
135 +
136 +**Full Path:**
137 +```
138 +product-brief → create-prd → create-architecture →
139 +create-epics → sprint-planning → dev-story → code-review ← YOU ARE HERE
140 +```
skills/frameworks/bmad/bmad-create-architecture/SKILL.md new
+102
@@ -0,0 +1,102 @@
1 +---
2 +name: "bmad-create-architecture"
3 +description: "Design technical architecture from PRD requirements."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["bmad", "architecture", "design", "technical"]
7 +trigger_patterns:
8 + - "create architecture"
9 + - "design system"
10 + - "architecture document"
11 +---
12 +
13 +# BMAD: Create Architecture
14 +
15 +Design the technical architecture to fulfill PRD requirements.
16 +
17 +## When to Use
18 +
19 +- PRD is approved
20 +- Need technical design before implementation
21 +- Before breaking into epics
22 +
23 +## Architecture Document Structure
24 +
25 +Create `docs/architecture.md`:
26 +
27 +```markdown
28 +# Architecture Document: [Product Name]
29 +
30 +## Overview
31 +[High-level system description]
32 +
33 +## Architecture Diagram
34 +```
35 +[Component diagram - ASCII or reference to image]
36 +```
37 +
38 +## Components
39 +
40 +### Component 1: [Name]
41 +- **Purpose**: [What it does]
42 +- **Technology**: [Stack/framework]
43 +- **Responsibilities**: [What it owns]
44 +- **Interfaces**: [How it communicates]
45 +
46 +## Data Model
47 +
48 +### Entity: [Name]
49 +| Field | Type | Description |
50 +|-------|------|-------------|
51 +| id | UUID | Primary key |
52 +| ... | ... | ... |
53 +
54 +## API Design
55 +
56 +### Endpoint: [Name]
57 +- **Method**: GET/POST/etc
58 +- **Path**: `/api/v1/...`
59 +- **Request**: [Schema]
60 +- **Response**: [Schema]
61 +
62 +## Technology Decisions
63 +
64 +### Decision 1: [What]
65 +- **Options Considered**: [List]
66 +- **Selected**: [Choice]
67 +- **Rationale**: [Why]
68 +
69 +## Security Architecture
70 +- Authentication: [Approach]
71 +- Authorization: [Approach]
72 +- Data Protection: [Approach]
73 +
74 +## Infrastructure
75 +- Hosting: [Where]
76 +- Scaling: [Strategy]
77 +- Deployment: [Process]
78 +
79 +## Performance Considerations
80 +- [Caching strategy]
81 +- [Database optimization]
82 +- [CDN usage]
83 +
84 +## Monitoring & Logging
85 +- [What to monitor]
86 +- [Logging approach]
87 +- [Alerting strategy]
88 +```
89 +
90 +## Output
91 +
92 +```markdown
93 +## Architecture Complete: [Product Name]
94 +
95 +**Components**: [X] main components
96 +**APIs**: [Y] endpoints designed
97 +**Entities**: [Z] data models
98 +
99 +Architecture saved to `docs/architecture.md`
100 +
101 +Ready to define epics? Use `bmad-create-epics`.
102 +```
skills/frameworks/bmad/bmad-create-epics/SKILL.md new
+104
@@ -0,0 +1,104 @@
1 +---
2 +name: "bmad-create-epics"
3 +description: "Break architecture into manageable epics for iterative development."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["bmad", "epics", "agile", "planning"]
7 +trigger_patterns:
8 + - "create epics"
9 + - "break down work"
10 + - "define epics"
11 +---
12 +
13 +# BMAD: Create Epics
14 +
15 +Break the architecture into deliverable epics for iterative development.
16 +
17 +## When to Use
18 +
19 +- Architecture is approved
20 +- Need to plan sprints/iterations
21 +- Before creating developer stories
22 +
23 +## Epic Structure
24 +
25 +Create `docs/epics/` directory with one file per epic:
26 +
27 +```markdown
28 +# Epic: [Epic Name]
29 +
30 +## Overview
31 +[What this epic delivers]
32 +
33 +## Business Value
34 +[Why this matters to users/business]
35 +
36 +## Dependencies
37 +- [Prior epics or external dependencies]
38 +
39 +## User Stories
40 +- US-001: [Title]
41 +- US-002: [Title]
42 +- US-003: [Title]
43 +
44 +## Acceptance Criteria
45 +- [ ] [Criteria 1]
46 +- [ ] [Criteria 2]
47 +
48 +## Technical Scope
49 +- Components affected: [List]
50 +- APIs: [List]
51 +- Data: [List]
52 +
53 +## Estimated Effort
54 +- Story Points: [X]
55 +- Duration: [Y weeks]
56 +
57 +## Risks
58 +- [Risk 1]
59 +- [Risk 2]
60 +```
61 +
62 +## Epic Planning Process
63 +
64 +1. **Identify Deliverables**: What user value can be shipped?
65 +2. **Define Boundaries**: Clear start and end
66 +3. **Order by Dependencies**: What must come first?
67 +4. **Size Appropriately**: 1-4 weeks of work
68 +5. **Assign Stories**: Group related user stories
69 +
70 +## Epic Ordering
71 +
72 +```markdown
73 +## Epic Roadmap
74 +
75 +### Phase 1: Foundation
76 +1. Epic: Core Infrastructure
77 +2. Epic: Authentication
78 +
79 +### Phase 2: Core Features
80 +3. Epic: [Feature A]
81 +4. Epic: [Feature B]
82 +
83 +### Phase 3: Enhancement
84 +5. Epic: [Feature C]
85 +```
86 +
87 +## Output
88 +
89 +```markdown
90 +## Epics Defined: [Product Name]
91 +
92 +**Total Epics**: [X]
93 +**Phases**: [Y]
94 +**Estimated Duration**: [Z weeks]
95 +
96 +### Epic Summary
97 +| Epic | Stories | Points | Phase |
98 +|------|---------|--------|-------|
99 +| [Name] | [X] | [Y] | 1 |
100 +
101 +Epics saved to `docs/epics/`
102 +
103 +Ready to start development? Use `bmad-dev-story` for implementation.
104 +```
skills/frameworks/bmad/bmad-create-prd/SKILL.md new
+148
@@ -0,0 +1,148 @@
1 +---
2 +name: "bmad-create-prd"
3 +description: "Transform product brief into a detailed Product Requirements Document (PRD)."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["bmad", "prd", "requirements", "documentation"]
7 +trigger_patterns:
8 + - "create prd"
9 + - "product requirements"
10 + - "requirements document"
11 +---
12 +
13 +# BMAD: Create PRD
14 +
15 +Transform the product brief into a comprehensive Product Requirements Document.
16 +
17 +## When to Use
18 +
19 +- Product brief is approved
20 +- Need detailed requirements for development
21 +- Before architecture design
22 +
23 +## PRD Structure
24 +
25 +Create `docs/prd.md`:
26 +
27 +```markdown
28 +# Product Requirements Document: [Product Name]
29 +
30 +## Overview
31 +[Summary from product brief]
32 +
33 +## Background
34 +[Context and why this is being built]
35 +
36 +## Goals
37 +[From product brief, refined]
38 +
39 +## User Personas
40 +
41 +### Persona 1: [Name]
42 +- **Role**: [Job/function]
43 +- **Goals**: [What they want to achieve]
44 +- **Pain Points**: [Current frustrations]
45 +- **Technical Proficiency**: [Level]
46 +
47 +## User Stories
48 +
49 +### Epic 1: [Title]
50 +
51 +#### US-001: [Story Title]
52 +**As a** [persona]
53 +**I want to** [capability]
54 +**So that** [benefit]
55 +
56 +**Acceptance Criteria:**
57 +- [ ] Given [context], when [action], then [result]
58 +- [ ] Given [context], when [action], then [result]
59 +
60 +**Priority**: High/Medium/Low
61 +**Estimate**: S/M/L/XL
62 +
63 +## Functional Requirements
64 +
65 +### FR-001: [Requirement Title]
66 +**Description**: [What the system must do]
67 +**Rationale**: [Why this is needed]
68 +**Acceptance**: [How to verify]
69 +
70 +## Non-Functional Requirements
71 +
72 +### Performance
73 +- [Response time requirements]
74 +- [Throughput requirements]
75 +
76 +### Security
77 +- [Authentication requirements]
78 +- [Authorization requirements]
79 +- [Data protection]
80 +
81 +### Scalability
82 +- [Expected load]
83 +- [Growth projections]
84 +
85 +### Reliability
86 +- [Uptime requirements]
87 +- [Recovery requirements]
88 +
89 +## UI/UX Requirements
90 +- [Key interface requirements]
91 +- [Accessibility requirements]
92 +- [Brand guidelines]
93 +
94 +## Data Requirements
95 +- [Data entities needed]
96 +- [Storage requirements]
97 +- [Retention policies]
98 +
99 +## Integration Requirements
100 +- [External systems]
101 +- [APIs needed]
102 +- [Data flows]
103 +
104 +## Constraints
105 +[From product brief, detailed]
106 +
107 +## Assumptions
108 +[What we're assuming is true]
109 +
110 +## Dependencies
111 +[What this depends on]
112 +
113 +## Risks
114 +[From product brief, detailed]
115 +
116 +## Success Metrics
117 +[From product brief, detailed measurement plans]
118 +
119 +## Release Criteria
120 +- [ ] All P0 requirements complete
121 +- [ ] All tests pass
122 +- [ ] Performance benchmarks met
123 +- [ ] Security review complete
124 +- [ ] Documentation complete
125 +```
126 +
127 +## Process
128 +
129 +1. **Review Product Brief**: Ensure vision is clear
130 +2. **Define Personas**: Flesh out user types
131 +3. **Write User Stories**: Convert requirements to stories
132 +4. **Detail Requirements**: Functional and non-functional
133 +5. **Define Acceptance**: Clear criteria for each item
134 +6. **Prioritize**: MoSCoW or similar prioritization
135 +
136 +## Output
137 +
138 +```markdown
139 +## PRD Complete: [Product Name]
140 +
141 +**User Stories**: [X] stories across [Y] epics
142 +**Requirements**: [Z] functional, [W] non-functional
143 +**Priority Distribution**: [breakdown]
144 +
145 +PRD saved to `docs/prd.md`
146 +
147 +Ready to design architecture? Use `bmad-create-architecture`.
148 +```
skills/frameworks/bmad/bmad-dev-story/SKILL.md new
+134
@@ -0,0 +1,134 @@
1 +---
2 +name: "bmad-dev-story"
3 +description: "Generate implementable developer stories from epics with technical specifications."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["bmad", "development", "stories", "implementation"]
7 +trigger_patterns:
8 + - "dev story"
9 + - "implement story"
10 + - "developer story"
11 + - "start development"
12 +---
13 +
14 +# BMAD: Developer Story
15 +
16 +Take a user story from an epic and create a detailed, implementable developer specification.
17 +
18 +## When to Use
19 +
20 +- Starting work on a user story
21 +- Need technical specification for implementation
22 +- Handing off to developers
23 +
24 +## Developer Story Format
25 +
26 +```markdown
27 +# Developer Story: [US-XXX] [Title]
28 +
29 +## User Story
30 +**As a** [persona]
31 +**I want to** [capability]
32 +**So that** [benefit]
33 +
34 +## Technical Specification
35 +
36 +### Overview
37 +[Technical summary of what needs to be built]
38 +
39 +### Implementation Steps
40 +1. [ ] [Step 1 with file references]
41 +2. [ ] [Step 2 with file references]
42 +3. [ ] [Step 3 with file references]
43 +
44 +### Files to Modify
45 +| File | Changes |
46 +|------|---------|
47 +| `path/to/file.py` | [What to change] |
48 +
49 +### Files to Create
50 +| File | Purpose |
51 +|------|---------|
52 +| `path/to/new.py` | [What it does] |
53 +
54 +### API Changes
55 +```
56 +[Endpoint specifications if applicable]
57 +```
58 +
59 +### Data Changes
60 +```
61 +[Schema changes if applicable]
62 +```
63 +
64 +### Dependencies
65 +- [Package/library dependencies]
66 +- [Service dependencies]
67 +
68 +## Acceptance Tests
69 +
70 +### Test 1: [Name]
71 +```
72 +Given: [Setup]
73 +When: [Action]
74 +Then: [Expected result]
75 +```
76 +
77 +### Test 2: [Name]
78 +```
79 +Given: [Setup]
80 +When: [Action]
81 +Then: [Expected result]
82 +```
83 +
84 +## Definition of Done
85 +- [ ] Code complete
86 +- [ ] Unit tests pass
87 +- [ ] Integration tests pass
88 +- [ ] Code reviewed
89 +- [ ] Documentation updated
90 +- [ ] Deployed to staging
91 +```
92 +
93 +## Process
94 +
95 +1. **Load Epic Context**: Read epic and user story
96 +2. **Analyze Requirements**: Understand what's needed
97 +3. **Research Codebase**: Find relevant existing code
98 +4. **Design Solution**: Plan implementation
99 +5. **Write Specification**: Document steps
100 +6. **Define Tests**: Acceptance criteria as tests
101 +7. **Implement**: Follow the specification
102 +
103 +## Output
104 +
105 +After creating developer story:
106 +
107 +```markdown
108 +## Developer Story Ready: [US-XXX]
109 +
110 +**Story**: [Title]
111 +**Steps**: [X] implementation steps
112 +**Tests**: [Y] acceptance tests
113 +
114 +Ready to implement?
115 +```
116 +
117 +## Implementation Flow
118 +
119 +Once story is ready:
120 +
121 +1. Create feature branch
122 +2. Follow implementation steps
123 +3. Write tests as specified
124 +4. Verify acceptance criteria
125 +5. Create pull request
126 +6. Complete Definition of Done
127 +
128 +## Anti-Patterns
129 +
130 +- Vague implementation steps
131 +- Missing test specifications
132 +- No file references
133 +- Forgetting dependencies
134 +- Skipping code review
skills/frameworks/bmad/bmad-product-brief/SKILL.md new
+124
@@ -0,0 +1,124 @@
1 +---
2 +name: "bmad-product-brief"
3 +description: "Create a product brief defining vision, objectives, and high-level requirements."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["bmad", "product", "planning", "vision"]
7 +trigger_patterns:
8 + - "product brief"
9 + - "project vision"
10 + - "define product"
11 + - "start bmad"
12 +---
13 +
14 +# BMAD: Product Brief
15 +
16 +Create a product brief that captures the vision, objectives, and business context for a new product or feature.
17 +
18 +## When to Use
19 +
20 +- Starting a new product or major feature
21 +- Need to align stakeholders on vision
22 +- Before creating detailed requirements
23 +
24 +## Product Brief Structure
25 +
26 +Create `docs/product-brief.md`:
27 +
28 +```markdown
29 +# Product Brief: [Product Name]
30 +
31 +## Vision Statement
32 +[One sentence describing the ultimate goal]
33 +
34 +## Problem Statement
35 +[What problem does this solve? Who has this problem?]
36 +
37 +## Target Users
38 +- **Primary**: [User type and characteristics]
39 +- **Secondary**: [Other user types]
40 +
41 +## Business Objectives
42 +1. [Objective 1 - measurable]
43 +2. [Objective 2 - measurable]
44 +3. [Objective 3 - measurable]
45 +
46 +## Success Metrics
47 +| Metric | Target | Measurement |
48 +|--------|--------|-------------|
49 +| [Metric 1] | [Target] | [How measured] |
50 +| [Metric 2] | [Target] | [How measured] |
51 +
52 +## High-Level Requirements
53 +1. [Core capability 1]
54 +2. [Core capability 2]
55 +3. [Core capability 3]
56 +
57 +## Constraints
58 +- **Technical**: [Any technical limitations]
59 +- **Timeline**: [Target dates]
60 +- **Budget**: [Resource constraints]
61 +- **Compliance**: [Regulatory requirements]
62 +
63 +## Out of Scope
64 +- [What this is NOT]
65 +- [Explicitly excluded features]
66 +
67 +## Risks and Mitigations
68 +| Risk | Impact | Mitigation |
69 +|------|--------|------------|
70 +| [Risk 1] | High/Med/Low | [Strategy] |
71 +
72 +## Stakeholders
73 +- **Owner**: [Who owns this]
74 +- **Contributors**: [Who's involved]
75 +- **Reviewers**: [Who approves]
76 +```
77 +
78 +## Gathering Information
79 +
80 +Ask the user about:
81 +
82 +1. **Problem Space**
83 + - What problem are you solving?
84 + - Who experiences this problem?
85 + - What's the impact of the problem?
86 +
87 +2. **Solution Vision**
88 + - What does success look like?
89 + - How will users benefit?
90 + - What makes this different?
91 +
92 +3. **Business Context**
93 + - What are the business goals?
94 + - What constraints exist?
95 + - Who are the stakeholders?
96 +
97 +4. **Scope**
98 + - What must be included?
99 + - What should be excluded?
100 + - What's the timeline?
101 +
102 +## Output
103 +
104 +After creating the brief:
105 +
106 +```markdown
107 +## Product Brief Complete: [Product Name]
108 +
109 +**Vision**: [One-liner]
110 +**Objectives**: [X] defined
111 +**Core Requirements**: [Y] identified
112 +
113 +Brief saved to `docs/product-brief.md`
114 +
115 +Ready to create detailed PRD? Use `bmad-create-prd`.
116 +```
117 +
118 +## Anti-Patterns
119 +
120 +- Skipping problem definition
121 +- Vague success metrics
122 +- No stakeholder alignment
123 +- Scope creep from day one
124 +- Missing constraints
skills/frameworks/bmad/bmad-quick-spec/SKILL.md new
+138
@@ -0,0 +1,138 @@
1 +---
2 +name: "bmad-quick-spec"
3 +description: "Analyze codebase and produce tech-spec with stories for quick tasks."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["bmad", "quick", "specification", "stories"]
7 +trigger_patterns:
8 + - "quick spec"
9 + - "quick path"
10 + - "simple feature"
11 + - "bug fix spec"
12 +---
13 +
14 +# BMAD: Quick Spec
15 +
16 +Fast-track specification for small features and bug fixes.
17 +
18 +## When to Use
19 +
20 +The Quick Path is for:
21 +- Bug fixes
22 +- Small features with clear scope
23 +- Configuration changes
24 +- Minor enhancements
25 +
26 +**NOT for:**
27 +- New products or platforms
28 +- Complex features requiring architecture
29 +- Work spanning multiple sprints
30 +
31 +## The Quick Path
32 +
33 +```
34 +quick-spec → dev-story → code-review
35 +```
36 +
37 +Just 3 commands instead of the full 6+ step BMAD process.
38 +
39 +## Process
40 +
41 +### 1. Analyze the Request
42 +
43 +Understand what needs to be done:
44 +- What is the problem or requirement?
45 +- What files might be affected?
46 +- Are there existing patterns to follow?
47 +
48 +### 2. Codebase Analysis
49 +
50 +Examine relevant parts of the codebase:
51 +
52 +```markdown
53 +## Codebase Analysis
54 +
55 +### Affected Areas
56 +- [File/module 1]: [What it does]
57 +- [File/module 2]: [What it does]
58 +
59 +### Existing Patterns
60 +- [Pattern 1]: [How it's used]
61 +- [Pattern 2]: [How it's used]
62 +
63 +### Dependencies
64 +- [Dependency 1]: [Relevance]
65 +```
66 +
67 +### 3. Generate Tech Spec
68 +
69 +Create a lightweight technical specification:
70 +
71 +```markdown
72 +# Tech Spec: {Feature/Fix Name}
73 +
74 +## Summary
75 +[One sentence description]
76 +
77 +## Problem
78 +[What issue this solves]
79 +
80 +## Solution
81 +[High-level approach]
82 +
83 +## Implementation Details
84 +
85 +### Changes Required
86 +1. [Change 1]
87 +2. [Change 2]
88 +
89 +### Files Affected
90 +- `path/to/file1.ts` - [What changes]
91 +- `path/to/file2.ts` - [What changes]
92 +
93 +## Testing
94 +- [ ] [Test case 1]
95 +- [ ] [Test case 2]
96 +
97 +## Acceptance Criteria
98 +- [ ] [Criterion 1]
99 +- [ ] [Criterion 2]
100 +```
101 +
102 +### 4. Generate Stories
103 +
104 +Break the spec into implementable stories:
105 +
106 +```markdown
107 +## Stories
108 +
109 +### Story 1: {Name}
110 +**As a** [user type]
111 +**I want** [capability]
112 +**So that** [benefit]
113 +
114 +**Tasks:**
115 +- [ ] Task 1
116 +- [ ] Task 2
117 +
118 +**Acceptance Criteria:**
119 +- [ ] Criterion 1
120 +```
121 +
122 +## Output
123 +
124 +**Creates:**
125 +- `QUICK-SPEC.md` - Technical specification
126 +- Stories ready for `/bmad:dev-story`
127 +
128 +## Next Steps
129 +
130 +After quick-spec:
131 +1. `/bmad:dev-story` - Implement each story
132 +2. `/bmad:code-review` - Validate quality
133 +
134 +## Integration with Full Path
135 +
136 +If during quick-spec you discover the task is more complex:
137 +- Stop the quick path
138 +- Switch to full BMAD path starting with `/bmad:product-brief`
skills/frameworks/bmad/bmad-sprint-planning/SKILL.md new
+151
@@ -0,0 +1,151 @@
1 +---
2 +name: "bmad-sprint-planning"
3 +description: "Initialize sprint tracking and select stories for the sprint."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["bmad", "sprint", "planning", "agile"]
7 +trigger_patterns:
8 + - "sprint planning"
9 + - "plan sprint"
10 + - "initialize sprint"
11 +---
12 +
13 +# BMAD: Sprint Planning
14 +
15 +Initialize sprint tracking and select stories for implementation.
16 +
17 +## When to Use
18 +
19 +- After epics and stories are created (`/bmad:create-epics`)
20 +- At the start of each development sprint
21 +- When re-planning mid-sprint
22 +
23 +## Prerequisites
24 +
25 +- Epics and stories defined
26 +- Story estimates available (or will be created)
27 +- Team capacity known
28 +
29 +## Process
30 +
31 +### 1. Review Backlog
32 +
33 +Examine available stories:
34 +
35 +```markdown
36 +## Backlog Review
37 +
38 +### High Priority
39 +| Story | Epic | Estimate | Status |
40 +|-------|------|----------|--------|
41 +| Story 1 | Epic A | 3 pts | Ready |
42 +| Story 2 | Epic A | 5 pts | Ready |
43 +
44 +### Medium Priority
45 +| Story | Epic | Estimate | Status |
46 +|-------|------|----------|--------|
47 +| Story 3 | Epic B | 2 pts | Ready |
48 +
49 +### Needs Refinement
50 +| Story | Epic | Issue |
51 +|-------|------|-------|
52 +| Story 4 | Epic B | Unclear requirements |
53 +```
54 +
55 +### 2. Estimate Stories
56 +
57 +If stories need estimates:
58 +
59 +```markdown
60 +## Story Estimation
61 +
62 +### Story: {Name}
63 +**Complexity factors:**
64 +- [ ] Code changes: [Simple/Medium/Complex]
65 +- [ ] Testing needs: [Low/Medium/High]
66 +- [ ] Integration: [None/Some/Heavy]
67 +- [ ] Risk: [Low/Medium/High]
68 +
69 +**Estimate:** X points
70 +
71 +**Rationale:** [Why this estimate]
72 +```
73 +
74 +### 3. Set Sprint Capacity
75 +
76 +```markdown
77 +## Sprint Capacity
78 +
79 +**Sprint duration:** X days/weeks
80 +**Team velocity:** Y points (based on history or estimate)
81 +**Available capacity:** Z points (accounting for meetings, etc.)
82 +```
83 +
84 +### 4. Select Sprint Stories
85 +
86 +Choose stories that fit capacity:
87 +
88 +```markdown
89 +## Sprint {N} Plan
90 +
91 +**Goal:** [Sprint goal in one sentence]
92 +
93 +**Selected Stories:**
94 +| # | Story | Epic | Points | Priority |
95 +|---|-------|------|--------|----------|
96 +| 1 | Story 1 | Epic A | 3 | Must have |
97 +| 2 | Story 2 | Epic A | 5 | Must have |
98 +| 3 | Story 3 | Epic B | 2 | Should have |
99 +
100 +**Total Points:** X / Y capacity
101 +
102 +**Stretch Goals (if time permits):**
103 +- Story 4 (2 pts)
104 +```
105 +
106 +### 5. Initialize Sprint Tracking
107 +
108 +Create sprint tracking file:
109 +
110 +```markdown
111 +# Sprint {N}: {Sprint Name}
112 +
113 +**Start:** YYYY-MM-DD
114 +**End:** YYYY-MM-DD
115 +**Goal:** [Sprint goal]
116 +
117 +## Progress
118 +
119 +| Story | Status | Assigned | Notes |
120 +|-------|--------|----------|-------|
121 +| Story 1 | Not Started | - | |
122 +| Story 2 | Not Started | - | |
123 +
124 +## Daily Updates
125 +### Day 1
126 +- Started:
127 +- Completed:
128 +- Blockers:
129 +```
130 +
131 +## Output
132 +
133 +**Creates:**
134 +- `SPRINT-{N}.md` - Sprint tracking document
135 +- Updated story statuses
136 +
137 +## Next Steps
138 +
139 +After sprint planning:
140 +1. `/bmad:dev-story` - Work on each selected story
141 +2. Track progress in sprint document
142 +3. `/bmad:code-review` - Review completed work
143 +
144 +## Sprint Ceremonies (Reference)
145 +
146 +| Ceremony | When | Purpose |
147 +|----------|------|---------|
148 +| **Planning** | Sprint start | Select stories, set goal |
149 +| **Daily standup** | Daily | Sync progress, identify blockers |
150 +| **Review** | Sprint end | Demo completed work |
151 +| **Retrospective** | Sprint end | Improve process |
skills/frameworks/gsd/gsd-complete-milestone/SKILL.md new
+114
@@ -0,0 +1,114 @@
1 +---
2 +name: "gsd-complete-milestone"
3 +description: "Archive completed milestone, tag release, and prepare for next iteration."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["gsd", "milestone", "release", "completion"]
7 +trigger_patterns:
8 + - "complete milestone"
9 + - "finish milestone"
10 + - "archive milestone"
11 + - "tag release"
12 +---
13 +
14 +# GSD: Complete Milestone
15 +
16 +Archive the milestone and prepare for the next development cycle.
17 +
18 +## When to Use
19 +
20 +- After all phases in the current milestone are verified
21 +- When ready to tag a release
22 +- Before starting `gsd-new-milestone` for the next version
23 +
24 +## Prerequisites
25 +
26 +- All phases in the milestone should be complete
27 +- All verification steps should pass
28 +- No critical issues remaining
29 +
30 +## Process
31 +
32 +### 1. Milestone Audit
33 +
34 +Before completing, verify:
35 +
36 +```markdown
37 +## Milestone Audit Checklist
38 +
39 +- [ ] All planned phases are complete
40 +- [ ] Verification passed for each phase
41 +- [ ] No critical bugs or blockers
42 +- [ ] Documentation is current
43 +- [ ] All changes are committed
44 +```
45 +
46 +### 2. Archive Milestone
47 +
48 +Move milestone files to archive:
49 +
50 +```
51 +.planning/
52 +├── archive/
53 +│ └── v{version}/
54 +│ ├── PROJECT.md
55 +│ ├── REQUIREMENTS.md
56 +│ ├── ROADMAP.md
57 +│ ├── phases/
58 +│ │ ├── 1-CONTEXT.md
59 +│ │ ├── 1-RESEARCH.md
60 +│ │ ├── 1-*-PLAN.md
61 +│ │ └── ...
62 +│ └── STATE.md
63 +```
64 +
65 +### 3. Tag Release
66 +
67 +Create a git tag for the milestone:
68 +
69 +```bash
70 +git tag -a v{version} -m "Milestone: {milestone_name}"
71 +```
72 +
73 +### 4. Generate Summary
74 +
75 +Create a milestone summary:
76 +
77 +```markdown
78 +## Milestone Summary: {name}
79 +
80 +### Delivered
81 +- [Feature 1]
82 +- [Feature 2]
83 +
84 +### Metrics
85 +- Phases completed: X
86 +- Plans executed: Y
87 +- Total commits: Z
88 +
89 +### Key Decisions
90 +- [Decision 1]: [Rationale]
91 +- [Decision 2]: [Rationale]
92 +
93 +### Lessons Learned
94 +- [Lesson 1]
95 +- [Lesson 2]
96 +
97 +### Next Steps
98 +- [Suggestion for next milestone]
99 +```
100 +
101 +## Output
102 +
103 +**Creates:**
104 +- Archive folder with milestone artifacts
105 +- Git tag for the release
106 +- `MILESTONE-SUMMARY.md`
107 +
108 +## Usage
109 +
110 +```
111 +/gsd:complete-milestone
112 +```
113 +
114 +After completion, use `/gsd:new-milestone` to start the next version.
skills/frameworks/gsd/gsd-discuss-phase/SKILL.md new
+93
@@ -0,0 +1,93 @@
1 +---
2 +name: "gsd-discuss-phase"
3 +description: "Capture implementation decisions and user preferences before planning begins."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["gsd", "discussion", "planning", "elicitation"]
7 +trigger_patterns:
8 + - "discuss phase"
9 + - "capture decisions"
10 + - "implementation preferences"
11 +---
12 +
13 +# GSD: Discuss Phase
14 +
15 +Shape the implementation before research and planning begins.
16 +
17 +## When to Use
18 +
19 +- After `gsd-new-project` has created the roadmap
20 +- Before `gsd-plan-phase` for a specific phase
21 +- When you need to capture user preferences for how something should be built
22 +
23 +## Purpose
24 +
25 +Your roadmap has a sentence or two per phase. That's not enough context to build something the way the user imagines it. This step captures preferences before anything gets researched or planned.
26 +
27 +## Process
28 +
29 +### 1. Analyze the Phase
30 +
31 +Identify gray areas based on what's being built:
32 +
33 +| Feature Type | Questions to Explore |
34 +|-------------|---------------------|
35 +| **Visual features** | Layout, density, interactions, empty states |
36 +| **APIs/CLIs** | Response format, flags, error handling, verbosity |
37 +| **Content systems** | Structure, tone, depth, flow |
38 +| **Organization tasks** | Grouping criteria, naming, duplicates, exceptions |
39 +
40 +### 2. Interactive Discussion
41 +
42 +For each area the user selects:
43 +- Ask targeted questions
44 +- Drill deeper on important decisions
45 +- Stop when user is satisfied
46 +
47 +### 3. Create CONTEXT.md
48 +
49 +Document all decisions in a structured format:
50 +
51 +```markdown
52 +# Phase {N} Context: {Phase Name}
53 +
54 +## Decisions Made
55 +
56 +### {Area 1}
57 +- **Decision**: [What was decided]
58 +- **Rationale**: [Why this choice]
59 +
60 +### {Area 2}
61 +...
62 +
63 +## Constraints Identified
64 +- [Constraint 1]
65 +- [Constraint 2]
66 +
67 +## Open Questions (for Research)
68 +- [Question 1]
69 +- [Question 2]
70 +```
71 +
72 +## Output
73 +
74 +**Creates:** `{phase}-CONTEXT.md`
75 +
76 +This file feeds directly into:
77 +1. **Researcher** — Knows what patterns to investigate
78 +2. **Planner** — Knows what decisions are locked
79 +
80 +## Best Practices
81 +
82 +- Keep discussions focused on one phase at a time
83 +- Document preferences even if they seem obvious
84 +- Distinguish between firm decisions and preferences
85 +- Note any constraints that affect implementation choices
86 +
87 +## Usage
88 +
89 +```
90 +/gsd:discuss-phase 1
91 +```
92 +
93 +Replace `1` with the phase number from your roadmap.
skills/frameworks/gsd/gsd-execute-phase/SKILL.md new
+137
@@ -0,0 +1,137 @@
1 +---
2 +name: "gsd-execute-phase"
3 +description: "Implement the approved plan with regular checkpoints and progress tracking."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["gsd", "implementation", "execution", "coding"]
7 +trigger_patterns:
8 + - "execute"
9 + - "implement"
10 + - "start coding"
11 + - "build"
12 +---
13 +
14 +# GSD: Execute Phase
15 +
16 +Use this skill to implement an approved plan systematically with progress tracking.
17 +
18 +## When to Use
19 +
20 +- After plan has been approved
21 +- User says "start implementing" or "execute the plan"
22 +- Ready to write code
23 +
24 +## Prerequisites
25 +
26 +- An approved plan exists in `.gsd/plan.md`
27 +- User has confirmed they want to proceed
28 +
29 +## Execution Process
30 +
31 +### 1. Load the Plan
32 +
33 +Read `.gsd/plan.md` and present the task list:
34 +
35 +```markdown
36 +## Starting Execution: [Feature Name]
37 +
38 +**Tasks to complete:**
39 +1. [ ] Task 1
40 +2. [ ] Task 2
41 +3. [ ] Task 3
42 +
43 +Beginning with Task 1...
44 +```
45 +
46 +### 2. Work Through Tasks Sequentially
47 +
48 +For each task:
49 +
50 +1. **Announce** what you're about to do
51 +2. **Implement** the changes
52 +3. **Verify** the change works (run tests, check syntax)
53 +4. **Update** the checklist
54 +5. **Report** completion before moving on
55 +
56 +```markdown
57 +### Task 1: [Description]
58 +**Status**: In Progress
59 +
60 +[Implementation details...]
61 +
62 +**Result**: Complete
63 +- Created `path/to/file.py`
64 +- Modified `path/to/other.py`
65 +- Tests: Passing
66 +
67 +Moving to Task 2...
68 +```
69 +
70 +### 3. Handle Issues
71 +
72 +When encountering problems:
73 +
74 +1. **Stop** and describe the issue clearly
75 +2. **Propose** solutions
76 +3. **Ask** for user input on how to proceed
77 +4. **Don't** silently make major deviations from the plan
78 +
79 +```markdown
80 +### Issue Encountered
81 +
82 +**Problem**: [Description]
83 +**Impact**: [What this affects]
84 +
85 +**Options**:
86 +A) [Solution A]
87 +B) [Solution B]
88 +
89 +How would you like to proceed?
90 +```
91 +
92 +### 4. Update Progress
93 +
94 +After each task, update `.gsd/plan.md`:
95 +- Mark completed tasks with [x]
96 +- Add notes about any deviations
97 +- Track files actually modified
98 +
99 +### 5. Checkpoint at Milestones
100 +
101 +Every 3-4 tasks, or at natural breakpoints:
102 +
103 +```markdown
104 +## Progress Checkpoint
105 +
106 +**Completed**: 4/8 tasks
107 +**Files modified**:
108 +- file1.py (200 lines)
109 +- file2.py (50 lines)
110 +
111 +**Status**: On track
112 +
113 +Continue with remaining tasks?
114 +```
115 +
116 +## Completion
117 +
118 +When all tasks are done:
119 +
120 +```markdown
121 +## Execution Complete: [Feature Name]
122 +
123 +**Tasks**: 8/8 complete
124 +**Files created**: 3
125 +**Files modified**: 5
126 +**Tests**: All passing
127 +
128 +Ready for verification phase? Use `gsd-verify-work` to validate.
129 +```
130 +
131 +## Anti-Patterns
132 +
133 +- Don't skip tasks without user approval
134 +- Don't make undocumented changes
135 +- Don't continue past errors without resolving them
136 +- Don't forget to run tests after changes
137 +- Don't implement features not in the plan
skills/frameworks/gsd/gsd-new-project/SKILL.md new
+97
@@ -0,0 +1,97 @@
1 +---
2 +name: "gsd-new-project"
3 +description: "Initialize a new GSD (Get Stuff Done) project with proper structure and roadmap."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["gsd", "planning", "initialization", "project-setup"]
7 +trigger_patterns:
8 + - "start project"
9 + - "new project"
10 + - "initialize project"
11 + - "setup gsd"
12 +---
13 +
14 +# GSD: New Project Setup
15 +
16 +Use this skill when starting a new project with the GSD (Get Stuff Done) methodology.
17 +
18 +## When to Use
19 +
20 +- User asks to start a new project
21 +- User wants to set up a structured development workflow
22 +- Beginning work on a greenfield feature or application
23 +
24 +## Project Structure
25 +
26 +Create the following structure in the project directory:
27 +
28 +```
29 +project/
30 +├── docs/
31 +│ ├── roadmap.md # High-level project roadmap
32 +│ ├── decisions/ # Architecture Decision Records
33 +│ └── specs/ # Feature specifications
34 +├── src/ # Source code
35 +├── tests/ # Test files
36 +└── .gsd/
37 + ├── plan.md # Current implementation plan
38 + ├── checklist.md # Progress checklist
39 + └── context.md # Project context for AI
40 +```
41 +
42 +## Step-by-Step Process
43 +
44 +### 1. Gather Project Requirements
45 +
46 +Ask the user:
47 +- What is the project name and purpose?
48 +- What are the primary goals?
49 +- What technologies/stack will be used?
50 +- What are the key constraints or requirements?
51 +
52 +### 2. Create Roadmap
53 +
54 +In `docs/roadmap.md`, document:
55 +- Project vision (1-2 sentences)
56 +- Key milestones (3-5 major phases)
57 +- Success criteria
58 +- Known risks/dependencies
59 +
60 +### 3. Initialize GSD Context
61 +
62 +Create `.gsd/context.md` with:
63 +- Project summary
64 +- Tech stack details
65 +- Coding conventions
66 +- Testing approach
67 +
68 +### 4. Set Up First Plan
69 +
70 +Create `.gsd/plan.md` with the first milestone broken down:
71 +- Clear objective
72 +- Numbered tasks
73 +- Acceptance criteria
74 +
75 +## Example Output
76 +
77 +After initialization, provide this summary:
78 +
79 +```markdown
80 +## Project Initialized: [Project Name]
81 +
82 +**Location**: /path/to/project
83 +**Framework**: GSD (Get Stuff Done)
84 +
85 +### Next Steps
86 +1. Review the roadmap in `docs/roadmap.md`
87 +2. Start planning phase with `gsd-plan-phase` skill
88 +3. Begin implementation once plan is approved
89 +
90 +Ready to proceed to planning phase?
91 +```
92 +
93 +## Anti-Patterns
94 +
95 +- Don't skip requirements gathering
96 +- Don't create overly detailed plans upfront (plans evolve)
97 +- Don't proceed without user confirmation of goals
skills/frameworks/gsd/gsd-plan-phase/SKILL.md new
+126
@@ -0,0 +1,126 @@
1 +---
2 +name: "gsd-plan-phase"
3 +description: "Collaborate with user to create a detailed implementation plan before coding."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["gsd", "planning", "collaboration", "design"]
7 +trigger_patterns:
8 + - "plan"
9 + - "create plan"
10 + - "planning phase"
11 + - "design"
12 +---
13 +
14 +# GSD: Plan Phase
15 +
16 +Use this skill to create a detailed implementation plan collaboratively with the user before any coding begins.
17 +
18 +## When to Use
19 +
20 +- After project initialization
21 +- Before starting a new feature
22 +- When requirements need clarification
23 +- User asks to "plan" something
24 +
25 +## Core Principle
26 +
27 +**No coding without a plan. No plan without user approval.**
28 +
29 +## Planning Process
30 +
31 +### 1. Understand the Goal
32 +
33 +Ask clarifying questions:
34 +- What specific outcome do you want?
35 +- What does success look like?
36 +- Are there constraints (time, tech, compatibility)?
37 +- What's the scope boundary?
38 +
39 +### 2. Research Existing Code
40 +
41 +Before proposing solutions:
42 +- Examine relevant existing files
43 +- Identify patterns already in use
44 +- Note integration points
45 +- Check for similar implementations
46 +
47 +### 3. Present Options
48 +
49 +Provide 2-3 implementation approaches:
50 +
51 +```markdown
52 +## Option A: [Name]
53 +**Approach**: Brief description
54 +**Pros**: Benefits list
55 +**Cons**: Drawbacks list
56 +**Effort**: Low/Medium/High
57 +
58 +## Option B: [Name]
59 +**Approach**: Brief description
60 +**Pros**: Benefits list
61 +**Cons**: Drawbacks list
62 +**Effort**: Low/Medium/High
63 +```
64 +
65 +### 4. Get User Decision
66 +
67 +Ask the user to choose an approach. Don't proceed without explicit selection.
68 +
69 +### 5. Create Detailed Plan
70 +
71 +Once approach is selected, create `.gsd/plan.md`:
72 +
73 +```markdown
74 +# Implementation Plan: [Feature Name]
75 +
76 +## Objective
77 +[Clear statement of what we're building]
78 +
79 +## Chosen Approach
80 +[Selected option with rationale]
81 +
82 +## Tasks
83 +1. [ ] Task 1 - Description
84 + - Subtask 1a
85 + - Subtask 1b
86 +2. [ ] Task 2 - Description
87 +3. [ ] Task 3 - Description
88 +4. [ ] Task 4 - Integration testing
89 +
90 +## Files to Modify/Create
91 +- `path/to/file.py` - Description of changes
92 +- `path/to/new_file.py` - New file for X
93 +
94 +## Acceptance Criteria
95 +- [ ] Criterion 1
96 +- [ ] Criterion 2
97 +- [ ] Tests pass
98 +```
99 +
100 +### 6. Confirm and Proceed
101 +
102 +Present the plan and ask:
103 +> "Here's the implementation plan. Review and let me know if you'd like any changes. Once approved, I'll begin the execute phase."
104 +
105 +## Output Format
106 +
107 +After planning is complete:
108 +
109 +```markdown
110 +## Plan Created: [Feature Name]
111 +
112 +**Tasks**: [X] items
113 +**Files affected**: [Y] files
114 +**Estimated complexity**: Low/Medium/High
115 +
116 +Plan saved to `.gsd/plan.md`
117 +
118 +Ready to start implementation? Use `gsd-execute-phase` to begin.
119 +```
120 +
121 +## Anti-Patterns
122 +
123 +- Don't start coding without plan approval
124 +- Don't create plans that are too detailed (leave room for discovery)
125 +- Don't skip the options discussion
126 +- Don't assume requirements - always confirm
skills/frameworks/gsd/gsd-verify-work/SKILL.md new
+162
@@ -0,0 +1,162 @@
1 +---
2 +name: "gsd-verify-work"
3 +description: "Validate completed implementation against requirements and acceptance criteria."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["gsd", "verification", "testing", "quality"]
7 +trigger_patterns:
8 + - "verify"
9 + - "check work"
10 + - "validate"
11 + - "review implementation"
12 +---
13 +
14 +# GSD: Verify Work
15 +
16 +Use this skill to validate that the implementation meets all requirements and acceptance criteria.
17 +
18 +## When to Use
19 +
20 +- After completing the execute phase
21 +- Before marking a feature as done
22 +- When user asks to verify or check work
23 +
24 +## Verification Process
25 +
26 +### 1. Load Acceptance Criteria
27 +
28 +Read from `.gsd/plan.md` and list all acceptance criteria:
29 +
30 +```markdown
31 +## Verification: [Feature Name]
32 +
33 +**Acceptance Criteria:**
34 +- [ ] Criterion 1
35 +- [ ] Criterion 2
36 +- [ ] Criterion 3
37 +- [ ] Tests pass
38 +```
39 +
40 +### 2. Run Automated Tests
41 +
42 +Execute the test suite:
43 +
44 +```bash
45 +# Run relevant tests
46 +pytest tests/
47 +# or npm test, cargo test, etc.
48 +```
49 +
50 +Report results:
51 +```markdown
52 +### Test Results
53 +**Total**: 24 tests
54 +**Passed**: 24
55 +**Failed**: 0
56 +**Skipped**: 0
57 +```
58 +
59 +### 3. Manual Verification Checklist
60 +
61 +Walk through each acceptance criterion:
62 +
63 +```markdown
64 +### Criterion 1: [Description]
65 +**Check**: [How to verify]
66 +**Result**: PASS/FAIL
67 +**Evidence**: [What was observed]
68 +
69 +### Criterion 2: [Description]
70 +**Check**: [How to verify]
71 +**Result**: PASS/FAIL
72 +**Evidence**: [What was observed]
73 +```
74 +
75 +### 4. Code Quality Check
76 +
77 +Review the implementation for:
78 +
79 +- [ ] No obvious bugs or errors
80 +- [ ] Consistent with existing code style
81 +- [ ] No security vulnerabilities
82 +- [ ] Error handling in place
83 +- [ ] No hardcoded secrets or debug code
84 +
85 +### 5. Documentation Check
86 +
87 +Verify:
88 +- [ ] README updated if needed
89 +- [ ] Comments for complex logic
90 +- [ ] API documentation if applicable
91 +
92 +### 6. Generate Verification Report
93 +
94 +```markdown
95 +## Verification Report: [Feature Name]
96 +
97 +### Summary
98 +**Status**: PASSED / FAILED
99 +**Date**: [Date]
100 +
101 +### Acceptance Criteria
102 +| Criterion | Status | Notes |
103 +|-----------|--------|-------|
104 +| Criterion 1 | PASS | |
105 +| Criterion 2 | PASS | |
106 +| Tests pass | PASS | 24/24 |
107 +
108 +### Code Quality
109 +- Style: Consistent
110 +- Security: No issues
111 +- Error handling: Present
112 +
113 +### Issues Found
114 +[None / List of issues]
115 +
116 +### Recommendation
117 +Ready for deployment / Needs fixes
118 +```
119 +
120 +## If Verification Fails
121 +
122 +When criteria are not met:
123 +
124 +```markdown
125 +### Verification Failed
126 +
127 +**Failed criteria:**
128 +1. [Criterion that failed]
129 + - Expected: [what was expected]
130 + - Actual: [what was observed]
131 +
132 +**Recommended fixes:**
133 +1. [Fix for issue 1]
134 +
135 +Return to execute phase to address these issues?
136 +```
137 +
138 +## Completion
139 +
140 +When all criteria pass:
141 +
142 +```markdown
143 +## Feature Complete: [Feature Name]
144 +
145 +All acceptance criteria verified.
146 +All tests passing.
147 +Code quality checks passed.
148 +
149 +**Next steps:**
150 +- Commit changes
151 +- Create pull request (if applicable)
152 +- Move to next feature
153 +
154 +Would you like me to help with the commit?
155 +```
156 +
157 +## Anti-Patterns
158 +
159 +- Don't skip verification
160 +- Don't mark as complete with failing tests
161 +- Don't ignore edge cases in verification
162 +- Don't approve without checking acceptance criteria
skills/frameworks/prp/prp-execute/SKILL.md new
+79
@@ -0,0 +1,79 @@
1 +---
2 +name: "prp-execute"
3 +description: "Execute a PRP specification systematically."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["prp", "execution", "implementation"]
7 +trigger_patterns:
8 + - "execute prp"
9 + - "run prp"
10 + - "follow prompt"
11 +---
12 +
13 +# PRP: Execute
14 +
15 +Execute a Prompt-Response Protocol specification systematically.
16 +
17 +## When to Use
18 +
19 +- PRP has been generated
20 +- Ready to perform the task
21 +- Following an established protocol
22 +
23 +## Execution Process
24 +
25 +1. **Load PRP**: Read the protocol specification
26 +2. **Gather Inputs**: Collect all required inputs
27 +3. **Follow Steps**: Execute each step in order
28 +4. **Produce Outputs**: Generate specified outputs
29 +5. **Validate**: Check against quality criteria
30 +
31 +## Execution Template
32 +
33 +```markdown
34 +## Executing PRP: [Task Name]
35 +
36 +### Inputs Collected
37 +- [Input 1]: [Value/Source]
38 +- [Input 2]: [Value/Source]
39 +
40 +### Step Execution
41 +
42 +#### Step 1: [Name]
43 +**Action**: [What was done]
44 +**Result**: [Outcome]
45 +
46 +#### Step 2: [Name]
47 +**Action**: [What was done]
48 +**Result**: [Outcome]
49 +
50 +### Outputs Produced
51 +- [Output 1]: [Location/Content]
52 +- [Output 2]: [Location/Content]
53 +
54 +### Validation
55 +- [ ] [Criterion 1]: PASS/FAIL
56 +- [ ] [Criterion 2]: PASS/FAIL
57 +
58 +### Status
59 +**Result**: SUCCESS/FAILED
60 +```
61 +
62 +## Error Handling
63 +
64 +When errors occur:
65 +1. Check PRP error handling section
66 +2. Follow prescribed response
67 +3. If not covered, pause and report
68 +
69 +## Output
70 +
71 +```markdown
72 +## PRP Execution Complete: [Task Name]
73 +
74 +**Status**: Success
75 +**Outputs**: [List]
76 +**Validation**: All criteria passed
77 +
78 +[Outputs available at specified locations]
79 +```
skills/frameworks/prp/prp-generate/SKILL.md new
+94
@@ -0,0 +1,94 @@
1 +---
2 +name: "prp-generate"
3 +description: "Generate a comprehensive Prompt-Response Protocol specification for a task."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["prp", "prompt-engineering", "specification"]
7 +trigger_patterns:
8 + - "generate prp"
9 + - "create prompt"
10 + - "prp specification"
11 +---
12 +
13 +# PRP: Generate
14 +
15 +Generate a comprehensive Prompt-Response Protocol for a development task.
16 +
17 +## When to Use
18 +
19 +- Well-defined, repeatable tasks
20 +- Need consistent execution
21 +- Creating reusable prompts
22 +
23 +## PRP Structure
24 +
25 +A PRP contains everything needed for task execution:
26 +
27 +```markdown
28 +# PRP: [Task Name]
29 +
30 +## Context
31 +[Background and environment information]
32 +
33 +## Objective
34 +[Clear statement of what must be accomplished]
35 +
36 +## Inputs
37 +- [Input 1]: [Description and format]
38 +- [Input 2]: [Description and format]
39 +
40 +## Constraints
41 +- [Constraint 1]
42 +- [Constraint 2]
43 +
44 +## Process Steps
45 +1. [Step 1 - specific action]
46 +2. [Step 2 - specific action]
47 +3. [Step 3 - specific action]
48 +
49 +## Expected Outputs
50 +- [Output 1]: [Format and content]
51 +- [Output 2]: [Format and content]
52 +
53 +## Quality Criteria
54 +- [ ] [Criterion 1]
55 +- [ ] [Criterion 2]
56 +
57 +## Examples
58 +
59 +### Example 1
60 +**Input**: [Sample]
61 +**Process**: [Brief walkthrough]
62 +**Output**: [Expected result]
63 +
64 +## Error Handling
65 +| Condition | Response |
66 +|-----------|----------|
67 +| [Error 1] | [Action] |
68 +
69 +## Validation
70 +[How to verify the output is correct]
71 +```
72 +
73 +## Generation Process
74 +
75 +1. **Understand the Task**: What needs to be done?
76 +2. **Identify Inputs**: What information is needed?
77 +3. **Define Steps**: What's the process?
78 +4. **Specify Outputs**: What should be produced?
79 +5. **Add Examples**: Concrete illustrations
80 +6. **Define Validation**: How to check correctness
81 +
82 +## Output
83 +
84 +```markdown
85 +## PRP Generated: [Task Name]
86 +
87 +**Steps**: [X] defined
88 +**Inputs**: [Y] required
89 +**Outputs**: [Z] specified
90 +
91 +PRP saved to `prp/[task-name].md`
92 +
93 +Ready to execute? Use `prp-execute`.
94 +```
skills/frameworks/speckit/speckit-constitution/SKILL.md new
+78
@@ -0,0 +1,78 @@
1 +---
2 +name: "speckit-constitution"
3 +description: "Define project constitution with principles, constraints, and non-negotiables."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["speckit", "planning", "principles", "foundation"]
7 +trigger_patterns:
8 + - "constitution"
9 + - "define principles"
10 + - "project rules"
11 +---
12 +
13 +# Spec Kit: Constitution
14 +
15 +Define the foundational principles and constraints that guide all project decisions.
16 +
17 +## When to Use
18 +
19 +- Starting a new project with Spec Kit
20 +- Need to establish non-negotiable rules
21 +- Before creating specifications
22 +
23 +## Constitution Structure
24 +
25 +Create `CONSTITUTION.md`:
26 +
27 +```markdown
28 +# Project Constitution: [Project Name]
29 +
30 +## Core Principles
31 +1. [Principle 1 - e.g., "Security is non-negotiable"]
32 +2. [Principle 2 - e.g., "Simple over clever"]
33 +3. [Principle 3 - e.g., "Test everything"]
34 +
35 +## Technology Stack
36 +- Language: [Primary language]
37 +- Framework: [Framework choice]
38 +- Database: [Data storage]
39 +- Infrastructure: [Hosting/deployment]
40 +
41 +## Coding Standards
42 +- Style Guide: [Reference]
43 +- Formatting: [Tool, e.g., Prettier, Black]
44 +- Linting: [Tool and config]
45 +
46 +## Testing Requirements
47 +- Unit Test Coverage: [Minimum %]
48 +- Integration Tests: [Required/Optional]
49 +- E2E Tests: [Required/Optional]
50 +
51 +## Quality Gates
52 +- [ ] All tests must pass
53 +- [ ] No linting errors
54 +- [ ] Code review required
55 +- [ ] [Other gates]
56 +
57 +## Non-Negotiables
58 +- [Thing that cannot be compromised 1]
59 +- [Thing that cannot be compromised 2]
60 +
61 +## Conventions
62 +- Naming: [Convention]
63 +- File Structure: [Pattern]
64 +- Commit Messages: [Format]
65 +```
66 +
67 +## Output
68 +
69 +```markdown
70 +## Constitution Created: [Project Name]
71 +
72 +**Principles**: [X] defined
73 +**Non-negotiables**: [Y] established
74 +
75 +Constitution saved to `CONSTITUTION.md`
76 +
77 +Ready to specify features? Use `speckit-specify`.
78 +```
skills/frameworks/speckit/speckit-implement/SKILL.md new
+65
@@ -0,0 +1,65 @@
1 +---
2 +name: "speckit-implement"
3 +description: "Execute tasks following specifications and constitution."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["speckit", "implementation", "execution"]
7 +trigger_patterns:
8 + - "implement task"
9 + - "execute task"
10 + - "start task"
11 +---
12 +
13 +# Spec Kit: Implement
14 +
15 +Execute tasks while strictly following specifications and constitution.
16 +
17 +## When to Use
18 +
19 +- Tasks are defined
20 +- Ready to write code
21 +- Need to implement a specific task
22 +
23 +## Implementation Process
24 +
25 +1. **Load Context**
26 + - Read relevant specification
27 + - Review constitution constraints
28 + - Check task requirements
29 +
30 +2. **Implement**
31 + - Follow specification exactly
32 + - Apply constitution principles
33 + - No deviation without approval
34 +
35 +3. **Verify**
36 + - Run specified tests
37 + - Check acceptance criteria
38 + - Verify constitution compliance
39 +
40 +4. **Update Status**
41 + - Mark task complete
42 + - Document any notes
43 + - Move to next task
44 +
45 +## Constitution Compliance Check
46 +
47 +Before marking complete:
48 +- [ ] Follows all coding standards
49 +- [ ] Meets quality gates
50 +- [ ] Respects non-negotiables
51 +- [ ] Tests at required coverage
52 +
53 +## Output
54 +
55 +```markdown
56 +## Task Complete: [Task Title]
57 +
58 +**Spec**: [REQ-XXX] satisfied
59 +**Files**: [List of changes]
60 +**Tests**: All passing
61 +
62 +Constitution compliance: Verified
63 +
64 +Next task?
65 +```
skills/frameworks/speckit/speckit-plan/SKILL.md new
+72
@@ -0,0 +1,72 @@
1 +---
2 +name: "speckit-plan"
3 +description: "Generate implementation roadmap from specifications."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["speckit", "planning", "roadmap"]
7 +trigger_patterns:
8 + - "plan implementation"
9 + - "create roadmap"
10 + - "implementation plan"
11 +---
12 +
13 +# Spec Kit: Plan
14 +
15 +Generate an implementation roadmap from approved specifications.
16 +
17 +## When to Use
18 +
19 +- Specifications are approved
20 +- Need to plan development sequence
21 +- Before generating tasks
22 +
23 +## Plan Structure
24 +
25 +Create `PLAN.md`:
26 +
27 +```markdown
28 +# Implementation Plan: [Project Name]
29 +
30 +## Specifications Covered
31 +- [spec-1.md]: [Brief description]
32 +- [spec-2.md]: [Brief description]
33 +
34 +## Implementation Phases
35 +
36 +### Phase 1: [Name]
37 +**Goal**: [What this phase achieves]
38 +**Specs**: [Which specifications]
39 +**Dependencies**: [None/Prior phases]
40 +
41 +### Phase 2: [Name]
42 +...
43 +
44 +## Dependency Graph
45 +```
46 +[Phase 1] → [Phase 2] → [Phase 3]
47 + ↘ [Phase 4]
48 +```
49 +
50 +## Risk Mitigation
51 +| Risk | Phase | Mitigation |
52 +|------|-------|------------|
53 +| [Risk] | [X] | [Strategy] |
54 +
55 +## Success Criteria
56 +- [ ] All specifications implemented
57 +- [ ] All tests pass
58 +- [ ] Constitution compliance verified
59 +```
60 +
61 +## Output
62 +
63 +```markdown
64 +## Plan Created: [Project Name]
65 +
66 +**Phases**: [X]
67 +**Specifications**: [Y] covered
68 +
69 +Plan saved to `PLAN.md`
70 +
71 +Ready to generate tasks? Use `speckit-tasks`.
72 +```
skills/frameworks/speckit/speckit-specify/SKILL.md new
+88
@@ -0,0 +1,88 @@
1 +---
2 +name: "speckit-specify"
3 +description: "Create detailed specifications for features following constitution principles."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["speckit", "specification", "design"]
7 +trigger_patterns:
8 + - "specify"
9 + - "create spec"
10 + - "specification"
11 +---
12 +
13 +# Spec Kit: Specify
14 +
15 +Create detailed, unambiguous specifications following the project constitution.
16 +
17 +## When to Use
18 +
19 +- After constitution is defined
20 +- Before planning implementation
21 +- When feature requirements need detail
22 +
23 +## Specification Structure
24 +
25 +Create `specs/[feature-name].md`:
26 +
27 +```markdown
28 +# Specification: [Feature Name]
29 +
30 +## Summary
31 +[One paragraph description]
32 +
33 +## Constitution Alignment
34 +- Principle: [How this follows principle X]
35 +- Constraints: [Relevant constraints]
36 +
37 +## Requirements
38 +
39 +### Functional
40 +1. [REQ-001] [Clear, testable requirement]
41 +2. [REQ-002] [Clear, testable requirement]
42 +
43 +### Non-Functional
44 +1. [NFR-001] [Performance/security/etc requirement]
45 +
46 +## Interface
47 +
48 +### Inputs
49 +- [Input 1]: [Type, validation, description]
50 +
51 +### Outputs
52 +- [Output 1]: [Type, format, description]
53 +
54 +## Behavior
55 +
56 +### Happy Path
57 +1. [Step 1]
58 +2. [Step 2]
59 +3. [Step 3]
60 +
61 +### Error Cases
62 +| Condition | Behavior |
63 +|-----------|----------|
64 +| [Error 1] | [Response] |
65 +
66 +## Examples
67 +
68 +### Example 1: [Name]
69 +**Input**: [Sample input]
70 +**Output**: [Expected output]
71 +
72 +## Acceptance Criteria
73 +- [ ] [AC-001] [Criterion]
74 +- [ ] [AC-002] [Criterion]
75 +```
76 +
77 +## Output
78 +
79 +```markdown
80 +## Specification Complete: [Feature Name]
81 +
82 +**Requirements**: [X] functional, [Y] non-functional
83 +**Acceptance Criteria**: [Z] items
84 +
85 +Specification saved to `specs/[feature-name].md`
86 +
87 +Ready to plan? Use `speckit-plan`.
88 +```
skills/frameworks/speckit/speckit-tasks/SKILL.md new
+57
@@ -0,0 +1,57 @@
1 +---
2 +name: "speckit-tasks"
3 +description: "Break plan into actionable tasks with clear specifications."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["speckit", "tasks", "breakdown"]
7 +trigger_patterns:
8 + - "create tasks"
9 + - "break down"
10 + - "generate tasks"
11 +---
12 +
13 +# Spec Kit: Tasks
14 +
15 +Break the implementation plan into specific, actionable tasks.
16 +
17 +## When to Use
18 +
19 +- Plan is approved
20 +- Ready to start implementation
21 +- Need discrete work items
22 +
23 +## Task Format
24 +
25 +Create `TASKS.md`:
26 +
27 +```markdown
28 +# Tasks: [Phase Name]
29 +
30 +## Task 1: [Title]
31 +**Spec Reference**: [REQ-XXX]
32 +**Status**: [ ] Not Started
33 +**Files**:
34 +- Create: `path/to/new.py`
35 +- Modify: `path/to/existing.py`
36 +**Steps**:
37 +1. [Specific step]
38 +2. [Specific step]
39 +**Verification**: [How to verify complete]
40 +
41 +## Task 2: [Title]
42 +...
43 +```
44 +
45 +## Output
46 +
47 +```markdown
48 +## Tasks Generated: [Phase Name]
49 +
50 +**Total Tasks**: [X]
51 +**Ready to Start**: [Y]
52 +**Blocked**: [Z]
53 +
54 +Tasks saved to `TASKS.md`
55 +
56 +Ready to implement? Use `speckit-implement`.
57 +```
skills/frameworks/superpowers/sp-brainstorming/SKILL.md new
+113
@@ -0,0 +1,113 @@
1 +---
2 +name: "sp-brainstorming"
3 +description: "Structured brainstorming for requirements exploration before implementation."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["superpowers", "planning", "design", "requirements"]
7 +trigger_patterns:
8 + - "brainstorm"
9 + - "explore options"
10 + - "design"
11 + - "think through"
12 +---
13 +
14 +# Superpowers: Brainstorming
15 +
16 +Use this skill BEFORE any implementation to explore requirements and design options.
17 +
18 +## When to Use
19 +
20 +- User requests a new feature
21 +- Starting creative work
22 +- Multiple implementation approaches possible
23 +- Requirements are unclear
24 +
25 +## Brainstorming Process
26 +
27 +### Phase 1: Understanding Intent (Ask 3-5 Questions)
28 +
29 +Focus questions on:
30 +1. **Goal Clarity**: What specific outcome do you want?
31 +2. **Context**: What existing code/systems does this interact with?
32 +3. **Constraints**: Performance, security, compatibility requirements?
33 +4. **Edge Cases**: What happens in failure scenarios?
34 +5. **Success Criteria**: How will we know it's working?
35 +
36 +### Phase 2: Explore the Codebase
37 +
38 +Before proposing solutions:
39 +- Read relevant existing files
40 +- Identify established patterns
41 +- Note integration points
42 +- Check for similar implementations
43 +
44 +### Phase 3: Design Options
45 +
46 +Present 2-3 approaches with trade-offs:
47 +
48 +```markdown
49 +## Option A: [Name]
50 +**Approach**: Brief description
51 +**Pros**: List benefits
52 +**Cons**: List drawbacks
53 +**Best for**: When to choose this
54 +
55 +## Option B: [Name]
56 +**Approach**: Brief description
57 +**Pros**: List benefits
58 +**Cons**: List drawbacks
59 +**Best for**: When to choose this
60 +```
61 +
62 +### Phase 4: Technical Specification
63 +
64 +Once approach is chosen, document:
65 +
66 +1. **Files to Create/Modify**: List with descriptions
67 +2. **Dependencies**: External packages or internal modules
68 +3. **Data Flow**: How data moves through the system
69 +4. **API Contracts**: Input/output specifications
70 +5. **Test Strategy**: How this will be tested
71 +
72 +### Phase 5: Implementation Plan
73 +
74 +Break down into ordered tasks:
75 +
76 +```markdown
77 +## Implementation Tasks
78 +1. [ ] Task 1 - Description
79 +2. [ ] Task 2 - Description (depends on 1)
80 +3. [ ] Task 3 - Description
81 +4. [ ] Task 4 - Integration testing
82 +```
83 +
84 +## Output Format
85 +
86 +After brainstorming:
87 +
88 +```markdown
89 +## Summary: [Feature Name]
90 +
91 +### Chosen Approach
92 +[Brief description of selected approach]
93 +
94 +### Key Decisions
95 +- Decision 1: Rationale
96 +- Decision 2: Rationale
97 +
98 +### Implementation Tasks
99 +1. Task 1
100 +2. Task 2
101 +3. Task 3
102 +
103 +### Ready to Plan
104 +Confirm with user before proceeding to `sp-writing-plans`.
105 +```
106 +
107 +## Anti-Patterns
108 +
109 +- Jumping to code without understanding requirements
110 +- Single solution bias (always consider alternatives)
111 +- Ignoring existing codebase patterns
112 +- Over-engineering simple problems
113 +- Under-specifying complex requirements
skills/frameworks/superpowers/sp-code-review/SKILL.md new
+121
@@ -0,0 +1,121 @@
1 +---
2 +name: "sp-code-review"
3 +description: "Review implementation against plan, report issues by severity."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["superpowers", "review", "quality", "verification"]
7 +trigger_patterns:
8 + - "code review"
9 + - "review code"
10 + - "check implementation"
11 +---
12 +
13 +# Superpowers: Code Review
14 +
15 +Review implementation against the plan with severity-based reporting.
16 +
17 +## When to Use
18 +
19 +- After completing a task or set of tasks
20 +- Before merging a feature branch
21 +- Between implementation phases
22 +- When requesting external review
23 +
24 +## Review Process
25 +
26 +### 1. Gather Context
27 +
28 +- Load the relevant plan(s)
29 +- Identify expected deliverables
30 +- Note any constraints or requirements
31 +
32 +### 2. Systematic Review
33 +
34 +Check each category:
35 +
36 +| Category | What to Check |
37 +|----------|---------------|
38 +| **Plan Compliance** | Does the code match the plan? |
39 +| **Test Coverage** | Are all requirements tested? |
40 +| **Code Quality** | Is it readable and maintainable? |
41 +| **Error Handling** | Are edge cases covered? |
42 +| **Security** | Any vulnerabilities introduced? |
43 +| **Performance** | Any obvious bottlenecks? |
44 +
45 +### 3. Issue Classification
46 +
47 +Classify findings by severity:
48 +
49 +```markdown
50 +## Review Findings
51 +
52 +### 🔴 CRITICAL (Blocks merge)
53 +- [Issue description]
54 +- [Location: file:line]
55 +- [Suggested fix]
56 +
57 +### 🟡 IMPORTANT (Should fix)
58 +- [Issue description]
59 +- [Location: file:line]
60 +- [Suggested fix]
61 +
62 +### 🟢 MINOR (Nice to have)
63 +- [Issue description]
64 +- [Location: file:line]
65 +- [Suggested fix]
66 +
67 +### ℹ️ OBSERVATIONS (No action needed)
68 +- [Note or observation]
69 +```
70 +
71 +## Severity Guidelines
72 +
73 +### 🔴 CRITICAL
74 +- Security vulnerabilities
75 +- Data loss potential
76 +- Crashes or errors in happy path
77 +- Missing required functionality
78 +- **Action**: MUST fix before merge
79 +
80 +### 🟡 IMPORTANT
81 +- Missing edge case handling
82 +- Performance issues
83 +- Code that will be hard to maintain
84 +- Missing tests for key paths
85 +- **Action**: Should fix, discuss if blocking
86 +
87 +### 🟢 MINOR
88 +- Style inconsistencies
89 +- Minor optimization opportunities
90 +- Documentation gaps
91 +- **Action**: Fix if time permits
92 +
93 +## Review Checklist
94 +
95 +```markdown
96 +## Pre-Merge Checklist
97 +
98 +- [ ] All critical issues resolved
99 +- [ ] Important issues addressed or tracked
100 +- [ ] Tests pass
101 +- [ ] No linting errors
102 +- [ ] Documentation updated if needed
103 +- [ ] Commit messages are clear
104 +```
105 +
106 +## Integration with Superpowers Workflow
107 +
108 +1. **Brainstorming** → Design
109 +2. **Git Worktrees** → Workspace
110 +3. **Writing Plans** → Tasks
111 +4. **TDD** → Implementation
112 +5. **Code Review** → Quality check ← YOU ARE HERE
113 +6. **Finishing Branch** → Merge
114 +
115 +## Best Practices
116 +
117 +- Review in small chunks (one task at a time when possible)
118 +- Focus on the plan—does the code deliver what was planned?
119 +- Be specific: include file names and line numbers
120 +- Suggest fixes, don't just identify problems
121 +- Critical issues block; everything else is negotiable
skills/frameworks/superpowers/sp-executing-plans/SKILL.md new
+164
@@ -0,0 +1,164 @@
1 +---
2 +name: "sp-executing-plans"
3 +description: "Systematically implement plan steps with verification at each stage."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["superpowers", "implementation", "execution"]
7 +trigger_patterns:
8 + - "execute plan"
9 + - "implement plan"
10 + - "start building"
11 + - "follow plan"
12 +---
13 +
14 +# Superpowers: Executing Plans
15 +
16 +Systematically work through a plan, verifying each step before proceeding.
17 +
18 +## When to Use
19 +
20 +- Plan has been created and approved
21 +- User is ready to start implementation
22 +- Need to resume work on an existing plan
23 +
24 +## Execution Flow
25 +
26 +```
27 +Load Plan → Start Step → Implement → Verify → Update Status → Next Step
28 +```
29 +
30 +## Execution Process
31 +
32 +### 1. Load and Display Plan
33 +
34 +```markdown
35 +## Executing: [Feature Name]
36 +
37 +**Plan**: [path/to/plan.md]
38 +**Progress**: [X]/[Total] steps complete
39 +
40 +### Remaining Steps:
41 +- Step [N]: [Title]
42 +- Step [N+1]: [Title]
43 +...
44 +
45 +Starting Step [N]...
46 +```
47 +
48 +### 2. Execute Each Step
49 +
50 +For each step:
51 +
52 +#### a) Announce Intent
53 +```markdown
54 +### Step [N]: [Title]
55 +**Goal**: [What this achieves]
56 +**Starting...**
57 +```
58 +
59 +#### b) Implement Changes
60 +- Make the code changes
61 +- Follow existing patterns
62 +- Add tests if specified
63 +
64 +#### c) Verify
65 +- Run specified verification
66 +- Check for regressions
67 +- Confirm goal is met
68 +
69 +#### d) Report Completion
70 +```markdown
71 +**Step [N] Complete**
72 +- Modified: `file1.py`, `file2.py`
73 +- Tests: Passing
74 +- Verification: [How verified]
75 +
76 +Proceeding to Step [N+1]...
77 +```
78 +
79 +### 3. Handle Deviations
80 +
81 +When plan needs adjustment:
82 +
83 +```markdown
84 +### Plan Deviation Needed
85 +
86 +**Step**: [N]
87 +**Issue**: [What was discovered]
88 +**Impact**: [How this affects the plan]
89 +
90 +**Options**:
91 +A) [Adjustment option]
92 +B) [Alternative option]
93 +
94 +How would you like to proceed?
95 +```
96 +
97 +Wait for user input before continuing.
98 +
99 +### 4. Progress Checkpoints
100 +
101 +Every 2-3 steps or at natural breaks:
102 +
103 +```markdown
104 +## Checkpoint
105 +
106 +**Progress**: [X]/[Total] steps
107 +**Completed**:
108 +- Step 1: [Title]
109 +- Step 2: [Title]
110 +
111 +**Status**: On track / Adjustments made
112 +
113 +Continue with remaining steps?
114 +```
115 +
116 +### 5. Handle Failures
117 +
118 +If a step fails:
119 +
120 +```markdown
121 +### Step [N] Failed
122 +
123 +**Error**: [What went wrong]
124 +**Attempted**: [What was tried]
125 +
126 +**Options**:
127 +1. Debug and fix
128 +2. Skip step (with consequences)
129 +3. Revise plan
130 +
131 +How would you like to proceed?
132 +```
133 +
134 +### 6. Completion
135 +
136 +```markdown
137 +## Execution Complete: [Feature Name]
138 +
139 +**Steps**: [Total]/[Total] complete
140 +**Files created**: [count]
141 +**Files modified**: [count]
142 +**Tests**: [status]
143 +
144 +### Summary of Changes
145 +- `file1.py`: [what changed]
146 +- `file2.py`: [what changed]
147 +
148 +Ready for final review? Use `sp-finishing-branch` to wrap up.
149 +```
150 +
151 +## Best Practices
152 +
153 +- **Small commits**: Commit after each step or logical group
154 +- **Run tests frequently**: Don't let failures accumulate
155 +- **Stay focused**: Only implement what's in the plan
156 +- **Document deviations**: Note any changes to the plan
157 +
158 +## Anti-Patterns
159 +
160 +- Skipping verification
161 +- Making unplanned changes
162 +- Continuing past failures without resolving
163 +- Large commits with multiple steps
164 +- Not updating plan with actual changes
skills/frameworks/superpowers/sp-finishing-branch/SKILL.md new
+172
@@ -0,0 +1,172 @@
1 +---
2 +name: "sp-finishing-branch"
3 +description: "Complete development branch with proper git workflow, review, and merge preparation."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["superpowers", "git", "review", "completion"]
7 +trigger_patterns:
8 + - "finish branch"
9 + - "wrap up"
10 + - "prepare for merge"
11 + - "create pr"
12 +---
13 +
14 +# Superpowers: Finishing Branch
15 +
16 +Complete a development branch with proper verification, documentation, and git workflow.
17 +
18 +## When to Use
19 +
20 +- Implementation is complete
21 +- Ready to merge or create PR
22 +- Need to clean up before submission
23 +
24 +## Finishing Checklist
25 +
26 +### 1. Verify All Tests Pass
27 +
28 +```bash
29 +# Run full test suite
30 +pytest tests/
31 +# or npm test, cargo test, etc.
32 +```
33 +
34 +```markdown
35 +## Test Results
36 +**Total**: [X] tests
37 +**Passed**: [X]
38 +**Failed**: 0
39 +**Coverage**: [X]%
40 +
41 +All tests passing.
42 +```
43 +
44 +### 2. Code Quality Check
45 +
46 +- [ ] No linting errors
47 +- [ ] No type errors (if applicable)
48 +- [ ] No debug code left in
49 +- [ ] No hardcoded values that should be config
50 +- [ ] Error handling is present
51 +- [ ] No security issues
52 +
53 +### 3. Documentation Review
54 +
55 +- [ ] README updated if needed
56 +- [ ] API documentation current
57 +- [ ] Comments explain non-obvious code
58 +- [ ] CHANGELOG updated
59 +
60 +### 4. Clean Git History
61 +
62 +Review commits:
63 +```bash
64 +git log --oneline -10
65 +```
66 +
67 +Ensure commits are:
68 +- [ ] Logical and atomic
69 +- [ ] Well-described
70 +- [ ] No WIP or temp commits
71 +
72 +### 5. Create/Update PR Description
73 +
74 +```markdown
75 +## Summary
76 +[1-3 sentence description of changes]
77 +
78 +## Changes
79 +- [Change 1]
80 +- [Change 2]
81 +- [Change 3]
82 +
83 +## Testing
84 +- [How this was tested]
85 +- [What to test during review]
86 +
87 +## Screenshots (if applicable)
88 +[Add screenshots for UI changes]
89 +
90 +## Checklist
91 +- [ ] Tests pass
92 +- [ ] Documentation updated
93 +- [ ] No breaking changes (or noted below)
94 +```
95 +
96 +### 6. Final Verification
97 +
98 +```markdown
99 +## Pre-Merge Checklist
100 +
101 +**Branch**: [branch-name]
102 +**Target**: [main/develop]
103 +
104 +### Automated Checks
105 +- [ ] All tests pass
106 +- [ ] Linting passes
107 +- [ ] Build succeeds
108 +
109 +### Manual Verification
110 +- [ ] Feature works as expected
111 +- [ ] Edge cases handled
112 +- [ ] No regressions in related features
113 +
114 +### Documentation
115 +- [ ] README current
116 +- [ ] API docs updated
117 +- [ ] Inline comments adequate
118 +
119 +### Git
120 +- [ ] Commits are clean
121 +- [ ] No merge conflicts
122 +- [ ] Branch is up to date with target
123 +```
124 +
125 +## Output
126 +
127 +After finishing process:
128 +
129 +```markdown
130 +## Branch Ready: [branch-name]
131 +
132 +**Status**: Ready for review/merge
133 +**Tests**: All passing
134 +**Commits**: [X] clean commits
135 +
136 +### Summary of Changes
137 +- [Main change 1]
138 +- [Main change 2]
139 +
140 +### PR/MR Ready
141 +[Link or instructions to create]
142 +
143 +What's next?
144 +- Create pull request
145 +- Request review
146 +- Merge (if self-merge allowed)
147 +```
148 +
149 +## Git Commands Reference
150 +
151 +```bash
152 +# Update branch with latest target
153 +git fetch origin
154 +git rebase origin/main
155 +
156 +# Interactive rebase to clean commits
157 +git rebase -i origin/main
158 +
159 +# Push (force if rebased)
160 +git push --force-with-lease
161 +
162 +# Create PR via CLI (GitHub)
163 +gh pr create --title "Feature: X" --body "..."
164 +```
165 +
166 +## Anti-Patterns
167 +
168 +- Merging with failing tests
169 +- Skipping code review
170 +- Poor commit messages
171 +- Leaving TODO comments
172 +- Not updating documentation
skills/frameworks/superpowers/sp-git-worktrees/SKILL.md new
+112
@@ -0,0 +1,112 @@
1 +---
2 +name: "sp-git-worktrees"
3 +description: "Create isolated workspace on new branch for parallel development."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["superpowers", "git", "worktree", "branching"]
7 +trigger_patterns:
8 + - "git worktree"
9 + - "create worktree"
10 + - "isolated workspace"
11 + - "parallel development"
12 +---
13 +
14 +# Superpowers: Git Worktrees
15 +
16 +Create isolated workspaces for parallel development without stashing or switching branches.
17 +
18 +## When to Use
19 +
20 +- After design approval, before implementation
21 +- When you need to work on multiple features simultaneously
22 +- When you want a clean environment for a new feature
23 +
24 +## What Git Worktrees Provide
25 +
26 +- **Isolation**: Each worktree has its own working directory
27 +- **Parallel work**: Multiple features can be developed simultaneously
28 +- **Clean baseline**: Start fresh without uncommitted changes
29 +- **Easy cleanup**: Remove worktree when done, branch remains
30 +
31 +## Process
32 +
33 +### 1. Create Worktree
34 +
35 +```bash
36 +# From your main repository
37 +git worktree add ../feature-name feature-branch-name
38 +```
39 +
40 +Or create worktree with new branch:
41 +```bash
42 +git worktree add -b feature-branch-name ../feature-name
43 +```
44 +
45 +### 2. Navigate to Worktree
46 +
47 +```bash
48 +cd ../feature-name
49 +```
50 +
51 +### 3. Verify Setup
52 +
53 +```bash
54 +# Check you're on the right branch
55 +git branch
56 +
57 +# Run project setup (if needed)
58 +npm install # or equivalent
59 +```
60 +
61 +### 4. Verify Test Baseline
62 +
63 +Before any changes, ensure tests pass:
64 +
65 +```bash
66 +# Run test suite
67 +npm test # or equivalent
68 +
69 +# All tests should be green before you start
70 +```
71 +
72 +## Worktree Management
73 +
74 +### List Worktrees
75 +```bash
76 +git worktree list
77 +```
78 +
79 +### Remove Worktree
80 +```bash
81 +git worktree remove ../feature-name
82 +```
83 +
84 +### Prune Stale Worktrees
85 +```bash
86 +git worktree prune
87 +```
88 +
89 +## Best Practices
90 +
91 +1. **Naming convention**: Use descriptive names matching branch purpose
92 +2. **Location**: Keep worktrees in sibling directories
93 +3. **Cleanup**: Remove worktrees after merging
94 +4. **Test baseline**: Always verify tests pass before starting work
95 +
96 +## Directory Structure Example
97 +
98 +```
99 +~/projects/
100 +├── my-project/ # Main repo
101 +├── my-project-feature-a/ # Worktree for feature A
102 +├── my-project-feature-b/ # Worktree for feature B
103 +└── my-project-hotfix/ # Worktree for hotfix
104 +```
105 +
106 +## Integration with Superpowers Workflow
107 +
108 +1. **Brainstorming** → Design approved
109 +2. **Git Worktrees** → Create isolated workspace ← YOU ARE HERE
110 +3. **Writing Plans** → Plan implementation
111 +4. **Executing Plans** → Build feature
112 +5. **Finishing Branch** → Merge and cleanup worktree
skills/frameworks/superpowers/sp-test-driven-development/SKILL.md new
+110
@@ -0,0 +1,110 @@
1 +---
2 +name: "sp-test-driven-development"
3 +description: "RED-GREEN-REFACTOR cycle: write failing test, minimal code, commit."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["superpowers", "tdd", "testing", "development"]
7 +trigger_patterns:
8 + - "test driven"
9 + - "tdd"
10 + - "red green refactor"
11 + - "test first"
12 +---
13 +
14 +# Superpowers: Test-Driven Development
15 +
16 +Enforce strict RED-GREEN-REFACTOR discipline for reliable code.
17 +
18 +## The TDD Cycle
19 +
20 +```
21 +┌─────────┐ ┌─────────┐ ┌──────────┐
22 +│ RED │ ──▶ │ GREEN │ ──▶ │ REFACTOR │
23 +│ (fail) │ │ (pass) │ │ (clean) │
24 +└─────────┘ └─────────┘ └──────────┘
25 + ▲ │
26 + └───────────────────────────────┘
27 +```
28 +
29 +## The Rules
30 +
31 +### 1. RED: Write a Failing Test First
32 +
33 +- Write the test BEFORE any implementation
34 +- The test MUST fail initially
35 +- Failure confirms the test is testing something real
36 +
37 +```bash
38 +# Run test - expect failure
39 +npm test -- --grep "should validate email"
40 +# FAIL ✗
41 +```
42 +
43 +### 2. GREEN: Write Minimal Code to Pass
44 +
45 +- Write ONLY enough code to make the test pass
46 +- No extra features, no "while I'm here" additions
47 +- Resist the urge to generalize
48 +
49 +```bash
50 +# Run test - expect success
51 +npm test -- --grep "should validate email"
52 +# PASS ✓
53 +```
54 +
55 +### 3. REFACTOR: Clean Up (Tests Stay Green)
56 +
57 +- Improve code quality without changing behavior
58 +- Tests must remain passing
59 +- Commit after each successful refactor
60 +
61 +```bash
62 +# Run all tests - all must pass
63 +npm test
64 +# All PASS ✓
65 +```
66 +
67 +### 4. COMMIT: After Each Cycle
68 +
69 +- One commit per RED-GREEN-REFACTOR cycle
70 +- Clear commit message describing the test case
71 +
72 +## Anti-Patterns to Avoid
73 +
74 +| Anti-Pattern | Why It's Bad |
75 +|-------------|--------------|
76 +| Writing code before tests | No proof code works |
77 +| Writing multiple tests at once | Too much change, hard to debug |
78 +| Making tests pass with hacks | Technical debt accumulates |
79 +| Skipping refactor step | Code quality degrades |
80 +| Testing implementation details | Tests become brittle |
81 +
82 +## Test Quality Checklist
83 +
84 +- [ ] Test describes behavior, not implementation
85 +- [ ] Test has clear arrange-act-assert structure
86 +- [ ] Test fails for the right reason initially
87 +- [ ] Test name explains what it verifies
88 +- [ ] Test is independent (no shared state)
89 +
90 +## Integration with Superpowers Workflow
91 +
92 +1. **Brainstorming** → Design approved
93 +2. **Git Worktrees** → Isolated workspace
94 +3. **Writing Plans** → Tasks defined
95 +4. **TDD** → For each task: RED → GREEN → REFACTOR ← YOU ARE HERE
96 +5. **Code Review** → Review implementation
97 +6. **Finishing Branch** → Merge
98 +
99 +## The Discipline
100 +
101 +**DELETE code written before tests.**
102 +
103 +If you find yourself writing implementation before the test:
104 +1. Stop immediately
105 +2. Delete the implementation
106 +3. Write the test first
107 +4. Watch it fail
108 +5. THEN write the code
109 +
110 +This is not negotiable. The discipline IS the value.
skills/frameworks/superpowers/sp-writing-plans/SKILL.md new
+140
@@ -0,0 +1,140 @@
1 +---
2 +name: "sp-writing-plans"
3 +description: "Create detailed implementation plans with clear steps and verification criteria."
4 +version: "1.0.0"
5 +author: "Agent Zero Team"
6 +tags: ["superpowers", "planning", "documentation"]
7 +trigger_patterns:
8 + - "write plan"
9 + - "create plan"
10 + - "make plan"
11 + - "planning"
12 +---
13 +
14 +# Superpowers: Writing Plans
15 +
16 +Create a detailed, actionable implementation plan after brainstorming.
17 +
18 +## When to Use
19 +
20 +- After completing brainstorming phase
21 +- User has selected an approach
22 +- Ready to formalize the implementation strategy
23 +
24 +## Plan Document Structure
25 +
26 +Create a plan file (e.g., `PLAN.md` or `.plan/current.md`):
27 +
28 +```markdown
29 +# Implementation Plan: [Feature Name]
30 +
31 +## Context
32 +[Brief background and why this is being built]
33 +
34 +## Objective
35 +[Clear, measurable goal statement]
36 +
37 +## Approach
38 +[Selected approach from brainstorming with rationale]
39 +
40 +## Steps
41 +
42 +### Step 1: [Title]
43 +**Goal**: What this step achieves
44 +**Actions**:
45 +- Specific action 1
46 +- Specific action 2
47 +**Verification**: How to confirm step is complete
48 +**Files**: Files to create/modify
49 +
50 +### Step 2: [Title]
51 +...
52 +
53 +## Test Plan
54 +- [ ] Unit tests for X
55 +- [ ] Integration tests for Y
56 +- [ ] Manual verification of Z
57 +
58 +## Acceptance Criteria
59 +- [ ] Criterion 1
60 +- [ ] Criterion 2
61 +- [ ] All tests pass
62 +- [ ] No regressions
63 +
64 +## Dependencies
65 +- [List external dependencies]
66 +
67 +## Risks
68 +- [Potential issues and mitigations]
69 +```
70 +
71 +## Plan Writing Guidelines
72 +
73 +### Steps Should Be
74 +
75 +1. **Atomic**: One clear action per step
76 +2. **Verifiable**: Has a way to confirm completion
77 +3. **Ordered**: Dependencies are clear
78 +4. **Scoped**: Not too large, not too small
79 +
80 +### Each Step Includes
81 +
82 +- Clear goal statement
83 +- Specific file changes
84 +- Verification method
85 +- Estimated size (small/medium/large)
86 +
87 +### Good Step Example
88 +
89 +```markdown
90 +### Step 3: Add validation to user input
91 +**Goal**: Ensure email addresses are valid format
92 +**Actions**:
93 +- Create `validators/email.py` with email regex
94 +- Import validator in `forms/user_form.py`
95 +- Add validation call in `handle_submit()`
96 +**Verification**:
97 +- Unit test with valid/invalid emails
98 +- Form rejects "notanemail" input
99 +**Files**: `validators/email.py`, `forms/user_form.py`
100 +```
101 +
102 +### Bad Step Example
103 +
104 +```markdown
105 +### Step 3: Implement validation
106 +- Add validation
107 +```
108 +
109 +## Plan Review Checklist
110 +
111 +Before finalizing:
112 +- [ ] Each step has a clear goal
113 +- [ ] Dependencies between steps are noted
114 +- [ ] Test plan covers main scenarios
115 +- [ ] Acceptance criteria are measurable
116 +- [ ] No steps are too large (break down if needed)
117 +
118 +## Output
119 +
120 +After plan is written:
121 +
122 +```markdown
123 +## Plan Complete: [Feature Name]
124 +
125 +**Steps**: [X] implementation steps
126 +**Test cases**: [Y] planned
127 +**Files affected**: [Z] files
128 +
129 +Plan saved to `[path]`
130 +
131 +Ready to execute? Use `sp-executing-plans` to begin.
132 +```
133 +
134 +## Anti-Patterns
135 +
136 +- Steps that are too vague
137 +- Missing verification criteria
138 +- Forgetting test planning
139 +- Plans that can't be followed by someone else
140 +- Overly rigid plans (leave room for discovery)
skills/shared/.gitkeep renamed
skills/shared/claude-code-skill-factory-dev/generated-skills/prompt-factory/outputs/.gitkeep renamed
webui/components/modals/memory/memory-dashboard-store.js
+1 -1
@@ -508,7 +508,7 @@ ${memory.content_full}
508 main: "#3b82f6",
509 fragments: "#10b981",
510 solutions: "#8b5cf6",
511 - instruments: "#f59e0b",
511 + skills: "#f59e0b",
512 };
513 return colors[area] || "#6c757d";
514 },
webui/components/modals/memory/memory-dashboard.html
+1 -1
@@ -35,7 +35,7 @@
35 <option value="main">Main</option>
36 <option value="fragments">Fragments</option>
37 <option value="solutions">Solutions</option>
38 - <option value="instruments">Instruments</option>
38 + <option value="skills">Skills</option>
39 </select>
40 </div>
41
webui/components/projects/project-edit-basic-data.html
+20 -2
@@ -58,6 +58,18 @@
58 </template>
59 </div>
60 </div>
61 +
62 + <div class="projects-form-group">
63 + <label class="projects-form-label">Development Framework</label>
64 + <span class="projects-form-description">Override the global development framework for this project.
65 + Framework skills will be prioritized when working on this project.</span>
66 + <select class="projects-form-select" x-model="$store.projects.selectedProject.dev_framework">
67 + <template x-for="option in $store.projects.frameworkOptions" :key="option.value">
68 + <option :value="option.value" x-text="option.label"
69 + :selected="option.value === ($store.projects.selectedProject.dev_framework || '')"></option>
70 + </template>
71 + </select>
72 + </div>
73 </div>
74
75
@@ -92,7 +104,8 @@
104 }
105
106 .projects-form-input,
95 - .projects-form-textarea {
107 + .projects-form-textarea,
108 + .projects-form-select {
109 background: var(--color-input);
110 color: var(--color-text);
111 border: 1px solid var(--color-border);
@@ -102,11 +115,16 @@
115 }
116
117 .projects-form-input:focus,
105 - .projects-form-textarea:focus {
118 + .projects-form-textarea:focus,
119 + .projects-form-select:focus {
120 border-color: var(--color-primary);
121 background: var(--color-input-focus);
122 }
123
124 + .projects-form-select {
125 + cursor: pointer;
126 + }
127 +
128 .projects-color-row {
129 display: flex;
130 gap: 0.5em;
webui/components/projects/project-edit-skills.html new
+92
@@ -0,0 +1,92 @@
1 +<html>
2 +<head>
3 + <title>Project Skills</title>
4 + <script type="module">
5 + import { store } from "/components/projects/projects-store.js";
6 + import { store as skillsStore } from "/components/settings/skills/skills-import-store.js";
7 + </script>
8 +</head>
9 +<body>
10 + <div x-data="{
11 + openSkillsImport() {
12 + // Pre-configure the skills import for this project
13 + if ($store.skillsImportStore) {
14 + $store.skillsImportStore.dest = 'project';
15 + $store.skillsImportStore.projectName = $store.projects.selectedProject.name;
16 + }
17 + openModal('settings/skills/import.html');
18 + }
19 + }">
20 + <template x-if="$store.projects && $store.projects.selectedProject">
21 + <div class="project-skills-section">
22 + <p class="skills-description">
23 + Import skills specific to this project. Project skills are stored in the project's
24 + <code>.a0proj/skills/</code> folder and are only available when this project is active.
25 + </p>
26 +
27 + <div class="skills-actions">
28 + <button type="button" class="button" @click="openSkillsImport()">
29 + Import Skills
30 + </button>
31 + </div>
32 +
33 + <div class="skills-info">
34 + <p>
35 + <strong>Project Skills Location:</strong><br>
36 + <code x-text="'usr/projects/' + $store.projects.selectedProject.name + '/.a0proj/skills/'"></code>
37 + </p>
38 + <p class="skills-note">
39 + Use the global Settings &gt; Skills tab for shared skills available to all projects.
40 + </p>
41 + </div>
42 + </div>
43 + </template>
44 + </div>
45 +
46 + <style>
47 + .project-skills-section {
48 + display: flex;
49 + flex-direction: column;
50 + gap: 1rem;
51 + }
52 +
53 + .skills-description {
54 + color: var(--color-text-secondary);
55 + font-size: 0.9rem;
56 + margin: 0;
57 + }
58 +
59 + .skills-actions {
60 + display: flex;
61 + gap: 0.5rem;
62 + }
63 +
64 + .skills-info {
65 + background: var(--color-bg-secondary);
66 + padding: 0.75rem;
67 + border-radius: 4px;
68 + font-size: 0.85rem;
69 + }
70 +
71 + .skills-info p {
72 + margin: 0 0 0.5rem 0;
73 + }
74 +
75 + .skills-info p:last-child {
76 + margin-bottom: 0;
77 + }
78 +
79 + .skills-note {
80 + color: var(--color-text-secondary);
81 + font-style: italic;
82 + }
83 +
84 + .skills-info code {
85 + background: var(--color-bg-tertiary);
86 + padding: 0.1rem 0.3rem;
87 + border-radius: 3px;
88 + font-size: 0.85em;
89 + }
90 + </style>
91 +</body>
92 +</html>
webui/components/projects/project-edit.html
+8
@@ -66,6 +66,14 @@
66 </x-component>
67 </div>
68
69 + <div class="project-detail">
70 + <div class="project-detail-header">
71 + <span class="projects-project-card-title">Skills</span>
72 + </div>
73 + <x-component path="projects/project-edit-skills.html">
74 + </x-component>
75 + </div>
76 +
77 <div class="buttons-container" style="margin: var(--spacing-md) var(--spacing-sm) var(--spacing-lg) var(--spacing-sm);">
78 <div class="buttons-left">
79 <button type="button" class="button cancel"
webui/components/projects/projects-store.js
+23
@@ -15,6 +15,7 @@ const model = {
15 projectList: [],
16 selectedProject: null,
17 editData: null,
18 + frameworkOptions: [],
19 colors: [
20 "#7b2cbf", // Deep Purple
21 "#8338ec", // Blue Violet
@@ -71,16 +72,37 @@ const model = {
72
73 async openCreateModal() {
74 this.selectedProject = this._createNewProjectData();
75 + await this.loadFrameworkOptions();
76 await modals.openModal(createModal);
77 this.selectedProject = null;
78 },
79
80 async openEditModal(name) {
81 this.selectedProject = await this._createEditProjectData(name);
82 + await this.loadFrameworkOptions();
83 await modals.openModal(editModal);
84 this.selectedProject = null;
85 },
86
87 + async loadFrameworkOptions() {
88 + try {
89 + const response = await api.callJsonApi("frameworks", { action: "list" });
90 + if (response?.ok && response?.data) {
91 + // Add "Use Global Setting" option at the top
92 + this.frameworkOptions = [
93 + { value: "", label: "Use Global Setting" },
94 + ...response.data.map(fw => ({ value: fw.id, label: fw.name }))
95 + ];
96 + } else {
97 + // Fallback if API fails
98 + this.frameworkOptions = [{ value: "", label: "Use Global Setting" }];
99 + }
100 + } catch (error) {
101 + console.error("Error loading framework options:", error);
102 + this.frameworkOptions = [{ value: "", label: "Use Global Setting" }];
103 + }
104 + },
105 +
106 async cancelCreate() {
107 await modals.closeModal(createModal);
108 },
@@ -308,6 +330,7 @@ const model = {
330 title: `Project #${this.projectList.length + 1}`,
331 description: "",
332 color: "",
333 + dev_framework: "",
334 };
335 },
336
webui/components/settings/agent/agent-settings.html
+10
@@ -15,6 +15,12 @@
15 <span>Agent Config</span>
16 </a>
17 </li>
18 + <li>
19 + <a href="#section-framework">
20 + <img src="/public/framework.svg" alt="Framework" />
21 + <span>Development Framework</span>
22 + </a>
23 + </li>
24 <li>
25 <a href="#section-chat-model">
26 <img src="/public/chat_model.svg" alt="Chat Model" />
@@ -58,6 +64,10 @@
64 <x-component path="settings/agent/agent.html"></x-component>
65 </div>
66
67 + <div id="section-framework" class="section">
68 + <x-component path="settings/agent/framework.html"></x-component>
69 + </div>
70 +
71 <div id="section-chat-model" class="section">
72 <x-component path="settings/agent/chat_model.html"></x-component>
73 </div>
webui/components/settings/agent/framework.html new
+49
@@ -0,0 +1,49 @@
1 +<html>
2 + <head>
3 + <title>Development Framework</title>
4 + </head>
5 +
6 + <body>
7 + <div x-data>
8 + <template x-if="$store.settingsStore.settings">
9 + <div>
10 + <div class="section-title">Development Framework</div>
11 + <div class="section-description">
12 + Choose a structured development workflow methodology to guide the agent.
13 + </div>
14 +
15 + <div class="field">
16 + <div class="field-label">
17 + <div class="field-title">Active Framework</div>
18 + <div class="field-description">
19 + Select a development methodology. When active, framework-specific skills are prioritized
20 + and workflow guidance is injected into the system prompt.
21 + </div>
22 + </div>
23 + <div class="field-control">
24 + <select x-model="$store.settingsStore.settings.dev_framework">
25 + <template x-for="option in $store.settingsStore.additional?.framework_options" :key="option.value">
26 + <option :value="option.value" :selected="option.value === $store.settingsStore.settings.dev_framework" x-text="option.label"></option>
27 + </template>
28 + </select>
29 + </div>
30 + </div>
31 +
32 + <div class="field">
33 + <div class="field-label">
34 + <div class="field-title">Framework Details</div>
35 + <div class="field-description">
36 + View detailed information about the selected framework and its workflow steps.
37 + </div>
38 + </div>
39 + <div class="field-control">
40 + <button class="btn btn-field" @click="$store.settingsStore.handleFieldButton({id: 'framework_info'})">
41 + View Details
42 + </button>
43 + </div>
44 + </div>
45 + </div>
46 + </template>
47 + </div>
48 + </body>
49 +</html>
webui/components/settings/frameworks/framework-details.html new
+273
@@ -0,0 +1,273 @@
1 +<html>
2 +<head>
3 + <title>Development Framework Details</title>
4 + <script type="module">
5 + import { store } from "/components/settings/frameworks/framework-store.js";
6 + </script>
7 +</head>
8 +<body>
9 + <div x-data class="framework-modal-container">
10 + <template x-if="$store.frameworkStore">
11 + <div x-init="$store.frameworkStore.init()" x-destroy="$store.frameworkStore.onClose()">
12 +
13 + <div x-show="$store.frameworkStore.loading" class="loading">
14 + Loading frameworks...
15 + </div>
16 +
17 + <div x-show="$store.frameworkStore.error" class="error">
18 + <span x-text="$store.frameworkStore.error"></span>
19 + </div>
20 +
21 + <div x-show="!$store.frameworkStore.loading && !$store.frameworkStore.error">
22 +
23 + <!-- Framework selector -->
24 + <div class="framework-selector">
25 + <label class="selector-label">
26 + <span>View Framework:</span>
27 + <select class="framework-dropdown"
28 + @change="$store.frameworkStore.selectFramework($event.target.value)">
29 + <template x-for="fw in $store.frameworkStore.frameworks" :key="fw.id">
30 + <option :value="fw.id"
31 + :selected="$store.frameworkStore.selectedFramework?.id === fw.id"
32 + x-text="fw.name"></option>
33 + </template>
34 + </select>
35 + </label>
36 + </div>
37 +
38 + <!-- Framework details -->
39 + <template x-if="$store.frameworkStore.selectedFramework">
40 + <div class="framework-details">
41 + <div class="framework-header">
42 + <h3 x-text="$store.frameworkStore.selectedFramework.name"></h3>
43 + <span class="framework-id" x-text="'ID: ' + $store.frameworkStore.selectedFramework.id"></span>
44 + </div>
45 +
46 + <p class="framework-description" x-text="$store.frameworkStore.selectedFramework.description"></p>
47 +
48 + <!-- Workflow steps -->
49 + <template x-if="$store.frameworkStore.selectedFramework.workflows?.length > 0">
50 + <div class="workflow-section">
51 + <h4>Workflow Steps</h4>
52 + <div class="workflow-steps">
53 + <template x-for="(step, index) in $store.frameworkStore.selectedFramework.workflows" :key="step.skill_name">
54 + <div class="workflow-step">
55 + <div class="step-number" x-text="step.sequence"></div>
56 + <div class="step-content">
57 + <div class="step-name" x-text="step.name"></div>
58 + <div class="step-skill">
59 + <code x-text="step.skill_name"></code>
60 + </div>
61 + <div class="step-description" x-text="step.description"></div>
62 + </div>
63 + </div>
64 + </template>
65 + </div>
66 + </div>
67 + </template>
68 +
69 + <!-- No workflows message -->
70 + <template x-if="!$store.frameworkStore.selectedFramework.workflows?.length">
71 + <div class="no-workflows">
72 + <p>This framework has no predefined workflow steps.</p>
73 + </div>
74 + </template>
75 +
76 + <!-- Usage hint -->
77 + <div class="usage-hint">
78 + <h4>How to Use</h4>
79 + <p>When this framework is active:</p>
80 + <ul>
81 + <li>Framework skills are prioritized in skill discovery</li>
82 + <li>Workflow guidance is injected into the system prompt</li>
83 + <li>Use <code>skills_tool</code> to load specific workflow skills</li>
84 + </ul>
85 + </div>
86 + </div>
87 + </template>
88 +
89 + <!-- No selection -->
90 + <template x-if="!$store.frameworkStore.selectedFramework">
91 + <div class="no-selection">
92 + <p>Select a framework to view its details.</p>
93 + </div>
94 + </template>
95 + </div>
96 +
97 + </div>
98 + </template>
99 + </div>
100 +
101 + <style>
102 + .framework-modal-container {
103 + padding: 0.5rem;
104 + }
105 +
106 + .loading {
107 + text-align: center;
108 + padding: 2rem;
109 + color: var(--color-secondary);
110 + }
111 +
112 + .error {
113 + color: var(--color-error);
114 + padding: 1rem;
115 + background: var(--color-error-bg);
116 + border-radius: 4px;
117 + margin-bottom: 1rem;
118 + }
119 +
120 + .framework-selector {
121 + margin-bottom: 1.5rem;
122 + }
123 +
124 + .selector-label {
125 + display: flex;
126 + align-items: center;
127 + gap: 0.75rem;
128 + font-weight: 600;
129 + }
130 +
131 + .framework-dropdown {
132 + flex: 1;
133 + max-width: 300px;
134 + padding: 0.5rem;
135 + border: 1px solid var(--color-border);
136 + border-radius: 4px;
137 + background: var(--color-bg-primary);
138 + color: var(--color-text-primary);
139 + font-size: 0.95rem;
140 + }
141 +
142 + .framework-details {
143 + background: var(--color-input);
144 + border: 1px solid var(--color-border);
145 + border-radius: 8px;
146 + padding: 1.25rem;
147 + }
148 +
149 + .framework-header {
150 + display: flex;
151 + align-items: baseline;
152 + gap: 1rem;
153 + margin-bottom: 0.75rem;
154 + }
155 +
156 + .framework-header h3 {
157 + margin: 0;
158 + font-size: 1.25rem;
159 + color: var(--color-primary);
160 + }
161 +
162 + .framework-id {
163 + font-size: 0.8rem;
164 + color: var(--color-secondary);
165 + font-family: monospace;
166 + }
167 +
168 + .framework-description {
169 + color: var(--color-text-secondary);
170 + line-height: 1.5;
171 + margin-bottom: 1.5rem;
172 + }
173 +
174 + .workflow-section h4,
175 + .usage-hint h4 {
176 + font-size: 1rem;
177 + margin: 0 0 0.75rem 0;
178 + color: var(--color-primary);
179 + border-bottom: 1px solid var(--color-border);
180 + padding-bottom: 0.5rem;
181 + }
182 +
183 + .workflow-steps {
184 + display: flex;
185 + flex-direction: column;
186 + gap: 0.75rem;
187 + }
188 +
189 + .workflow-step {
190 + display: flex;
191 + gap: 1rem;
192 + padding: 0.75rem;
193 + background: var(--color-bg-primary);
194 + border-radius: 6px;
195 + border: 1px solid var(--color-border);
196 + }
197 +
198 + .step-number {
199 + display: flex;
200 + align-items: center;
201 + justify-content: center;
202 + width: 2rem;
203 + height: 2rem;
204 + background: var(--color-accent);
205 + color: white;
206 + border-radius: 50%;
207 + font-weight: bold;
208 + font-size: 0.9rem;
209 + flex-shrink: 0;
210 + }
211 +
212 + .step-content {
213 + flex: 1;
214 + }
215 +
216 + .step-name {
217 + font-weight: 600;
218 + margin-bottom: 0.25rem;
219 + }
220 +
221 + .step-skill {
222 + margin-bottom: 0.25rem;
223 + }
224 +
225 + .step-skill code {
226 + font-size: 0.8rem;
227 + background: var(--color-input);
228 + padding: 0.15rem 0.4rem;
229 + border-radius: 3px;
230 + color: var(--color-accent);
231 + }
232 +
233 + .step-description {
234 + font-size: 0.9rem;
235 + color: var(--color-text-secondary);
236 + }
237 +
238 + .no-workflows,
239 + .no-selection {
240 + text-align: center;
241 + padding: 2rem;
242 + color: var(--color-secondary);
243 + }
244 +
245 + .usage-hint {
246 + margin-top: 1.5rem;
247 + padding-top: 1rem;
248 + }
249 +
250 + .usage-hint p {
251 + margin: 0 0 0.5rem 0;
252 + color: var(--color-text-secondary);
253 + }
254 +
255 + .usage-hint ul {
256 + margin: 0;
257 + padding-left: 1.5rem;
258 + color: var(--color-text-secondary);
259 + }
260 +
261 + .usage-hint li {
262 + margin-bottom: 0.25rem;
263 + }
264 +
265 + .usage-hint code {
266 + font-size: 0.85rem;
267 + background: var(--color-input);
268 + padding: 0.1rem 0.3rem;
269 + border-radius: 3px;
270 + }
271 + </style>
272 +</body>
273 +</html>
webui/components/settings/frameworks/framework-store.js new
+60
@@ -0,0 +1,60 @@
1 +import { createStore } from "/js/AlpineStore.js";
2 +import { callJsonApi } from "/js/api.js";
3 +
4 +const model = {
5 + frameworks: [],
6 + selectedFramework: null,
7 + loading: false,
8 + error: null,
9 + _initialized: false,
10 +
11 + async init() {
12 + if (this._initialized) return;
13 + this._initialized = true;
14 + await this.loadFrameworks();
15 + },
16 +
17 + async loadFrameworks() {
18 + this.loading = true;
19 + this.error = null;
20 + try {
21 + const response = await callJsonApi("frameworks", { action: "list" });
22 + if (response.ok) {
23 + this.frameworks = response.data;
24 + // Select current framework from settings
25 + const currentFramework = this.getCurrentFrameworkId();
26 + this.selectFramework(currentFramework);
27 + } else {
28 + this.error = response.error || "Failed to load frameworks";
29 + }
30 + } catch (e) {
31 + this.error = e.message || "Failed to load frameworks";
32 + } finally {
33 + this.loading = false;
34 + }
35 + },
36 +
37 + getCurrentFrameworkId() {
38 + // Get from settings store - new structure has settings.dev_framework directly
39 + const settingsStore = window.Alpine?.store("settingsStore");
40 + if (settingsStore?.settings?.dev_framework) {
41 + return settingsStore.settings.dev_framework;
42 + }
43 + return "none";
44 + },
45 +
46 + selectFramework(frameworkId) {
47 + this.selectedFramework = this.frameworks.find(f => f.id === frameworkId) || null;
48 + },
49 +
50 + getWorkflowSteps() {
51 + if (!this.selectedFramework) return [];
52 + return this.selectedFramework.workflows || [];
53 + },
54 +
55 + onClose() {
56 + // Cleanup if needed
57 + }
58 +};
59 +
60 +export const store = createStore("frameworkStore", model);
webui/components/settings/settings-store.js
+1
@@ -13,6 +13,7 @@ const FIELD_BUTTON_MODAL_BY_ID = Object.freeze({
13 backup_restore: "settings/backup/restore.html",
14 show_a2a_connection: "settings/a2a/a2a-connection.html",
15 external_api_examples: "settings/external/api-examples.html",
16 + framework_info: "settings/frameworks/framework-details.html",
17 });
18
19 // Helper for toasts
webui/components/settings/settings.html
+11 -4
@@ -30,13 +30,17 @@
30 <!-- Tab Navigation -->
31 <div class="settings-tabs-container">
32 <div class="settings-tabs">
33 - <div class="settings-tab"
33 + <div class="settings-tab"
34 :class="{'active': $store.settingsStore.activeTab === 'agent'}"
35 - @click="$store.settingsStore.switchTab('agent')"
35 + @click="$store.settingsStore.switchTab('agent')"
36 title="Agent Settings">Agent Settings</div>
37 - <div class="settings-tab"
37 + <div class="settings-tab"
38 + :class="{'active': $store.settingsStore.activeTab === 'skills'}"
39 + @click="$store.settingsStore.switchTab('skills')"
40 + title="Skills">Skills</div>
41 + <div class="settings-tab"
42 :class="{'active': $store.settingsStore.activeTab === 'external'}"
39 - @click="$store.settingsStore.switchTab('external')"
43 + @click="$store.settingsStore.switchTab('external')"
44 title="External Services">External Services</div>
45 <div class="settings-tab"
46 :class="{'active': $store.settingsStore.activeTab === 'mcp'}"
@@ -58,6 +62,9 @@
62 <div x-show="$store.settingsStore.activeTab === 'agent'">
63 <x-component path="settings/agent/agent-settings.html"></x-component>
64 </div>
65 + <div x-show="$store.settingsStore.activeTab === 'skills'">
66 + <x-component path="settings/skills/skills-settings.html"></x-component>
67 + </div>
68 <div x-show="$store.settingsStore.activeTab === 'external'">
69 <x-component path="settings/external/external-settings.html"></x-component>
70 </div>
webui/components/settings/skills/import.html new
+221
@@ -0,0 +1,221 @@
1 +<html>
2 +<head>
3 + <title>Import Skills</title>
4 + <script type="module">
5 + import { store } from "/components/settings/skills/skills-import-store.js";
6 + </script>
7 +</head>
8 +<body>
9 + <div x-data>
10 + <template x-if="$store.skillsImportStore">
11 + <div x-init="$store.skillsImportStore.init()" x-destroy="$store.skillsImportStore.onClose()">
12 +
13 + <h3>Import Skills (SKILL.md)</h3>
14 +
15 + <div class="upload-section">
16 + <label for="skills-file" class="upload-label">
17 + Select Skills Pack (.zip)
18 + </label>
19 + <input type="file" id="skills-file" accept=".zip"
20 + @change="$store.skillsImportStore.handleFileUpload($event)">
21 + <div class="upload-hint">
22 + Upload a repository/archive that contains SKILL.md skill folders (see agentskills.io).
23 + </div>
24 + </div>
25 +
26 + <div class="options" x-show="$store.skillsImportStore.skillsFile">
27 + <label class="policy-label">
28 + <span class="policy-label-text">Destination:</span>
29 + <select x-model="$store.skillsImportStore.dest" class="policy-dropdown"
30 + @change="$store.skillsImportStore.previewImport()">
31 + <option value="shared">Shared (recommended)</option>
32 + <option value="custom">Custom</option>
33 + <option value="project">Project</option>
34 + </select>
35 + </label>
36 +
37 + <label class="policy-label" x-show="$store.skillsImportStore.dest === 'project'">
38 + <span class="policy-label-text">Project:</span>
39 + <select x-model="$store.skillsImportStore.projectName" class="policy-dropdown"
40 + @change="$store.skillsImportStore.previewImport()">
41 + <option value="">Select a project...</option>
42 + <template x-for="project in $store.skillsImportStore.projects" :key="project.name">
43 + <option :value="project.name" x-text="project.title || project.name"></option>
44 + </template>
45 + </select>
46 + </label>
47 +
48 + <label class="policy-label">
49 + <span class="policy-label-text">Namespace:</span>
50 + <input class="text-input" type="text" placeholder="e.g. my-pack"
51 + x-model="$store.skillsImportStore.namespace"
52 + @change="$store.skillsImportStore.previewImport()">
53 + </label>
54 +
55 + <label class="policy-label">
56 + <span class="policy-label-text">Conflict policy:</span>
57 + <select x-model="$store.skillsImportStore.conflict" class="policy-dropdown"
58 + @change="$store.skillsImportStore.previewImport()">
59 + <option value="skip">Skip existing</option>
60 + <option value="rename">Rename (add _2, _3...)</option>
61 + <option value="overwrite">Overwrite existing</option>
62 + </select>
63 + </label>
64 +
65 + <div class="buttons">
66 + <button class="btn slim" @click="$store.skillsImportStore.previewImport()"
67 + :disabled="$store.skillsImportStore.loading">Preview</button>
68 + <button class="btn slim primary" @click="$store.skillsImportStore.performImport()"
69 + :disabled="$store.skillsImportStore.loading">Import</button>
70 + </div>
71 + </div>
72 +
73 + <div x-show="$store.skillsImportStore.loading" class="loading">
74 + <span x-text="$store.skillsImportStore.loadingMessage || 'Processing...'"></span>
75 + </div>
76 +
77 + <div x-show="$store.skillsImportStore.error" class="error">
78 + <span x-text="$store.skillsImportStore.error"></span>
79 + </div>
80 +
81 + <div x-show="$store.skillsImportStore.preview" class="preview">
82 + <h4>Preview</h4>
83 + <div class="preview-meta">
84 + <div>Destination: <code x-text="$store.skillsImportStore.preview?.destination"></code></div>
85 + <div>Namespace: <code x-text="$store.skillsImportStore.preview?.namespace"></code></div>
86 + <div>Would import: <span x-text="$store.skillsImportStore.preview?.imported_count || 0"></span></div>
87 + <div>Would skip: <span x-text="$store.skillsImportStore.preview?.skipped_count || 0"></span></div>
88 + </div>
89 +
90 + <textarea class="preview-list" readonly
91 + x-text="($store.skillsImportStore.preview?.imported || []).join('\n')"></textarea>
92 + </div>
93 +
94 + <div x-show="$store.skillsImportStore.result" class="result">
95 + <h4>Import Complete</h4>
96 + <div class="preview-meta">
97 + <div>Imported: <span x-text="$store.skillsImportStore.result?.imported_count || 0"></span></div>
98 + <div>Skipped: <span x-text="$store.skillsImportStore.result?.skipped_count || 0"></span></div>
99 + </div>
100 + <div class="note">
101 + Skills are indexed automatically. If you don’t see them immediately, use the Restart button in the left pane.
102 + </div>
103 + </div>
104 +
105 + </div>
106 + </template>
107 + </div>
108 +
109 + <style>
110 + .upload-section {
111 + margin-bottom: 1rem;
112 + padding: 1rem;
113 + border: 2px dashed var(--color-border);
114 + border-radius: 4px;
115 + text-align: center;
116 + }
117 +
118 + .upload-label {
119 + display: block;
120 + margin-bottom: 0.5rem;
121 + font-weight: 600;
122 + }
123 +
124 + .upload-hint {
125 + margin-top: 0.5rem;
126 + font-size: 0.85rem;
127 + color: var(--color-secondary);
128 + }
129 +
130 + .options {
131 + margin: 1rem 0;
132 + padding: 0.75rem;
133 + background: var(--color-input);
134 + border: 1px solid var(--color-border);
135 + border-radius: 4px;
136 + }
137 +
138 + .policy-label {
139 + display: flex;
140 + align-items: center;
141 + gap: 0.5rem;
142 + margin: 0.5rem 0;
143 + }
144 +
145 + .policy-label-text {
146 + font-weight: 600;
147 + white-space: nowrap;
148 + width: 9rem;
149 + }
150 +
151 + .policy-dropdown, .text-input {
152 + flex: 1;
153 + padding: 0.5rem;
154 + border: 1px solid var(--color-border);
155 + border-radius: 4px;
156 + background: var(--color-bg-primary);
157 + color: var(--color-text-primary);
158 + font-size: 0.9rem;
159 + }
160 +
161 + .buttons {
162 + margin-top: 0.75rem;
163 + display: flex;
164 + gap: 0.5rem;
165 + }
166 +
167 + .loading {
168 + width: 100%;
169 + text-align: center;
170 + margin-top: 1rem;
171 + margin-bottom: 1rem;
172 + color: var(--color-secondary);
173 + }
174 +
175 + .error {
176 + color: var(--color-error);
177 + margin: 0.5rem 0;
178 + padding: 0.5rem;
179 + background: var(--color-error-bg);
180 + border-radius: 4px;
181 + }
182 +
183 + .preview, .result {
184 + margin-top: 1rem;
185 + padding: 0.75rem;
186 + background: var(--color-bg-primary);
187 + border: 1px solid var(--color-border);
188 + border-radius: 4px;
189 + }
190 +
191 + .preview-meta {
192 + display: grid;
193 + grid-template-columns: 1fr 1fr;
194 + gap: 0.25rem 1rem;
195 + margin-bottom: 0.5rem;
196 + color: var(--color-text-secondary);
197 + font-size: 0.9rem;
198 + }
199 +
200 + .preview-list {
201 + width: 100%;
202 + height: 12em;
203 + font-family: monospace;
204 + font-size: 0.85em;
205 + background: var(--color-bg-primary);
206 + color: var(--color-text-primary);
207 + border: 1px solid var(--color-border);
208 + border-radius: 4px;
209 + padding: 0.5em;
210 + resize: vertical;
211 + }
212 +
213 + .note {
214 + margin-top: 0.5rem;
215 + font-size: 0.9rem;
216 + color: var(--color-text-secondary);
217 + }
218 + </style>
219 +</body>
220 +</html>
221 +
webui/components/settings/skills/skills-import-store.js new
+180
@@ -0,0 +1,180 @@
1 +import { createStore } from "/js/AlpineStore.js";
2 +
3 +const fetchApi = globalThis.fetchApi;
4 +
5 +function sanitizeNamespace(text) {
6 + if (!text) return "";
7 + return String(text)
8 + .trim()
9 + .replace(/[^a-zA-Z0-9._-]+/g, "_")
10 + .replace(/^_+|_+$/g, "");
11 +}
12 +
13 +const model = {
14 + loading: false,
15 + loadingMessage: "",
16 + error: "",
17 +
18 + skillsFile: null,
19 + dest: "shared", // shared|custom|project
20 + namespace: "",
21 + conflict: "skip", // skip|overwrite|rename
22 + projectName: "", // selected project name when dest is "project"
23 + projects: [], // available projects list
24 +
25 + preview: null,
26 + result: null,
27 +
28 + init() {
29 + this.resetState();
30 + this.loadProjects();
31 + },
32 +
33 + resetState() {
34 + this.loading = false;
35 + this.loadingMessage = "";
36 + this.error = "";
37 + this.preview = null;
38 + this.result = null;
39 + },
40 +
41 + onClose() {
42 + this.resetState();
43 + this.skillsFile = null;
44 + },
45 +
46 + async loadProjects() {
47 + try {
48 + const response = await fetchApi("/projects", {
49 + method: "POST",
50 + headers: { "Content-Type": "application/json" },
51 + body: JSON.stringify({ action: "list" }),
52 + });
53 + const data = await response.json();
54 + this.projects = data.ok ? (data.data || []) : [];
55 + } catch (e) {
56 + console.error("Failed to load projects:", e);
57 + this.projects = [];
58 + }
59 + },
60 +
61 + async handleFileUpload(event) {
62 + const file = event.target.files[0];
63 + if (!file) return;
64 +
65 + this.skillsFile = file;
66 + this.error = "";
67 + this.result = null;
68 + this.preview = null;
69 +
70 + // default namespace from file name (minus .zip)
71 + const base = file.name.replace(/\.zip$/i, "");
72 + if (!this.namespace) {
73 + this.namespace = sanitizeNamespace(base);
74 + } else {
75 + this.namespace = sanitizeNamespace(this.namespace);
76 + }
77 +
78 + await this.previewImport();
79 + },
80 +
81 + buildFormData() {
82 + const formData = new FormData();
83 + formData.append("skills_file", this.skillsFile);
84 + formData.append("ctxid", globalThis.getContext ? globalThis.getContext() : "");
85 + formData.append("dest", this.dest);
86 + formData.append("namespace", sanitizeNamespace(this.namespace));
87 + formData.append("conflict", this.conflict);
88 + if (this.dest === "project" && this.projectName) {
89 + formData.append("project_name", this.projectName);
90 + }
91 + return formData;
92 + },
93 +
94 + async previewImport() {
95 + if (!this.skillsFile) {
96 + this.error = "Please select a skills .zip file first";
97 + return;
98 + }
99 +
100 + if (this.dest === "project" && !this.projectName) {
101 + this.error = "Please select a project";
102 + return;
103 + }
104 +
105 + try {
106 + this.loading = true;
107 + this.loadingMessage = "Previewing skills import...";
108 + this.error = "";
109 + this.preview = null;
110 +
111 + const response = await fetchApi("/skills_import_preview", {
112 + method: "POST",
113 + body: this.buildFormData(),
114 + });
115 +
116 + const result = await response.json();
117 + if (!result.success) {
118 + this.error = result.error || "Preview failed";
119 + return;
120 + }
121 +
122 + this.preview = result;
123 + // normalize namespace (server may sanitize)
124 + if (result.namespace) this.namespace = result.namespace;
125 + } catch (e) {
126 + this.error = `Preview error: ${e.message}`;
127 + } finally {
128 + this.loading = false;
129 + this.loadingMessage = "";
130 + }
131 + },
132 +
133 + async performImport() {
134 + if (!this.skillsFile) {
135 + this.error = "Please select a skills .zip file first";
136 + return;
137 + }
138 +
139 + if (this.dest === "project" && !this.projectName) {
140 + this.error = "Please select a project";
141 + return;
142 + }
143 +
144 + try {
145 + this.loading = true;
146 + this.loadingMessage = "Importing skills...";
147 + this.error = "";
148 + this.result = null;
149 +
150 + const response = await fetchApi("/skills_import", {
151 + method: "POST",
152 + body: this.buildFormData(),
153 + });
154 +
155 + const result = await response.json();
156 + if (!result.success) {
157 + this.error = result.error || "Import failed";
158 + return;
159 + }
160 +
161 + this.result = result;
162 + this.preview = result; // keep last info visible
163 + if (window.toastFrontendInfo) {
164 + window.toastFrontendInfo(
165 + `Imported ${result.imported_count} skill folder(s)`,
166 + "Skills Import"
167 + );
168 + }
169 + } catch (e) {
170 + this.error = `Import error: ${e.message}`;
171 + } finally {
172 + this.loading = false;
173 + this.loadingMessage = "";
174 + }
175 + },
176 +};
177 +
178 +const store = createStore("skillsImportStore", model);
179 +export { store };
180 +
webui/components/settings/skills/skills-settings.html new
+28
@@ -0,0 +1,28 @@
1 +<html>
2 + <head>
3 + <title>Skills Settings</title>
4 + </head>
5 +
6 + <body>
7 + <div x-data>
8 + <template x-if="$store.settingsStore">
9 + <div>
10 + <nav>
11 + <ul>
12 + <li>
13 + <a href="#section-skills-import">
14 + <img src="/public/skills.svg" alt="Import Skills" />
15 + <span>Import Skills</span>
16 + </a>
17 + </li>
18 + </ul>
19 + </nav>
20 +
21 + <div id="section-skills-import" class="section">
22 + <x-component path="settings/skills/import.html"></x-component>
23 + </div>
24 + </div>
25 + </template>
26 + </div>
27 + </body>
28 +</html>
webui/js/messages.js
+4 -1
@@ -782,7 +782,10 @@ export function drawMessageResponse({
782 : [];
783 setupCollapsible(messageDiv, ":scope > .step-action-buttons", !isMassRender(), responseActionButtons);
784
785 - if (group) updateProcessGroupHeader(group);
785 + if (group) {
786 + updateProcessGroupHeader(group);
787 + markProcessGroupComplete(group, heading);
788 + }
789
790 return container;
791 }
webui/public/framework.svg new
+1
@@ -0,0 +1 @@
1 +<?xml version="1.0" encoding="utf-8" ?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="1200" height="1200" viewBox="0 0 1200 1200"><path fill="#000101" transform="scale(0.657895 0.513699)" d="M508.916 0L1362.98 0C1363.14 0.341385 1363.3 0.687576 1363.47 1.02416C1367.39 8.79865 1375.59 13.481 1377.62 22.3398C1380.47 34.7523 1378.95 51.336 1378.95 64.2781C1378.94 81.9683 1377.02 188.105 1381.11 195.297C1382.95 198.534 1388.89 199.874 1391.85 200.621C1403.38 203.535 1415.16 204.96 1426.76 207.372C1451.19 212.452 1475.51 218.557 1500 223.552C1518.47 227.322 1543.07 230.826 1560.33 238.651C1565.8 241.128 1570.8 244.81 1574.08 251.121C1578 258.672 1578.06 267.695 1576.53 276.269C1574.84 285.685 1572.24 294.787 1570.41 304.151C1568.82 312.283 1567.79 320.642 1565.96 328.687C1564.25 336.171 1561.37 343.586 1560.24 351.235C1559.77 354.416 1559.94 356.73 1560.65 359.804C1566.58 371.237 1704.56 402.097 1721.74 417.629C1727.82 423.126 1736.93 428.034 1735.07 441.399C1732.85 451.78 1727.77 465.427 1724.4 475.72L1706.45 531.013C1692.87 571.851 1681.07 615.67 1667.8 656.842C1662.51 673.253 1632.11 754.205 1634.96 767.592C1638.74 774.659 1645.85 776.163 1651.74 780.39C1665.5 790.276 1675.09 808.073 1681.84 825.628C1695.69 861.609 1683.41 907.329 1690.99 945.367C1691.95 950.203 1720.35 948.698 1724 950.34C1759.45 957.538 1804.35 975.855 1817.09 1024.12C1818.63 1029.96 1820.1 1031.6 1824 1035.07L1824 1098.99L1823.07 1100.16C1820.91 1102.91 1817.32 1107.3 1816.75 1111.13C1813.76 1131.32 1810.43 1150.95 1806.44 1170.89L1763.34 1392.13L1681.34 1807.46C1676.11 1835.13 1672.99 1863.13 1666.61 1890.46C1653.16 1948.08 1653.99 2012.17 1613.21 2052.11C1576.48 2088.08 1535.19 2085.63 1492 2085.85L1432.92 2086.33L964.508 2086.38L806.112 2086.92C783.811 2086.97 746.255 2085.09 725.114 2087.2C715.475 2085.97 700.34 2087.07 690.246 2086.85C663.853 2086.27 636.829 2087.48 610.487 2086.83C490.842 2083.71 371.175 2082.16 251.505 2082.19L167.427 2082.23C121.545 2082.25 74.9808 2085.95 35.3736 2050.28C28.4268 2044.03 22.0048 2036.76 14.9919 2030.68L14.263 2030.06C12.4683 2025.24 2.57937 2001.92 0 1998.96L0 801.635C7.18447 791.036 7.72495 778.136 16.8099 764.683C37.3154 734.318 58.1865 724.038 87.9834 716.137C102.398 712.315 140.086 717.84 150.038 711.031C151.555 705.592 141.83 674.733 140.069 667.026C125.605 603.728 110.385 540.727 93.7366 478.318C87.6296 455.425 81.538 440.433 102.183 426.897C120.334 414.997 203.496 404.36 214.886 392.661C218.596 384.853 200.09 293.673 198.223 276.127C195.484 250.386 183.878 214.612 184.65 186.414C185.335 161.424 210.071 164.261 223.978 160.104C252.24 154.72 282.266 148.217 310.432 143.61L431.214 124.021C442.506 122.125 485.147 118.381 492.515 110.784C497.476 99.3625 493.429 43.4056 495.178 26.3796C496.784 10.7562 498.726 11.2972 508.916 0ZM1601.26 1968.14C1608.89 1943.51 1610.99 1922.29 1615.81 1896.93C1618.38 1883.44 1621.74 1870.92 1624 1857.13C1625.82 1846.02 1627.02 1832.44 1629.04 1821.75L1697.39 1475.31L1751.4 1195.24C1759.32 1153.95 1769.4 1112.43 1775.35 1070.7C1778.66 1047.5 1760.92 1015.47 1744.22 1009.85C1711.71 998.931 1668.74 1002.71 1634.95 1003L1518.54 1003.37L1009.08 1003.23L859.472 1003.33C834.05 1003.55 800.12 1005.53 775.465 1002.68C727.391 997.106 711.134 958.746 687.676 912.926L646.484 831.711C632.93 805.145 621.492 772.861 594.339 771.055C573.505 769.67 552.276 770.287 531.435 770.336L452.006 770.475L180.588 770.495C161.103 770.497 105.852 768.652 90.3112 774.399C81.0911 777.835 72.6887 784.171 65.8695 792.829C59.0862 801.531 54.8373 811.525 53.7269 823.666C49.9807 864.631 51.5087 911.507 51.5272 953.062L51.7401 1185.33C52.0648 1376 51.6141 1566.67 50.3878 1757.33C50.4072 1801.85 49.9809 1846.19 49.2629 1890.69C48.879 1914.49 48.7726 1938.54 49.3763 1962.31C49.6601 1972.72 54.8135 1995.68 60.8 2002.58C70.4693 2013.72 82.4238 2025.13 95.8591 2026.51C119.313 2028.91 143.103 2028.31 166.582 2028.29L269.985 2028.31L627.415 2027.59L1210.57 2027.77L1418.24 2027.91C1459.17 2028.05 1500.13 2028.27 1541.22 2028.15C1561.57 2028.09 1576.1 2017.67 1590.72 1999.73C1597.35 1991.59 1599.16 1979.36 1601.26 1968.14ZM891.543 718.868C899.272 692.549 907.202 665.057 915.296 638.966L937.394 569.04C941.254 556.787 953.194 528.484 953.008 515.921C952.793 501.434 941.143 468.135 938.08 452.374C935.985 441.59 933.025 429.927 930.285 419.407C927.447 410.173 923.72 408.351 916.316 409.797C905.935 411.825 895.837 415.24 885.556 417.849L804.481 438.888L371.871 546.771L233.704 581.831C221.855 584.937 194.809 589.245 185.491 594.051C184.065 595.892 182.303 598.896 182.892 601.77C189.726 635.149 198.746 668.341 205.759 701.841C206.47 705.235 207.839 708.771 209.27 711.137C219.08 715.123 271.02 713.763 284.844 713.802L506.732 714.718C525.686 714.906 544.64 714.904 563.593 714.712C574.408 714.583 592.293 713.128 602.539 715.289C625.96 720.229 651.678 731.925 667.557 755.64C676.745 769.364 682.52 783.592 690.38 798.355C710.165 835.053 726.722 873.682 747.21 909.919C751.716 917.89 756.32 932.759 763.015 938.722C775.958 950.249 804.288 949.534 819.485 945.571C820.752 945.241 821.819 942.818 822.354 941.461C826.484 924.183 832.164 908.412 837.768 891.936C840.641 883.488 841.584 872.121 844.729 863.548C849.55 850.01 854.007 837.753 858.409 823.874C869.155 789.687 881.87 752.501 891.543 718.868ZM891.657 898.458C889.79 903.052 878.531 942.35 879.38 946.369C882.193 947.439 889.34 948.99 892.068 948.883C913.562 948.046 1027.42 953.51 1043.19 947.574C1044.02 941.477 1038.34 936.161 1036.37 929.974C1036.92 927.392 1037.82 924.951 1039.02 922.76C1055.65 892.305 1077.18 861.57 1093.46 830.228C1100.53 816.625 1111.36 802.363 1125 811.786C1130.72 815.739 1146.76 825.137 1149.99 831.173C1151.4 839.503 1133.6 864.934 1128.93 872.563C1120.19 887.05 1111.63 901.722 1103.27 916.571C1099.66 922.889 1088.77 939.032 1090.79 946.182C1095.28 951.116 1132.99 951.138 1137.28 946.661C1140.52 938.669 1129.17 928.587 1149.45 922.255C1204.94 904.926 1122.29 882.16 1172.17 858.666C1178.94 855.475 1186.87 847.107 1195.19 848.531C1199.24 853.105 1201.7 858.202 1204.89 863.651C1215.27 881.381 1226.98 899.434 1234.87 919.177C1238.16 927.391 1218.65 939.426 1220.62 947.052C1221.79 947.953 1221.72 947.981 1223.25 948.657C1230.43 951.838 1482.88 951.941 1511.79 949.859C1514.6 949.657 1517.4 949.457 1519.97 947.873C1527.57 935.523 1529 920.501 1533.56 906.329L1573.86 781.615L1644.97 554.693C1651.6 533.219 1674.2 476.795 1672.96 457.039C1668.89 448.306 1634.71 440.747 1625.25 437.84L1556.86 416.089L1242.14 316.593C1195.26 301.54 1147.47 289.045 1100.72 272.86C1096.17 271.284 1088.81 270.614 1086.38 276.967C1077.09 301.285 1070.09 326.399 1062.33 351.439L1029.53 456.452L954.642 696.058C951.264 707.179 948.34 719.251 944.927 730.683C928.522 787.296 910.757 843.248 891.657 898.458ZM886.459 281.987L477.786 386.278L294.33 433.42L216.001 453.044C206.415 455.423 159.615 463.744 152.651 471.989C148.31 477.128 162.712 532.976 167.674 538.524C170.833 540.311 173.132 539.627 176.565 538.809C207.705 531.807 236.637 523.379 267.329 515.77L531.491 449.743L780.205 388.284L861.022 367.334C873.888 364.031 886.926 361.131 899.663 357.662C904.426 356.364 914.745 353.81 911.899 345.169C907.415 331.559 900.824 289.704 891.872 282.224C889.132 281.574 889.153 281.388 886.459 281.987ZM1380.74 251.953C1376.42 259.678 1376.51 297.937 1381.34 304.616C1389.67 309.424 1410.9 315.004 1420.74 318.27C1438.34 324.338 1456 330.124 1473.72 335.626C1484.93 339.131 1501.85 347.63 1511.74 338.767C1512.96 334.893 1518.92 288.987 1518.77 283.995C1513.34 276.217 1462.47 267.973 1451.66 265.555C1436.79 262.126 1421.9 258.818 1406.99 255.633C1399.27 254.004 1388.16 250.849 1380.74 251.953ZM813.884 786.068C790.211 791.714 757.08 802.371 732.811 802.979C726.882 803.127 719.178 764.686 720.803 757.607C724.795 750.786 756.1 745.063 763.453 743.101C783.121 737.853 803.015 732.229 822.747 727.457C827.992 725.957 846.394 719.428 850.547 723.122C857.904 729.665 867.744 759.423 862.845 769.888C853.593 778.435 828.597 779.792 813.884 786.068ZM1598.83 949.468C1604.85 949.644 1610.85 950.074 1617.05 949.93C1631.32 949.599 1639.2 952.815 1639.27 930.357C1639.35 904.618 1644.12 832.498 1618.05 823.545C1616.29 824.714 1613.19 827.011 1612.57 829.38C1608.21 845.969 1575.64 935.958 1577.94 946.545C1582.52 951.424 1592.76 949.877 1598.83 949.468ZM552.4 49.3121C547.965 54.9659 548.916 60.744 548.911 69.2211L549.149 205.446C549.16 221.903 548.418 297.418 550.835 306.8C569.241 318.2 870.943 222.168 919.099 223.833C944.826 224.723 945.843 285.059 955.24 306.417C963.367 324.889 976.713 402.555 985.386 413.137L986.992 413.237C993.673 400.94 997.045 380.269 1001.67 366.344C1017.07 319.922 1030.05 268.178 1047.78 223.73C1058.56 196.7 1118.16 223.656 1135.77 229.368C1168.37 239.763 1202.04 249.592 1234.7 259.698C1247.67 263.713 1312.68 287.773 1320.33 283.71C1321.93 281.416 1322.37 279.988 1322.42 276.764C1323.48 204.9 1322.98 132.847 1322.52 60.9659C1322.5 57.9433 1322.34 54.513 1321.22 51.8722C1317.47 48.2156 1311.7 48.6575 1306.52 48.6788C1247.53 48.9216 1188.47 48.7999 1129.48 48.8874L825.979 48.7923L646.008 48.8792L586.315 48.8625C575.943 48.8638 562.563 48.403 552.4 49.3121ZM488.719 166.777C433.977 177.696 379.147 187.883 324.239 197.336C300.5 201.55 276.507 205.333 252.762 209.6C249.385 210.207 247.546 210.971 244.991 213.69C242.622 218.383 243.687 223.993 244.395 229.273C250.323 273.471 261.137 318.163 266.338 362.444C267.32 369.381 267.336 374.683 271.931 378.797C280.755 381.869 325.775 367.711 337.474 364.912L437.526 340.711C446.048 338.607 492.666 330.889 494.27 320.182C495.294 313.348 494.534 285.331 494.46 276.727C494.235 250.443 494.14 224.158 494.176 197.874C494.205 188.971 497.038 177.109 493.76 169.469C491.532 167.017 491.668 167.231 488.719 166.777Z"/><path fill="#FCFDFA" fill-opacity="0.0078431377" transform="scale(0.657895 0.513699)" d="M180.588 770.495L452.006 770.475L531.435 770.336C552.276 770.287 573.505 769.67 594.339 771.055C621.492 772.861 632.93 805.145 646.484 831.711L687.676 912.926C711.134 958.746 727.391 997.106 775.465 1002.68C800.12 1005.53 834.05 1003.55 859.472 1003.33L1009.08 1003.23L1518.54 1003.37L1634.95 1003C1668.74 1002.71 1711.71 998.931 1744.22 1009.85C1760.92 1015.47 1778.66 1047.5 1775.35 1070.7C1769.4 1112.43 1759.32 1153.95 1751.4 1195.24L1697.39 1475.31L1629.04 1821.75C1627.02 1832.44 1625.82 1846.02 1624 1857.13C1621.74 1870.92 1618.38 1883.44 1615.81 1896.93C1610.99 1922.29 1608.89 1943.51 1601.26 1968.14C1599.16 1979.36 1597.35 1991.59 1590.72 1999.73C1576.1 2017.67 1561.57 2028.09 1541.22 2028.15C1500.13 2028.27 1459.17 2028.05 1418.24 2027.91L1210.57 2027.77L627.415 2027.59L269.985 2028.31L166.582 2028.29C143.103 2028.31 119.313 2028.91 95.8591 2026.51C82.4238 2025.13 70.4693 2013.72 60.8 2002.58C54.8135 1995.68 49.6601 1972.72 49.3763 1962.31C48.7726 1938.54 48.879 1914.49 49.2629 1890.69C49.9809 1846.19 50.4072 1801.85 50.3878 1757.33C51.6141 1566.67 52.0648 1376 51.7401 1185.33L51.5272 953.062C51.5087 911.507 49.9807 864.631 53.7269 823.666C54.8373 811.525 59.0862 801.531 65.8695 792.829C72.6887 784.171 81.0911 777.835 90.3112 774.399C105.852 768.652 161.103 770.497 180.588 770.495ZM1015.09 1279.74C1014.96 1277.42 1014.76 1275.26 1014.55 1272.95C1009.43 1264.77 1004.74 1270.99 999.625 1268.83C988.479 1264.11 999.987 1248.96 994.535 1238.24C991.781 1236.34 988.185 1237.04 984.917 1237.19L984.307 1235.93C978.797 1224.35 978.265 1209.85 971.617 1203.2C967.341 1202.03 962.31 1201.03 957.93 1201.17C925.323 1202.21 892.78 1201.23 860.184 1200.31C851.723 1200.07 845.696 1212.21 841.73 1220.5L841.795 1222.64C841.857 1224.99 837.794 1270.62 837.444 1271.54C834.15 1274.38 824.677 1276.74 820.252 1278.9C813.521 1281.63 803.384 1292.26 796.097 1289.39C777.9 1282.23 741.783 1242.01 723.156 1258.55C708.232 1271.79 687.39 1296.42 673.739 1308.34C640.74 1337.16 637.181 1336.93 667.975 1369.52C672.082 1373.86 685.052 1391.64 685.945 1399.58C685.349 1403.9 682.859 1406.8 680.7 1410.01C678.134 1413.84 677.408 1417.58 676.31 1422.32C671.3 1443.97 661.53 1445.23 645.498 1447.12C635.285 1448.33 609.382 1443.97 602.506 1454.02C600.077 1457.57 599.482 1461.99 599.192 1466.57C598.284 1480.93 599.685 1495.83 599.7 1510.28C599.721 1530.67 597.849 1552.83 599.922 1572.97C600.398 1577.58 601.843 1581.67 604.883 1584.4C617.492 1595.71 661.569 1582.11 672.759 1599.35C676.046 1604.41 680.024 1624.53 681.391 1631.81C681.931 1634.68 682.441 1637.08 681.174 1639.72C678.313 1645.69 672.321 1650.53 668.448 1655.56C663.824 1661.55 646.559 1687.8 648.801 1695.63C651.039 1703.44 710.443 1761.6 720.163 1769.57C723.449 1772.26 727.028 1774.55 730.772 1775.99C738.817 1779.07 747.333 1778.06 754.632 1772.67C767.396 1763.23 781.437 1742.78 797.802 1747.63C802.56 1749.04 806.216 1754.45 810.706 1756.76C820.923 1762.03 829.676 1750.16 839.427 1773.16C846.591 1790.05 836.587 1820.49 853.763 1827.52C860.913 1830.45 950.345 1828.81 961.208 1827.91C964.899 1827.6 970.932 1827.12 974.012 1824.61C978.729 1820.77 980.905 1808.6 981.128 1801.94C981.535 1789.82 980.454 1778.18 987.857 1769C994.284 1761.02 1021.92 1746.68 1030.86 1747.08C1041.07 1747.54 1050.69 1755.78 1059.37 1762.02C1069.2 1769.09 1081.72 1782.21 1093.33 1780.98C1094.52 1780.86 1095.44 1780.78 1096.48 1779.92C1104.14 1773.59 1110.65 1764.31 1117.95 1757.22C1124.71 1750.67 1131.98 1744.94 1138.63 1738.23C1144.66 1732.15 1150.19 1725.25 1156.31 1719.35C1162.62 1713.26 1169.59 1707.89 1175.64 1701.43C1177.14 1699.82 1178.25 1697.74 1178.48 1695.19C1178.97 1689.74 1175.49 1685.48 1172.76 1682.03C1165.36 1672.71 1143.53 1648.34 1143.46 1635.31C1143.45 1633.39 1143.8 1631.61 1144.27 1629.79C1145.27 1625.94 1146.9 1622.41 1147.84 1618.54C1149.11 1613.35 1148.64 1607.46 1150.4 1602.39C1151.08 1600.44 1151.87 1599.1 1153.1 1597.66C1171.67 1575.98 1222.71 1608.31 1225.35 1561.22C1225.99 1549.77 1224.48 1538.09 1224.48 1526.6C1224.48 1507.19 1226.16 1487.13 1225.03 1467.82C1224.78 1463.47 1224.44 1457.56 1222.26 1454C1218.61 1448.01 1210.8 1447.73 1205.45 1447.69C1192.91 1447.59 1162.92 1450.94 1154.05 1439.13C1151.38 1435.58 1141.48 1403.95 1141.84 1399.7C1143.69 1377.83 1183.89 1354.33 1171.79 1333.23C1165.54 1322.33 1153.37 1315.89 1145.04 1307.74C1129.65 1292.7 1114.07 1272.61 1098.85 1257.73C1096.49 1255.43 1093.99 1253.97 1091.03 1253.65C1072.05 1251.6 1043.52 1288.39 1030.7 1287.94C1025.18 1287.74 1019.79 1283.08 1015.09 1279.74Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M841.73 1220.5C845.696 1212.21 851.723 1200.07 860.184 1200.31C892.78 1201.23 925.323 1202.21 957.93 1201.17C962.31 1201.03 967.341 1202.03 971.617 1203.2C978.265 1209.85 978.797 1224.35 984.307 1235.93L984.917 1237.19C986.46 1250.33 978.9 1263.15 987.038 1271.64C994.448 1279.37 1006.66 1276.96 1015.09 1279.74C1019.79 1283.08 1025.18 1287.74 1030.7 1287.94C1043.52 1288.39 1072.05 1251.6 1091.03 1253.65C1093.99 1253.97 1096.49 1255.43 1098.85 1257.73C1114.07 1272.61 1129.65 1292.7 1145.04 1307.74C1153.37 1315.89 1165.54 1322.33 1171.79 1333.23C1183.89 1354.33 1143.69 1377.83 1141.84 1399.7C1141.48 1403.95 1151.38 1435.58 1154.05 1439.13C1162.92 1450.94 1192.91 1447.59 1205.45 1447.69C1210.8 1447.73 1218.61 1448.01 1222.26 1454C1224.44 1457.56 1224.78 1463.47 1225.03 1467.82C1226.16 1487.13 1224.48 1507.19 1224.48 1526.6C1224.48 1538.09 1225.99 1549.77 1225.35 1561.22C1222.71 1608.31 1171.67 1575.98 1153.1 1597.66C1151.87 1599.1 1151.08 1600.44 1150.4 1602.39C1148.64 1607.46 1149.11 1613.35 1147.84 1618.54C1146.9 1622.41 1145.27 1625.94 1144.27 1629.79C1143.8 1631.61 1143.45 1633.39 1143.46 1635.31C1143.53 1648.34 1165.36 1672.71 1172.76 1682.03C1175.49 1685.48 1178.97 1689.74 1178.48 1695.19C1178.25 1697.74 1177.14 1699.82 1175.64 1701.43C1169.59 1707.89 1162.62 1713.26 1156.31 1719.35C1150.19 1725.25 1144.66 1732.15 1138.63 1738.23C1131.98 1744.94 1124.71 1750.67 1117.95 1757.22C1110.65 1764.31 1104.14 1773.59 1096.48 1779.92C1095.44 1780.78 1094.52 1780.86 1093.33 1780.98C1081.72 1782.21 1069.2 1769.09 1059.37 1762.02C1050.69 1755.78 1041.07 1747.54 1030.86 1747.08C1021.92 1746.68 994.284 1761.02 987.857 1769C980.454 1778.18 981.535 1789.82 981.128 1801.94C980.905 1808.6 978.729 1820.77 974.012 1824.61C970.932 1827.12 964.899 1827.6 961.208 1827.91C950.345 1828.81 860.913 1830.45 853.763 1827.52C836.587 1820.49 846.591 1790.05 839.427 1773.16C829.676 1750.16 820.923 1762.03 810.706 1756.76C806.216 1754.45 802.56 1749.04 797.802 1747.63C781.437 1742.78 767.396 1763.23 754.632 1772.67C747.333 1778.06 738.817 1779.07 730.772 1775.99C727.028 1774.55 723.449 1772.26 720.163 1769.57C710.443 1761.6 651.039 1703.44 648.801 1695.63C646.559 1687.8 663.824 1661.55 668.448 1655.56C672.321 1650.53 678.313 1645.69 681.174 1639.72C682.441 1637.08 681.931 1634.68 681.391 1631.81C680.024 1624.53 676.046 1604.41 672.759 1599.35C661.569 1582.11 617.492 1595.71 604.883 1584.4C601.843 1581.67 600.398 1577.58 599.922 1572.97C597.849 1552.83 599.721 1530.67 599.7 1510.28C599.685 1495.83 598.284 1480.93 599.192 1466.57C599.482 1461.99 600.077 1457.57 602.506 1454.02C609.382 1443.97 635.285 1448.33 645.498 1447.12C661.53 1445.23 671.3 1443.97 676.31 1422.32C677.408 1417.58 678.134 1413.84 680.7 1410.01C682.859 1406.8 685.349 1403.9 685.945 1399.58C685.052 1391.64 672.082 1373.86 667.975 1369.52C637.181 1336.93 640.74 1337.16 673.739 1308.34C687.39 1296.42 708.232 1271.79 723.156 1258.55C741.783 1242.01 777.9 1282.23 796.097 1289.39C803.384 1292.26 813.521 1281.63 820.252 1278.9C824.677 1276.74 834.15 1274.38 837.444 1271.54C837.794 1270.62 841.857 1224.99 841.795 1222.64L841.73 1220.5ZM692.452 1500.13L691.211 1500.5C680.439 1503.59 659.421 1496.76 664.236 1518.3C665.584 1524.33 674.434 1529.2 678.572 1530.84C704.394 1539.42 699.857 1523.53 720.062 1549.66C733.32 1565.59 725.247 1571.71 731.469 1588.48C736.575 1602.24 758.147 1630.05 758.352 1643.59C758.478 1651.93 749.936 1663.43 745.292 1668.84C740.996 1673.85 730.897 1682.15 730.425 1689.74C730.235 1692.8 731.146 1694.46 732.807 1696.47C735.252 1699.44 739.445 1700.45 742.671 1699.89C755.872 1697.57 763.717 1678.45 777.307 1675.53C785.486 1673.78 799.677 1678.3 807.865 1681.11C814.592 1683.41 819.026 1690.75 825.461 1693.32C841.087 1699.57 879.477 1708.98 890.926 1719.65C891.282 1719.98 891.632 1720.32 891.985 1720.66C907.304 1741.07 890.102 1770.23 907.188 1774.06C943.628 1782.24 915.666 1733.15 932.512 1715.03C942.211 1711.17 950.588 1711.53 959.955 1708.26C964.253 1706.86 974.315 1697.24 977.975 1697.09C997.545 1696.27 1005.58 1691.86 1021.55 1678.06C1033.67 1667.6 1054.66 1675.89 1065.1 1687.07C1069.2 1691.46 1076.31 1697.17 1081.4 1699.34C1086.89 1702.25 1096.66 1696.97 1096.66 1690.1C1096.68 1674.39 1075.47 1662.85 1069.52 1649.55C1066.4 1642.57 1066.22 1640.14 1067.15 1632.21C1068.17 1623.46 1075.66 1619.99 1080.51 1615.51C1089.91 1606.83 1084.39 1604.64 1086.67 1594.57C1088.38 1591.09 1094.32 1586.2 1095.57 1582.66C1105.32 1555.24 1089 1540.9 1122.03 1536.17C1132.22 1534.72 1162.46 1540.9 1164.39 1521.61C1167.16 1493.98 1144.27 1502.03 1131.09 1498.51C1116.13 1495.23 1108.9 1492.24 1099.78 1476.77L1099.06 1475.53C1098.89 1448.89 1099.55 1454.92 1086.64 1432.9C1081.01 1423.31 1075.02 1406.09 1068.18 1396.02C1065.97 1392.75 1067.64 1385.37 1068.47 1381.56C1075.08 1367.44 1096.71 1357.68 1096.53 1348.59C1095.89 1317.74 1060.29 1348.02 1055.54 1352.23C1049.82 1356.07 1043.45 1358.07 1036.98 1358.05C1017.87 1358.09 1015.32 1347.78 1000.93 1342.49C986.603 1337.22 982.34 1337.38 968.981 1326.74C963.908 1322.7 936.38 1328.2 929.989 1317.52C921.273 1308.8 931.01 1273.93 923.426 1268.1C913.145 1260.2 895.263 1263.57 898.768 1285.06C899.799 1291.38 897.775 1316 895.206 1320.25C883.709 1329.3 855.793 1329.87 841.939 1333.26C820.686 1338.48 787.002 1373.07 767.821 1349.8C759.395 1341.93 740.146 1330.2 731.311 1341.91C726.575 1358.29 760.123 1377.1 755.191 1397.57C747.062 1405.97 746.96 1411.04 742.497 1422.86C740.649 1427.75 731.822 1433.68 730.676 1438.91C721.068 1482.76 732.722 1490.31 692.452 1500.13Z"/><path fill="#151716" transform="scale(0.657895 0.513699)" d="M904.203 1393.14C938.234 1390.94 970.378 1401.06 998.167 1426.75C1004.95 1433.02 1019.83 1449.99 1024.04 1458.98C1037.94 1485.73 1038.61 1485.85 1040.02 1515.74C1042.75 1573.42 1000.8 1616.29 962.165 1634.33C950.321 1639.87 936.967 1641.83 922.994 1643.92C895.95 1647.06 854.949 1636.41 833.108 1615.12C816.075 1598.52 789.985 1570.98 787.031 1541.78C783.854 1510.39 785.34 1482.52 802.107 1457.76C819.638 1430.85 841.872 1412.59 867.479 1400.36C875.294 1396.67 895.314 1394.62 904.203 1393.14ZM921.607 1583.91C935.442 1580.79 960.041 1568.14 968.667 1552.18C976.907 1536.94 975.131 1513.54 973.403 1495.85C972.339 1484.95 962.235 1475.21 954.929 1469.9C936.518 1456.54 924.293 1449.64 902.846 1452.55C887.903 1456.79 863.983 1470.85 855.156 1487.49C849.404 1498.33 849.568 1525.76 852.291 1538.31C859.123 1569.8 898.915 1586.37 921.607 1583.91Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M886.485 1406.92C903.999 1405.71 928.304 1406.4 945.687 1408.68C945.205 1408.61 972.6 1427.59 978.007 1425.71C979.045 1425.36 996.369 1441.35 996.89 1443.57C997.977 1455.2 1016 1462.84 1016.16 1470.26C1016.42 1482.2 1019 1505.57 1020.17 1516.45C1021.46 1528.49 1017.63 1562.62 1013.97 1572.71C1009.01 1575.42 1007.47 1575.9 1002.23 1577.45C1001.84 1579.18 999.866 1587.86 999.167 1589.13C993.57 1599.26 980.675 1609.14 971.531 1612.79C964.457 1615.62 956.5 1617.06 950.613 1622.13C946.842 1625.37 944.629 1626.43 940.685 1628.62C922.655 1629.94 900.412 1629.59 882.299 1627.23C880.905 1627.05 874.915 1623.09 873.33 1621.79C866.105 1615.86 857.25 1616.44 849.556 1611.96C841.12 1605.1 838.963 1599.53 828.698 1592.44L827.13 1591.37C822.065 1571.64 812.359 1577.49 810.286 1567.17C804.234 1537.04 805.998 1499.68 810.072 1469.08C810.976 1462.28 824.747 1460.04 825.372 1451.3C825.524 1449.17 829.434 1441.11 830.321 1439.28C844.956 1432.83 841.818 1421.9 866.313 1420.57C872.658 1413.53 878.154 1409.22 886.485 1406.92ZM921.607 1583.91C935.442 1580.79 960.041 1568.14 968.667 1552.18C976.907 1536.94 975.131 1513.54 973.403 1495.85C972.339 1484.95 962.235 1475.21 954.929 1469.9C936.518 1456.54 924.293 1449.64 902.846 1452.55C887.903 1456.79 863.983 1470.85 855.156 1487.49C849.404 1498.33 849.568 1525.76 852.291 1538.31C859.123 1569.8 898.915 1586.37 921.607 1583.91Z"/><path fill="#FCFDFA" fill-opacity="0.0078431377" transform="scale(0.657895 0.513699)" d="M918.106 1714.94L932.512 1715.03C915.666 1733.15 943.628 1782.24 907.188 1774.06C890.102 1770.23 907.304 1741.07 891.985 1720.66L904.077 1720.62C910.271 1736.62 905.215 1758.79 911.539 1765.18C914.137 1765.85 914.507 1766.39 916.86 1765.17C918.432 1760.7 918.062 1721.96 918.106 1714.94Z"/><path fill="#FCFDFA" fill-opacity="0.011764706" transform="scale(0.657895 0.513699)" d="M720.062 1549.66C699.857 1523.53 704.394 1539.42 678.572 1530.84C674.434 1529.2 665.584 1524.33 664.236 1518.3C659.421 1496.76 680.439 1503.59 691.211 1500.5L692.452 1500.13C692.329 1506.27 693.097 1505.58 690.811 1509.76C688.609 1510.9 687.127 1511.64 685.015 1513.14C684.334 1516.91 684.195 1515.14 685.426 1518.65C696.578 1526.93 699.254 1508.6 720.061 1534.55L720.062 1549.66Z"/><path fill="#FCFDFA" fill-opacity="0.019607844" transform="scale(0.657895 0.513699)" d="M755.191 1397.57C760.123 1377.1 726.575 1358.29 731.311 1341.91C740.146 1330.2 759.395 1341.93 767.821 1349.8C764.723 1349.84 752.255 1348.91 751.004 1349.38C746.64 1362.93 769.48 1380.52 765.701 1394.77C762.583 1399.03 759.413 1398 755.191 1397.57Z"/><path fill="#FCFDFA" fill-opacity="0.015686275" transform="scale(0.657895 0.513699)" d="M1055.54 1352.23C1060.29 1348.02 1095.89 1317.74 1096.53 1348.59C1096.71 1357.68 1075.08 1367.44 1068.47 1381.56C1068.4 1379.17 1068.01 1366.71 1068.46 1365.97C1071.57 1360.91 1080.53 1354.77 1083.57 1348.7L1082.9 1347.48C1077.17 1347.26 1072.26 1350.16 1066.86 1351.87C1064.64 1352.58 1058.11 1352.31 1055.54 1352.23Z"/><path fill="#FCFDFA" fill-opacity="0.011764706" transform="scale(0.657895 0.513699)" d="M984.917 1237.19C988.185 1237.04 991.781 1236.34 994.535 1238.24C999.987 1248.96 988.479 1264.11 999.625 1268.83C1004.74 1270.99 1009.43 1264.77 1014.55 1272.95C1014.76 1275.26 1014.96 1277.42 1015.09 1279.74C1006.66 1276.96 994.448 1279.37 987.038 1271.64C978.9 1263.15 986.46 1250.33 984.917 1237.19Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M1253.16 623.019C1253.98 622.874 1254.81 622.746 1255.63 622.638C1265.86 621.352 1286.63 630.484 1297.57 634.248L1361.54 655.76C1389.37 664.767 1419.99 674.252 1447.56 683.789C1460.91 688.405 1522.95 704.254 1531 712.936C1533.22 722.276 1523.31 750.065 1517.71 755.623C1499.37 757.886 1418.97 728.504 1397.82 721.73L1322.57 697.809C1308.91 693.632 1254.42 679.339 1240.26 668.788C1234.91 664.808 1245.83 629.779 1253.16 623.019Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M1221.11 729.936C1234.55 728.556 1268.15 743.281 1282.53 747.966L1429.07 794.548C1436.02 796.835 1490.76 812.366 1495.6 818.986C1499.52 824.341 1491.9 858.215 1481.8 863.894C1472.8 863.247 1462.13 859.468 1453.14 856.922C1432.77 851.152 1412.5 843.858 1392.23 837.485L1266.18 796.838C1255.44 793.269 1216.68 783.144 1206.53 774.119C1203.46 771.388 1213.94 741.006 1215.51 736.732C1216 735.37 1219.53 731.57 1221.11 729.936Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M1364.65 542.289C1374.59 541.428 1384.52 546.956 1394.29 549.998L1528.72 593.217C1534.82 595.243 1562.3 602.958 1566.14 606.213C1567.85 613.25 1560.57 631.102 1558.69 638.974C1557.03 645.946 1555.11 647.914 1550.21 650.722C1540.01 651.968 1516.73 643.495 1505.73 640.217C1483.05 633.475 1460.4 626.538 1437.79 619.406C1419.4 613.671 1401.05 607.717 1382.74 601.546C1373.12 598.332 1362.77 595.304 1353.53 591.074C1343.67 585.427 1350.36 572.639 1353.09 564.681C1356.84 553.735 1354.94 546.983 1364.65 542.289Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M1183.57 445.429C1183.75 445.031 1183.93 444.63 1184.11 444.235C1188.44 435.003 1228.06 367.737 1234.41 365.7C1241.41 363.454 1260.58 376.673 1266.56 382.216C1268.69 384.195 1270.05 386.003 1271.36 388.916C1271.45 399.953 1213.69 493.902 1203.51 508.012C1201.92 510.204 1199.05 513.303 1196.51 512.637C1187.18 510.196 1165.9 498.188 1160.14 489.144L1159.2 487.718C1163.5 472.59 1175.78 461.172 1183.57 445.429Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M1025.66 795.317C1034.77 796.917 1047.35 818.494 1048.47 829.417C1049.93 843.786 1023.91 847.084 1019.15 855.325C1012.52 866.819 1030.87 881.325 1031.66 895.722C1028.3 906.79 1000.15 918.411 990.576 916.958C990.344 916.768 990.106 916.59 989.88 916.388C981.584 908.972 953.875 856.967 952.918 844.034C952.687 840.908 953.478 838.701 955.045 836.357C962.126 825.764 1014.73 796.387 1025.66 795.317Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M1145.19 353.769C1149.67 352.928 1153.57 352.451 1157.26 356.114C1161.56 360.38 1172.17 378.38 1172.31 384.875C1172.7 403.012 1149.33 399.456 1140.86 412.802C1139.08 427.348 1172.48 448.766 1139.63 464.236C1133.37 467.179 1128.37 470.241 1121.42 472.166C1106.09 471.778 1088.63 425.298 1081.04 409.445C1079.54 406.32 1077.53 394.99 1079.59 392.14C1092.76 373.92 1126.98 360.538 1145.19 353.769Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M1312.63 407.476C1329.07 408.886 1342.61 448.055 1351.14 463.356C1352.96 466.629 1356.68 478.218 1354.72 481.467C1341.73 503.001 1307.21 515.347 1288.07 524.3C1274.41 530.527 1275.42 517.262 1268.92 507.627C1246.35 474.124 1283.75 481.992 1292.95 463.587C1297.8 453.882 1274.96 437.404 1281.15 426.277C1286.71 417.104 1304.18 410.738 1312.63 407.476Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M1137.8 585.429C1146.5 585.192 1195.39 601.361 1201.42 607.771C1204.53 617.815 1192.83 646.743 1186.65 651.816C1168.31 647.594 1149.96 643.094 1132.1 636.014C1127.26 634.1 1123.28 631.722 1121.46 625.5C1121.99 617.838 1124.8 613.431 1126.49 606.604C1129.56 594.236 1126.59 589.365 1137.8 585.429Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M1104.71 692.572C1112.15 692.873 1164.34 709.063 1169.05 715.071C1169.92 722.815 1158.44 754.684 1153.61 760.11C1143.77 760.72 1095.49 745.315 1088.9 736.286C1088.44 734.323 1088.01 730.769 1088.87 729.032C1094.41 717.929 1095.47 698.931 1104.71 692.572Z"/><path fill="#FCFDFA" fill-opacity="0.011764706" transform="scale(0.657895 0.513699)" d="M1158.27 467.828C1167.08 456.205 1167.52 444.72 1183.57 445.429C1175.78 461.172 1163.5 472.59 1159.2 487.718C1157.59 485.609 1158.24 471.507 1158.27 467.828Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M696.549 522.808C715.602 519.486 711.546 532.22 716.583 548.941C723.564 568.098 719.877 572.93 703.906 577.441C658.216 590.347 611.458 599.323 565.611 611.277L405.228 651.115C368.479 660.14 334.944 670.641 297.246 678.755C277.94 683.408 279.004 674.865 274.377 653.7C273.107 647.892 270.799 637.799 272.848 632.303C282.444 624.531 336.034 613.671 351.333 609.708L563.989 556.736C607.855 545.915 652.841 533.176 696.549 522.808Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M882.801 593.617C902.301 590.455 899.427 608.719 906.006 626.467C910.593 638.839 899.706 644.098 892.799 646.433C873.517 652.95 852.911 657.554 833.447 662.46L722.447 691.004C701.769 696.054 669.943 702.03 650.099 709.067L648.624 709.599C647.498 709.693 646.37 709.74 645.241 709.741C633.588 709.615 632.921 699.896 630.269 687.951C628.61 680.478 625.171 669.415 626.247 661.883C634.02 654.225 850.732 604.115 882.801 593.617Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M855.301 483.966C870.84 479.593 873.339 492.484 877.045 509.056C878.484 515.488 879.827 524.902 876.768 530.733C864.949 539.519 798.939 553.475 782.592 556.887C769.424 558.555 769.847 555.693 765.388 541.794C761.671 530.205 751.5 509.433 767.737 505.133C796.72 497.458 825.999 489.196 855.301 483.966Z"/><path fill="#FCFDFA" fill-opacity="0.0078431377" transform="scale(0.657895 0.513699)" d="M552.4 49.3121C562.563 48.403 575.943 48.8638 586.315 48.8625L646.008 48.8792L825.979 48.7923L1129.48 48.8874C1188.47 48.7999 1247.53 48.9216 1306.52 48.6788C1311.7 48.6575 1317.47 48.2156 1321.22 51.8722C1322.34 54.513 1322.5 57.9433 1322.52 60.9659C1322.98 132.847 1323.48 204.9 1322.42 276.764C1322.37 279.988 1321.93 281.416 1320.33 283.71C1312.68 287.773 1247.67 263.713 1234.7 259.698C1202.04 249.592 1168.37 239.763 1135.77 229.368C1118.16 223.656 1058.56 196.7 1047.78 223.73C1030.05 268.178 1017.07 319.922 1001.67 366.344C997.045 380.269 993.673 400.94 986.992 413.237L985.386 413.137C976.713 402.555 963.367 324.889 955.24 306.417C945.843 285.059 944.826 224.723 919.099 223.833C870.943 222.168 569.241 318.2 550.835 306.8C548.418 297.418 549.16 221.903 549.149 205.446L548.911 69.2211C548.916 60.744 547.965 54.9659 552.4 49.3121Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M849.362 105.199C851.236 104.958 853.495 104.667 855.421 104.695C884.961 105.138 914.519 105.313 944.058 105.711C948.252 105.768 958.273 105.657 961.126 109.152C964.964 119.624 963.991 139.308 962.777 151.094C962.356 155.185 958.75 157.408 955.999 159.093C928.139 160.784 899.339 158.688 871.396 159.755C863.875 160.042 851.571 160.34 845.358 154.866C841.321 145.501 841.837 124.598 842.641 113.635C842.942 109.516 846.649 107.043 849.362 105.199Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M729.987 105.411C745.569 102.735 766.783 105.63 782.845 105.036C793.558 104.64 795.792 115.444 795.241 126.994C794.529 141.922 799.184 149.988 787.887 159.213C772.696 161.291 755.556 159.981 740.259 160.186C724.459 160.398 722.847 149.479 723.511 132.348C723.986 120.109 720.739 113.025 729.987 105.411Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M614.74 105.529C632.84 104.874 652.527 103.962 670.434 106.225C678.086 107.192 675.942 128.073 676.322 135.133C676.936 146.523 677.689 154.77 668.463 159.602C650.439 160.011 629.37 160.908 611.869 157.12C605.128 155.661 606.289 133.826 606.369 127.007C606.496 116.259 605.046 108.305 614.74 105.529Z"/><path fill="#FCFDFA" fill-opacity="0.0078431377" transform="scale(0.657895 0.513699)" d="M886.459 281.987C889.153 281.388 889.132 281.574 891.872 282.224C900.824 289.704 907.415 331.559 911.899 345.169C914.745 353.81 904.426 356.364 899.663 357.662C886.926 361.131 873.888 364.031 861.022 367.334L780.205 388.284L531.491 449.743L267.329 515.77C236.637 523.379 207.705 531.807 176.565 538.809C173.132 539.627 170.833 540.311 167.674 538.524C162.712 532.976 148.31 477.128 152.651 471.989C159.615 463.744 206.415 455.423 216.001 453.044L294.33 433.42L477.786 386.278L886.459 281.987Z"/><path fill="#FCFDFA" fill-opacity="0.0078431377" transform="scale(0.657895 0.513699)" d="M488.719 166.777C491.668 167.231 491.532 167.017 493.76 169.469C497.038 177.109 494.205 188.971 494.176 197.874C494.14 224.158 494.235 250.443 494.46 276.727C494.534 285.331 495.294 313.348 494.27 320.182C492.666 330.889 446.048 338.607 437.526 340.711L337.474 364.912C325.775 367.711 280.755 381.869 271.931 378.797C267.336 374.683 267.32 369.381 266.338 362.444C261.137 318.163 250.323 273.471 244.395 229.273C243.687 223.993 242.622 218.383 244.991 213.69C247.546 210.971 249.385 210.207 252.762 209.6C276.507 205.333 300.5 201.55 324.239 197.336C379.147 187.883 433.977 177.696 488.719 166.777Z"/><path fill="#FCFDFA" fill-opacity="0.0078431377" transform="scale(0.657895 0.513699)" d="M1380.74 251.953C1388.16 250.849 1399.27 254.004 1406.99 255.633C1421.9 258.818 1436.79 262.126 1451.66 265.555C1462.47 267.973 1513.34 276.217 1518.77 283.995C1518.92 288.987 1512.96 334.893 1511.74 338.767C1501.85 347.63 1484.93 339.131 1473.72 335.626C1456 330.124 1438.34 324.338 1420.74 318.27C1410.9 315.004 1389.67 309.424 1381.34 304.616C1376.51 297.937 1376.42 259.678 1380.74 251.953Z"/><path fill="#000101" transform="scale(0.657895 0.513699)" d="M822.747 727.457C827.992 725.957 846.394 719.428 850.547 723.122C857.904 729.665 867.744 759.423 862.845 769.888C853.593 778.435 828.597 779.792 813.884 786.068C790.211 791.714 757.08 802.371 732.811 802.979C726.882 803.127 719.178 764.686 720.803 757.607C724.795 750.786 756.1 745.063 763.453 743.101C783.121 737.853 803.015 732.229 822.747 727.457Z"/><path fill="#FCFDFA" fill-opacity="0.0078431377" transform="scale(0.657895 0.513699)" d="M1618.05 823.545C1644.12 832.498 1639.35 904.618 1639.27 930.357C1639.2 952.815 1631.32 949.599 1617.05 949.93C1610.85 950.074 1604.85 949.644 1598.83 949.468C1592.76 949.877 1582.52 951.424 1577.94 946.545C1575.64 935.958 1608.21 845.969 1612.57 829.38C1613.19 827.011 1616.29 824.714 1618.05 823.545Z"/><path fill="#FCFDFA" fill-opacity="0.011764706" transform="scale(0.657895 0.513699)" d="M822.747 727.457C825.334 715.214 842.081 713.357 849.964 713.295C864.938 713.177 864.263 743.906 871.671 747.907C876.225 744.058 879.731 720.223 891.543 718.868C881.87 752.501 869.155 789.687 858.409 823.874C857.638 812.462 859.708 797.797 855.964 787.804C854.709 786.499 853.544 784.919 851.786 785.101C838.923 786.437 826.836 786.811 813.884 786.068C828.597 779.792 853.593 778.435 862.845 769.888C867.744 759.423 857.904 729.665 850.547 723.122C846.394 719.428 827.992 725.957 822.747 727.457Z"/><path fill="#FCFDFA" fill-opacity="0.011764706" transform="scale(0.657895 0.513699)" d="M1036.37 929.974C1038.34 936.161 1044.02 941.477 1043.19 947.574C1027.42 953.51 913.562 948.046 892.068 948.883C889.34 948.99 882.193 947.439 879.38 946.369C878.531 942.35 889.79 903.052 891.657 898.458C891.99 909.446 894.019 929.812 889.417 937.984L889.693 939.754C898.533 942.765 917.804 941.75 927.579 941.979C963.797 942.989 1000.03 943.242 1036.25 942.738L1036.37 929.974Z"/><path fill="#FCFDFA" fill-opacity="0.0078431377" transform="scale(0.657895 0.513699)" d="M725.114 2087.2C746.255 2085.09 783.811 2086.97 806.112 2086.92L964.508 2086.38L1432.92 2086.33L1492 2085.85C1535.19 2085.63 1576.48 2088.08 1613.21 2052.11C1653.99 2012.17 1653.16 1948.08 1666.61 1890.46C1672.99 1863.13 1676.11 1835.13 1681.34 1807.46L1763.34 1392.13L1806.44 1170.89C1810.43 1150.95 1813.76 1131.32 1816.75 1111.13C1817.32 1107.3 1820.91 1102.91 1823.07 1100.16L1824 1098.99L1824 2336L0 2336L0 1998.96C2.57937 2001.92 12.4683 2025.24 14.263 2030.06C15.1264 2043.92 30.6926 2068.33 38.9784 2077.09C82.3948 2122.95 136.576 2114.4 188.813 2115.38C239.847 2116.78 290.895 2117.11 341.937 2116.37C397.829 2115.69 454.006 2111.75 509.894 2114.03C512.666 2114.14 541.821 2112.94 542.394 2112.69C561.111 2104.64 718.481 2093.78 725.114 2087.2Z"/><path fill="#FCFDFA" fill-opacity="0.027450981" transform="scale(0.657895 0.513699)" d="M14.263 2030.06L14.9919 2030.68C22.0048 2036.76 28.4268 2044.03 35.3736 2050.28C74.9808 2085.95 121.545 2082.25 167.427 2082.23L251.505 2082.19C371.175 2082.16 490.842 2083.71 610.487 2086.83C636.829 2087.48 663.853 2086.27 690.246 2086.85C700.34 2087.07 715.475 2085.97 725.114 2087.2C718.481 2093.78 561.111 2104.64 542.394 2112.69C541.821 2112.94 512.666 2114.14 509.894 2114.03C454.006 2111.75 397.829 2115.69 341.937 2116.37C290.895 2117.11 239.847 2116.78 188.813 2115.38C136.576 2114.4 82.3948 2122.95 38.9784 2077.09C30.6926 2068.33 15.1264 2043.92 14.263 2030.06Z"/></svg>
\ No newline at end of file
webui/public/skills.svg new
+4
@@ -0,0 +1,4 @@
1 +<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
2 + <path d="M7 7h10M7 11h10M7 15h6" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
3 + <path d="M5 3h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2Z" stroke="currentColor" stroke-width="2"/>
4 +</svg>
\ No newline at end of file