Initial commit

skills/build-assistant/examples.md

@@ -0,0 +1,328 @@
+# Build-Assistant - Examples
+
+## Complete Workflow Examples
+
+### Example 1: Building a New Agent from Scratch
+
+**Scenario**: Create an agent that analyzes code complexity
+
+**Steps**:
+
+1. **Read the template**
+```bash
+Read: templates/agents/agent.md.template
+```
+
+2. **Study the example**
+```bash
+Read: templates/agents/agent-example.md
+```
+
+3. **Create the agent file**
+```markdown
+---
+name: complexity-analyzer
+description: Analyzes code complexity and suggests improvements
+tools: Read, Grep, Bash
+model: claude-sonnet-4-5-20250929
+color: purple
+---
+
+You are a code complexity analyzer...
+
+## Your Process
+
+### Step 1: Scan Codebase
+...
+```
+
+4. **Validate the agent**
+```bash
+scripts/validate-agent.sh agents/complexity-analyzer.md
+# ✅ Agent validation passed
+```
+
+---
+
+### Example 2: Creating a Slash Command
+
+**Scenario**: Create a command to run complexity analysis
+
+**Steps**:
+
+1. **Read the documentation**
+```bash
+Read: docs/01-claude-code-slash-commands.md
+```
+
+2. **Read the template**
+```bash
+Read: templates/commands/command.md.template
+```
+
+3. **Create the command**
+```markdown
+---
+description: Analyze code complexity and generate report
+argument-hint: [target-directory]
+---
+
+User input: $ARGUMENTS
+
+Task
+```
+
+4. **Validate the command**
+```bash
+scripts/validate-command.sh commands/analyze-complexity.md
+# ✅ Command validation passed
+```
+
+---
+
+### Example 3: Building a Skill with Supporting Files
+
+**Scenario**: Create a skill for database design
+
+**Steps**:
+
+1. **Decide it should be a skill**
+```bash
+Read: docs/04-skills-vs-commands.md
+# Decision: Skill (automatic discovery, complex capability)
+```
+
+2. **Create directory structure**
+```bash
+mkdir -p skills/database-designer/templates
+mkdir -p skills/database-designer/scripts
+```
+
+3. **Read the template**
+```bash
+Read: templates/skills/SKILL.md.template
+```
+
+4. **Create SKILL.md**
+```markdown
+---
+name: Database Designer
+description: Design database schemas with normalization and optimization. Use when designing databases, creating schemas, or working with ERDs.
+allowed-tools: Read, Write, Bash
+---
+
+# Database Designer
+
+## Instructions
+
+1. Analyze requirements to identify entities
+2. Define relationships and cardinality
+3. Apply normalization (1NF through 3NF)
+4. Generate SQL schema files
+5. Create migration scripts
+
+## Available Resources
+
+- templates/schema.sql - SQL schema template
+- templates/migration.sql - Migration template
+- scripts/generate-erd.py - ERD diagram generator
+
+...
+```
+
+5. **Add supporting files**
+```bash
+# Create template
+Write: skills/database-designer/templates/schema.sql
+
+# Create script
+Write: skills/database-designer/scripts/generate-erd.py
+```
+
+6. **Validate the skill**
+```bash
+scripts/validate-skill.sh skills/database-designer/
+# ✅ Skill validation passed
+```
+
+---
+
+### Example 4: Building a Complete Plugin
+
+**Scenario**: Create a testing plugin with commands, agents, and skills
+
+**Steps**:
+
+1. **Read plugin documentation**
+```bash
+Read: docs/03-claude-code-plugins.md
+```
+
+2. **Study the example**
+```bash
+Read: templates/plugins/example-plugin/
+```
+
+3. **Create plugin structure**
+```bash
+mkdir -p multiagent-testing/.claude-plugin
+mkdir -p multiagent-testing/{commands,agents,skills,docs}
+```
+
+4. **Create manifest**
+```json
+{
+  "name": "multiagent-testing"
+  "version": "1.0.0"
+  "description": "Comprehensive testing tools for multiagent projects"
+  "components": {
+    "commands": 3
+    "agents": 2
+    "skills": 1
+  }
+}
+```
+
+5. **Add commands**
+```bash
+# /testing:unit
+Write: multiagent-testing/commands/unit.md
+
+# /testing:integration
+Write: multiagent-testing/commands/integration.md
+
+# /testing:e2e
+Write: multiagent-testing/commands/e2e.md
+```
+
+6. **Add agents**
+```bash
+# test-generator agent
+Write: multiagent-testing/agents/test-generator.md
+
+# test-runner agent
+Write: multiagent-testing/agents/test-runner.md
+```
+
+7. **Add skill**
+```bash
+# testing-assistant skill
+mkdir -p multiagent-testing/skills/testing-assistant
+Write: multiagent-testing/skills/testing-assistant/SKILL.md
+```
+
+8. **Create README**
+```markdown
+# multiagent-testing
+
+Comprehensive testing tools for multiagent projects.
+
+## Components
+
+- **Commands**: 3 slash commands
+- **Agents**: 2 specialized agents
+- **Skills**: 1 testing skill
+
+## Commands
+
+- `/testing:unit` - Run unit tests
+- `/testing:integration` - Run integration tests
+- `/testing:e2e` - Run end-to-end tests
+```
+
+9. **Validate the plugin**
+```bash
+scripts/validate-plugin.sh multiagent-testing/
+# ✅ Plugin validation passed
+```
+
+---
+
+### Example 5: Deciding Between Skill and Command
+
+**Scenario 1**: Git commit helper
+
+**Analysis**:
+```markdown
+Question: Should user explicitly trigger it?
+- NO - User might just ask "help me write a commit"
+
+Question: Should Claude discover automatically?
+- YES - When user mentions "commit" or "git commit"
+
+Decision: SKILL
+- Create skill with "Use when writing commit messages"
+- Claude activates when context matches
+```
+
+**Scenario 2**: Deployment workflow
+
+**Analysis**:
+```markdown
+Question: Should user explicitly trigger it?
+- YES - Deployment is critical, needs explicit control
+
+Question: Is it a sequential workflow?
+- YES - Multiple steps that user controls
+
+Decision: COMMAND
+- Create /deploy command
+- User explicitly invokes for safety
+```
+
+---
+
+### Example 6: Using Validation Scripts
+
+**Running Individual Validations**:
+
+```bash
+# Validate an agent
+scripts/validate-agent.sh agents/my-agent.md
+# ✅ Agent validation passed
+
+# Validate a command
+scripts/validate-command.sh commands/my-command.md
+# ✅ Command validation passed
+
+# Validate a skill
+scripts/validate-skill.sh skills/my-skill/
+# ⚠️  WARNING: Description should include 'Use when' trigger context
+# (Fix required)
+
+# Validate a plugin
+scripts/validate-plugin.sh plugins/my-plugin/
+# ❌ ERROR: Missing .claude-plugin/plugin.json
+# (Fix required)
+```
+
+**Running Comprehensive Tests**:
+
+```bash
+# Test entire build system
+scripts/test-build-system.sh
+# Running comprehensive build system tests...
+# ✅ All validations passed
+# ✅ All templates exist
+# ✅ All scripts executable
+```
+
+---
+
+## Quick Reference: Build Workflows
+
+### Agent Workflow
+1. Read template → 2. Study example → 3. Create agent → 4. Validate
+
+### Command Workflow
+1. Read docs → 2. Read template → 3. Create command → 4. Validate
+
+### Skill Workflow
+1. Decide vs command → 2. Read template → 3. Create skill → 4. Add resources → 5. Validate
+
+### Plugin Workflow
+1. Read docs → 2. Study example → 3. Create structure → 4. Add components → 5. Create README → 6. Validate
+
+---
+
+**Use these examples as templates when creating your own components!**