maestro-bundle 1.7.0 → 1.9.0

package/templates/bundle-ai-agents-deep/skills/deep-agent-skills-system/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: deep-agent-skills-system
+description: Create and load skills (SKILL.md) in Deep Agents for contextual knowledge loading. Use when creating skills for your agent, loading documentation on-demand, or reducing token usage.
+version: 1.0.0
+author: Maestro
+---
+
+# Deep Agent Skills System
+
+Create SKILL.md files that your Deep Agent loads contextually — only when relevant. This reduces startup tokens while keeping the agent knowledgeable.
+
+## When to Use
+- When the agent needs domain knowledge loaded on-demand
+- When creating reusable instructions for the agent
+- When reducing context window usage
+- When organizing agent capabilities into modules
+
+## Available Operations
+1. Create SKILL.md files with frontmatter
+2. Organize skills in directories
+3. Load skills into the agent
+4. Create skills with supporting files
+
+## Multi-Step Workflow
+
+### Step 1: Create Skill Directory
+
+```bash
+mkdir -p skills/deploy/
+mkdir -p skills/code-review/
+mkdir -p skills/database-migration/
+```
+
+### Step 2: Write SKILL.md
+
+```markdown
+# skills/deploy/SKILL.md
+
+---
+name: deploy
+description: Deploy application to production
+---
+
+# Deploy Skill
+
+## Steps
+1. Run tests: `pytest --tb=short`
+2. Build Docker image: `docker build -t app:latest .`
+3. Push to registry: `docker push registry/app:latest`
+4. Update K8s: `kubectl set image deployment/app app=registry/app:latest`
+5. Verify: `kubectl rollout status deployment/app`
+
+## Rollback
+If deploy fails: `kubectl rollout undo deployment/app`
+```
+
+### Step 3: Add Supporting Files
+
+```
+skills/deploy/
+├── SKILL.md              # Main instructions
+├── references/
+│   └── k8s-commands.md   # Reference doc loaded when needed
+└── scripts/
+    └── healthcheck.sh    # Script the agent can execute
+```
+
+### Step 4: Load Skills into Agent
+
+```python
+from deepagents import create_deep_agent
+from deepagents.backends import FilesystemBackend
+from langgraph.checkpoint.memory import MemorySaver
+
+agent = create_deep_agent(
+    model="anthropic:claude-sonnet-4-6",
+    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
+    skills=["./skills/"],  # Directory containing skill folders
+    checkpointer=MemorySaver()  # Required for skills
+)
+```
+
+### Step 5: Load Skills via Store (No Filesystem)
+
+```python
+from deepagents import create_deep_agent
+from deepagents.backends import StoreBackend
+from deepagents.backends.utils import create_file_data
+from langgraph.store.memory import InMemoryStore
+
+store = InMemoryStore()
+
+# Inject skill content into store
+skill_content = open("skills/deploy/SKILL.md").read()
+store.put(
+    namespace=("filesystem",),
+    key="/skills/deploy/SKILL.md",
+    value=create_file_data(skill_content)
+)
+
+agent = create_deep_agent(
+    backend=lambda rt: StoreBackend(rt),
+    store=store,
+    skills=["/skills/"]
+)
+```
+
+### Step 6: Verify
+
+```bash
+# Test that skills are discovered
+python -c "
+from deepagents import create_deep_agent
+from deepagents.backends import FilesystemBackend
+from langgraph.checkpoint.memory import MemorySaver
+
+agent = create_deep_agent(
+    backend=FilesystemBackend(root_dir='.', virtual_mode=True),
+    skills=['./skills/'],
+    checkpointer=MemorySaver()
+)
+result = agent.invoke({
+    'messages': [{'role': 'user', 'content': 'What skills do you have available?'}]
+}, config={'configurable': {'thread_id': 'test'}})
+print(result['messages'][-1].content)
+"
+```
+
+## Resources
+- `references/skill-format.md` — SKILL.md format specification
+
+## Examples
+
+### Example 1: Create a Skill
+User asks: "Create a skill for database migrations"
+Response approach:
+1. Create `skills/database-migration/SKILL.md`
+2. Add step-by-step instructions for Alembic
+3. Add `references/alembic-commands.md`
+4. Register skill directory in agent
+
+### Example 2: Agent Uses Skill Automatically
+User asks: "Deploy the app"
+Response approach:
+1. Agent detects "deploy" matches skill description
+2. Loads `skills/deploy/SKILL.md` into context
+3. Follows the steps in the skill
+4. Reports result
+
+## Notes
+- Skills load on-demand, not at startup — saves tokens
+- `checkpointer` is REQUIRED for skills to work
+- Skill descriptions must be specific for auto-matching
+- Keep SKILL.md under 500 lines — use references for detail
+- Skills are NOT inherited by subagents — pass explicitly

