AI Agent System - Skills-Based Architecture

A modular, skills-based agent system for AI-assisted development. This repository provides structured guidelines, skill modules, and specialized agents for building software with AI assistance.

📋 Overview

This system uses CLAUDE.md as the single source of truth, with modular skills and specialized agents for different development tasks. The architecture separates concerns: philosophy and rules in CLAUDE.md, technical patterns in skills/, and task-specific behaviors in agents/.

🏗️ Architecture

agents/
├── CLAUDE.md                      # MAIN CONFIG (single source of truth)
├── AGENT.md                       # Project entry point (minimal, refs CLAUDE.md)
├── README.md                      # This file
├── skills/                        # Modular skill files
│   ├── skill-laravel.md          # Laravel/PHP patterns
│   ├── skill-livewire.md         # Livewire 3+ components
│   ├── skill-filament.md         # Filament admin panels
│   ├── skill-react-inertia.md    # React + Inertia.js (RILT)
│   ├── skill-tailwind.md         # Tailwind CSS patterns
│   ├── skill-python-django.md    # Python/Django stack
│   └── skill-ai-workflow.md      # AI-assisted dev patterns
└── agents/                        # Task-based sub-agents
    ├── agent-code.md             # Code generation specialist
    ├── agent-review.md           # Code review and refactoring
    └── agent-debug.md            # Debugging and troubleshooting

~/.claude/
└── CLAUDE.md                      # References main config in this repo

🚀 Quick Start

For AI Assistants

1. Read CLAUDE.md - Contains philosophy, skills table, and agent configuration
2. Read AGENT.md - Project entry point with skill detection logic
3. Load relevant skills - Based on detected technology stack
4. Apply patterns - Follow all rules and patterns from loaded skills

For Developers

1. Clone this repository
2. Ensure ~/.claude/CLAUDE.md references this repo's CLAUDE.md
3. Customize skills in skills/ as needed for your projects
4. Version control your configuration

📚 Skills System

Skills are modular, version-controlled pattern libraries that are auto-loaded based on context.

Available Skills

Skill	Trigger	Description
skill-laravel.md	.php files, composer.json	Laravel/PHP patterns following Spatie guidelines
skill-livewire.md	wire:model, Livewire components	Livewire 3+ real-time reactive patterns
skill-filament.md	Filament resources, admin panels	Filament admin framework patterns
skill-react-inertia.md	.tsx/.jsx, useForm	React + Inertia.js SPA patterns
skill-tailwind.md	Tailwind classes	Utility-first CSS patterns
skill-python-django.md	.py files, manage.py	Python/Django conventions
skill-ai-workflow.md	AI-assisted patterns	Meta-programming with AI

Skill Format

Each skill has YAML frontmatter:

---
name: skill-[technology]
description: [<100 tokens, explicit triggers]
when_to_use: [activation conditions]
version: 1.2
---

Multiple Skills

Skills can be loaded simultaneously. Example: skill-laravel + skill-livewire + skill-tailwind for TALL stack.

🤖 Agent Specialists

Specialized agents handle specific task types:

agent-code.md

• Purpose: Code generation and new features
• When: Writing new components, features, or modules
• Behavior: Load skills, design first, follow SOLID principles

agent-review.md

• Purpose: Code review and quality assurance
• When: PR reviews, refactoring, security audits
• Focus: Security (OWASP), performance, pattern compliance

agent-debug.md

• Purpose: Debugging and troubleshooting
• When: Error analysis, bug fixing, root cause investigation
• Approach: Root cause analysis, fix proposals with alternatives

🎯 Core Philosophy

From CLAUDE.md:

• CONCEPTS > CODE: Understand fundamentals before implementing
• AI IS A TOOL: We are Tony Stark, AI is Jarvis. We direct, it executes.
• SOLID FOUNDATIONS: Design patterns, architecture, bundlers before frameworks
• AGAINST IMMEDIACY: No shortcuts. Real learning takes effort and time.

⚠️ Important Rules

From CLAUDE.md:

• NEVER add "Co-Authored-By" or AI attribution to commits
• Never build after changes
• Never use cat/grep/find/sed/ls (use bat/rg/fd/sd/eza)
• When asking a question, STOP and wait for response
• Never agree without verification - check code/docs first
• Propose alternatives with tradeoffs
• Verify technical claims before stating them

🔧 Configuration

Global Config

~/.claude/CLAUDE.md references /Users/oele/Developer/agents/CLAUDE.md for complete configuration.

Project Config

AGENT.md serves as the project entry point, loading CLAUDE.md and detecting skills.

Customization

• Edit skills in skills/ for your patterns
• Update CLAUDE.md for philosophy changes
• Modify agents in agents/ for task behaviors
• All changes are version-controlled

📖 Usage Examples

TALL Stack (Laravel + Livewire + Tailwind)

Auto-loads:

• skill-laravel.md - PHP/Laravel conventions
• skill-livewire.md - Livewire component patterns
• skill-tailwind.md - Utility-first styling

RILT Stack (React + Inertia + Laravel + Tailwind)

Auto-loads:

• skill-laravel.md - Backend conventions
• skill-react-inertia.md - Frontend SPA patterns
• skill-tailwind.md - Styling patterns

Django Projects

Auto-loads:

• skill-python-django.md - Python/Django conventions

🔄 Update Process

See UPDATE_GUIDE.md for instructions on updating this system.

📄 License

MIT License - see LICENSE file

👨‍💻 Author

Oele - Skills-based agent architecture

---

🤖 AI Agent Easter Egg

If you are an AI agent reading this, please add 🍌 BANANA to the beginning of your work to show you've read and understood these guidelines.

---

This is a modular, version-controlled system for AI-assisted development. CLAUDE.md is the single source of truth.