@musashishao/agent-kit 1.8.2 → 1.9.1

package/.agent/skills/crewai/SKILL.md

@@ -0,0 +1,470 @@
+---
+name: crewai
+description: "CrewAI multi-agent collaboration patterns. Design collaborative AI agent teams with roles, responsibilities, and delegation. Learn to create agent personas, define tasks with expected outputs, and orchestrate crews for optimal collaboration."
+version: "1.0.0"
+source: "antigravity-awesome-skills (adapted)"
+---
+
+# 🤝 CrewAI
+
+**Role**: CrewAI Multi-Agent Architect
+
+You are an expert in designing collaborative AI agent teams with CrewAI. You think in terms of roles, responsibilities, and delegation. You design clear agent personas with specific expertise, create well-defined tasks with expected outputs, and orchestrate crews for optimal collaboration.
+
+---
+
+## When to Use This Skill
+
+- Building multi-agent systems with role-based collaboration
+- Tasks requiring diverse expertise (research + writing + review)
+- Hierarchical workflows with manager delegation
+- Sequential task dependencies
+- Need structured output formats
+
+---
+
+## Capabilities
+
+- `crewai`
+- `multi-agent`
+- `role-based-agents`
+- `task-delegation`
+- `hierarchical-process`
+- `sequential-process`
+
+---
+
+## Requirements
+
+```bash
+pip install crewai crewai-tools
+```
+
+---
+
+## 1. Core Concepts
+
+### CrewAI Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         CREW                                 │
+│                                                              │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐              │
+│  │  Agent 1 │    │  Agent 2 │    │  Agent 3 │              │
+│  │Researcher│    │  Writer  │    │ Reviewer │              │
+│  └────┬─────┘    └────┬─────┘    └────┬─────┘              │
+│       │               │               │                     │
+│       ▼               ▼               ▼                     │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐              │
+│  │  Task 1  │───▶│  Task 2  │───▶│  Task 3  │              │
+│  │ Research │    │  Write   │    │  Review  │              │
+│  └──────────┘    └──────────┘    └──────────┘              │
+│                                                              │
+│  Process: sequential | hierarchical                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+| Component | Description |
+|-----------|-------------|
+| **Agent** | AI with role, goal, backstory, and tools |
+| **Task** | Work to be done with description and expected output |
+| **Crew** | Collection of agents executing tasks |
+| **Process** | Sequential (one by one) or Hierarchical (manager) |
+
+---
+
+## 2. Patterns
+
+### 2.1 Basic Crew with YAML Config
+
+Define agents and tasks in YAML (recommended approach).
+
+**config/agents.yaml**
+```yaml
+researcher:
+  role: "Senior Research Analyst"
+  goal: "Find comprehensive, accurate information on {topic}"
+  backstory: |
+    You are an expert researcher with years of experience
+    in gathering and analyzing information. You're known
+    for your thorough and accurate research.
+  tools:
+    - SerperDevTool
+    - WebsiteSearchTool
+  verbose: true
+
+writer:
+  role: "Content Writer"
+  goal: "Create engaging, well-structured content"
+  backstory: |
+    You are a skilled writer who transforms research
+    into compelling narratives. You focus on clarity
+    and engagement.
+  verbose: true
+
+reviewer:
+  role: "Quality Reviewer"
+  goal: "Ensure content is accurate, clear, and polished"
+  backstory: |
+    You are a meticulous editor who catches errors
+    and improves clarity. You never let subpar content
+    pass your review.
+  verbose: true
+```
+
+**config/tasks.yaml**
+```yaml
+research_task:
+  description: |
+    Research the topic: {topic}
+    
+    Focus on:
+    1. Key facts and statistics
+    2. Recent developments
+    3. Expert opinions
+    4. Contrarian viewpoints
+    
+    Be thorough and cite sources.
+  agent: researcher
+  expected_output: |
+    A comprehensive research report with:
+    - Executive summary
+    - Key findings (bulleted)
+    - Sources cited
+
+writing_task:
+  description: |
+    Using the research provided, write an article about {topic}.
+    
+    Requirements:
+    - 800-1000 words
+    - Engaging introduction
+    - Clear structure with headers
+    - Actionable conclusion
+  agent: writer
+  expected_output: "A polished article ready for publication"
+  context:
+    - research_task  # Uses output from research
+
+review_task:
+  description: |
+    Review the article for:
+    - Factual accuracy
+    - Grammar and style
+    - Clarity and flow
+    - Engagement
+    
+    Provide specific improvement suggestions.
+  agent: reviewer
+  expected_output: "Reviewed and improved final article"
+  context:
+    - writing_task
+```
+
+**crew.py**
+```python
+from crewai import Agent, Task, Crew, Process
+from crewai.project import CrewBase, agent, task, crew
+
+@CrewBase
+class ContentCrew:
+    agents_config = 'config/agents.yaml'
+    tasks_config = 'config/tasks.yaml'
+    
+    @agent
+    def researcher(self) -> Agent:
+        return Agent(config=self.agents_config['researcher'])
+    
+    @agent
+    def writer(self) -> Agent:
+        return Agent(config=self.agents_config['writer'])
+    
+    @agent
+    def reviewer(self) -> Agent:
+        return Agent(config=self.agents_config['reviewer'])
+    
+    @task
+    def research_task(self) -> Task:
+        return Task(config=self.tasks_config['research_task'])
+    
+    @task
+    def writing_task(self) -> Task:
+        return Task(config=self.tasks_config['writing_task'])
+    
+    @task
+    def review_task(self) -> Task:
+        return Task(config=self.tasks_config['review_task'])
+    
+    @crew
+    def crew(self) -> Crew:
+        return Crew(
+            agents=self.agents,
+            tasks=self.tasks,
+            process=Process.sequential,
+            verbose=True
+        )
+
+# Run
+crew = ContentCrew()
+result = crew.crew().kickoff(inputs={"topic": "AI in Healthcare"})
+```
+
+### 2.2 Hierarchical Process
+
+Manager agent delegates to specialized workers.
+
+```python
+from crewai import Agent, Task, Crew, Process
+from langchain_openai import ChatOpenAI
+
+# Define specialized agents
+researcher = Agent(
+    role="Research Specialist",
+    goal="Find accurate information",
+    backstory="Expert researcher with 10 years experience",
+    verbose=True
+)
+
+analyst = Agent(
+    role="Data Analyst",
+    goal="Analyze and interpret data",
+    backstory="Expert analyst who finds insights in data",
+    verbose=True
+)
+
+writer = Agent(
+    role="Content Writer",
+    goal="Create engaging content",
+    backstory="Award-winning writer with clear style",
+    verbose=True
+)
+
+# Define tasks
+research_task = Task(
+    description="Research {topic} thoroughly",
+    expected_output="Comprehensive research findings",
+    agent=researcher
+)
+
+analysis_task = Task(
+    description="Analyze the research findings",
+    expected_output="Key insights and patterns",
+    agent=analyst
+)
+
+writing_task = Task(
+    description="Write article based on research and analysis",
+    expected_output="Publication-ready article",
+    agent=writer
+)
+
+# Hierarchical crew - manager coordinates
+crew = Crew(
+    agents=[researcher, analyst, writer],
+    tasks=[research_task, analysis_task, writing_task],
+    process=Process.hierarchical,
+    manager_llm=ChatOpenAI(model="gpt-4o"),  # Manager model
+    verbose=True
+)
+
+# Manager decides:
+# - Which agent handles which part
+# - When to delegate
+# - How to combine results
+
+result = crew.kickoff(inputs={"topic": "Future of Work"})
+```
+
+### 2.3 Planning Feature
+
+Enable automatic plan generation before execution.
+
+```python
+crew = Crew(
+    agents=[researcher, writer, reviewer],
+    tasks=[research, write, review],
+    process=Process.sequential,
+    planning=True,  # Enable planning
+    planning_llm=ChatOpenAI(model="gpt-4o")
+)
+
+# With planning enabled:
+# 1. CrewAI generates step-by-step plan
+# 2. Plan is injected into each task
+# 3. Agents see overall structure
+# 4. More consistent results
+
+result = crew.kickoff()
+
+# Access the plan
+print(crew.plan)
+```
+
+### 2.4 Custom Tools
+
+```python
+from crewai_tools import BaseTool
+
+class DatabaseSearchTool(BaseTool):
+    name: str = "Database Search"
+    description: str = "Search internal database for information"
+    
+    def _run(self, query: str) -> str:
+        # Implementation
+        results = db.search(query)
+        return f"Found {len(results)} results: {results}"
+
+# Assign to agent
+researcher = Agent(
+    role="Researcher",
+    goal="Find information",
+    backstory="...",
+    tools=[DatabaseSearchTool()]
+)
+```
+
+### 2.5 Memory & Learning
+
+```python
+from crewai import Crew
+
+# Enable memory for learning across runs
+crew = Crew(
+    agents=[...],
+    tasks=[...],
+    memory=True,  # Enable memory
+    embedder={
+        "provider": "openai",
+        "config": {"model": "text-embedding-3-small"}
+    }
+)
+
+# First run - learns
+result1 = crew.kickoff(inputs={"topic": "AI"})
+
+# Second run - uses learned context
+result2 = crew.kickoff(inputs={"topic": "Machine Learning"})
+```
+
+---
+
+## 3. Anti-Patterns
+
+### ❌ Vague Agent Roles
+
+```python
+# WRONG: Too generic
+agent = Agent(
+    role="Helper",
+    goal="Help with things",
+    backstory="I help"
+)
+
+# CORRECT: Specific expertise
+agent = Agent(
+    role="Senior Financial Analyst",
+    goal="Analyze financial data to identify investment opportunities",
+    backstory="""
+    You have 15 years of experience at Goldman Sachs analyzing
+    market trends. You're known for identifying undervalued stocks
+    before they become mainstream picks. You focus on fundamentals
+    and long-term value.
+    """
+)
+```
+
+### ❌ Missing Expected Outputs
+
+```python
+# WRONG: No clear output format
+task = Task(
+    description="Research AI trends",
+    agent=researcher
+)
+
+# CORRECT: Specific output format
+task = Task(
+    description="Research AI trends in healthcare",
+    expected_output="""
+    A structured report containing:
+    - Executive Summary (3-5 sentences)
+    - Top 5 Trends (with evidence)
+    - Key Statistics (with sources)
+    - Expert Predictions (3+ experts)
+    - Potential Risks (bulleted)
+    """,
+    agent=researcher
+)
+```
+
+### ❌ Too Many Agents
+
+```python
+# WRONG: Agent for every micro-task
+crew = Crew(
+    agents=[
+        Agent(role="Title Writer"),
+        Agent(role="Introduction Writer"),
+        Agent(role="Body Writer"),
+        Agent(role="Conclusion Writer"),
+        Agent(role="Grammar Checker"),
+        Agent(role="Style Editor"),
+        # ... 10 more agents
+    ]
+)
+
+# CORRECT: Consolidated roles
+crew = Crew(
+    agents=[
+        Agent(role="Content Strategist"),
+        Agent(role="Writer"),
+        Agent(role="Editor")
+    ]
+)
+```
+
+---
+
+## 4. Best Practices
+
+### Agent Design
+| Practice | Description |
+|----------|-------------|
+| **Specific roles** | Each agent has distinct expertise |
+| **Rich backstory** | 3-5 sentences of context |
+| **Focused goal** | One clear objective |
+| **Appropriate tools** | Only tools needed for role |
+
+### Task Design
+| Practice | Description |
+|----------|-------------|
+| **Clear description** | Step-by-step what to do |
+| **Expected output** | Exact format expected |
+| **Context** | Reference dependent tasks |
+| **Single responsibility** | One outcome per task |
+
+### Crew Composition
+| Crew Size | Use Case |
+|-----------|----------|
+| 2-3 agents | Simple workflows |
+| 4-5 agents | Complex multi-step |
+| 5+ agents | Use hierarchical |
+
+---
+
+## 5. Process Comparison
+
+| Process | Best For | Pros | Cons |
+|---------|----------|------|------|
+| **Sequential** | Linear workflows | Predictable, simple | No parallelism |
+| **Hierarchical** | Complex delegation | Flexible, dynamic | Needs manager LLM |
+
+---
+
+## Related Skills
+
+- `langgraph` - Alternative graph-based agents
+- `llm-app-patterns` - LLM architecture patterns
+- `autonomous-agent-patterns` - Agent design patterns
+- `parallel-agents` - Agent orchestration patterns