package/templates/bundle-ai-agents-deep/skills/deep-agent-subagents/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: deep-agent-subagents
+description: Create and configure subagents for task delegation in Deep Agents. Use when delegating work to specialized agents, splitting complex tasks, or avoiding context bloat.
+version: 1.0.0
+author: Maestro
+---
+
+# Deep Agent Subagents
+
+Create specialized subagents that the main agent delegates tasks to via the built-in `task` tool. Subagents run in isolation with their own context window.
+
+## When to Use
+- When the main agent needs to delegate specialized work
+- When tasks would bloat the main agent's context
+- When different tasks need different models or tools
+- When building multi-agent orchestration
+
+## Available Operations
+1. Define subagent configurations
+2. Register subagents with the main agent
+3. Use different models per subagent
+4. Give subagents their own tools and skills
+
+## Multi-Step Workflow
+
+### Step 1: Define Subagent Configs
+
+```python
+# agent/subagents.py
+
+research_agent = {
+    "name": "research-agent",
+    "description": "Research topics in-depth using web search and documentation",
+    "system_prompt": "You are a thorough researcher. Always cite sources.",
+    "tools": [internet_search, read_documentation],
+    "model": "anthropic:claude-sonnet-4-6",
+}
+
+code_agent = {
+    "name": "code-agent",
+    "description": "Write, refactor, and fix code following clean architecture",
+    "system_prompt": "You are an expert programmer. Follow SOLID principles.",
+    "tools": [run_tests, lint_code],
+    "model": "anthropic:claude-sonnet-4-6",
+}
+
+review_agent = {
+    "name": "review-agent",
+    "description": "Review code for quality, security, and best practices",
+    "system_prompt": "You are a senior code reviewer. Be thorough but constructive.",
+    "tools": [lint_code, search_codebase],
+    "model": "openai:gpt-4o",  # Can use different model
+}
+```
+
+### Step 2: Register with Main Agent
+
+```python
+from deepagents import create_deep_agent
+
+orchestrator = create_deep_agent(
+    model="anthropic:claude-sonnet-4-6",
+    tools=[custom_tool],
+    subagents=[research_agent, code_agent, review_agent],
+    system_prompt="""You are an orchestrator. Delegate tasks to subagents:
+    - research-agent: for research and documentation
+    - code-agent: for writing and fixing code
+    - review-agent: for code reviews"""
+)
+```
+
+### Step 3: How Delegation Works
+
+The main agent uses the built-in `task` tool to delegate:
+
+```
+Main Agent thinks: "I need to research authentication patterns"
+Main Agent calls: task(agent="research-agent", task="Research JWT vs OAuth2 patterns")
+→ research-agent runs independently
+→ Returns summary to main agent
+Main Agent continues with the research results
+```
+
+### Step 4: Subagents with Their Own Skills
+
+```python
+code_agent = {
+    "name": "code-agent",
+    "description": "Write code following project patterns",
+    "system_prompt": "You are a coder.",
+    "tools": [run_tests],
+    "skills": ["/skills/clean-architecture/"],  # Subagent-specific skills
+}
+```
+
+### Step 5: Test
+
+```bash
+python -c "
+from deepagents import create_deep_agent
+
+research = {'name': 'researcher', 'description': 'Research topics', 'system_prompt': 'Research thoroughly.'}
+agent = create_deep_agent(subagents=[research])
+result = agent.invoke({'messages': [{'role': 'user', 'content': 'Research best practices for error handling in Python'}]})
+print(result['messages'][-1].content)
+"
+```
+
+## Resources
+- `references/subagent-patterns.md` — Common multi-agent patterns
+
+## Examples
+
+### Example 1: Research + Code Split
+User asks: "Research auth patterns, then implement JWT"
+Response approach:
+1. Orchestrator delegates research to `research-agent`
+2. Gets research summary back
+3. Delegates implementation to `code-agent` with research context
+4. Gets code back, runs tests
+
+### Example 2: Parallel Reviews
+User asks: "Review the PR from security and quality perspectives"
+Response approach:
+1. Create `security-reviewer` and `quality-reviewer` subagents
+2. Delegate both reviews simultaneously
+3. Aggregate results
+
+### Example 3: Different Models per Task
+User asks: "Use a cheaper model for simple tasks"
+Response approach:
+1. Main agent: `claude-sonnet-4-6` (reasoning)
+2. Code subagent: `claude-sonnet-4-6` (code gen)
+3. Summary subagent: `openai:gpt-4o-mini` (cheap summarization)
+
+## Notes
+- Subagents run in isolated context (no access to main agent's conversation)
+- Skills are NOT inherited — pass them explicitly to each subagent
+- Use subagents to avoid context bloat — delegate detailed work
+- The `task` tool is built-in, no need to define it
+- Each subagent can use a different model