Secondorderai Summon Skill Summon

Agency Skill Creator

A skill for generating bespoke, stack-aware Claude Code agent files through a progressive interview process. Each generated agent is a specialized AI persona with identity, personality, mission, critical rules, concrete code patterns, workflows, and success metrics — designed to be autonomously picked up by Claude Code from the project-local .claude/agents/ directory.

Why This Skill Exists

Generic agent templates are too broad to be useful. A "backend architect" agent that speaks Express.js is useless in a Hono + Drizzle + Cloudflare Workers codebase. This skill generates agents from first principles: it understands your stack, your conventions, your pain points, and produces agents that speak your language and enforce your standards.

How It Works

The skill follows a progressive interview flow:

1. Role Selection — What kind of specialist does the user need?
2. Stack Discovery — What technologies, patterns, and conventions define this project?
3. Domain Drilling — Role-specific questions that shape the agent's expertise
4. Generation — Produce the agent .md file with full structure
5. Composition (optional) — Generate an orchestrator agent that coordinates a team

Progressive Interview Flow

Phase 1: Role Selection

Ask the user what role they need. Present the three categories:

Engineering Roles:

• Backend Engineer
• Frontend Engineer
• Fullstack Engineer
• AI/ML Engineer
• DevOps / Infrastructure Engineer
• Data Engineer

Quality Roles:

• QA Engineer / Test Specialist
• Security Auditor
• Code Reviewer
• Performance Engineer

Product & Architecture Roles:

• System Architect
• Tech Lead
• API Designer

If the user describes something that doesn't fit these categories, derive the closest match and confirm. The categories are guidelines, not constraints — the user might want a "Database Migration Specialist" or "Observability Engineer" and that's perfectly valid.

Phase 2: Stack Discovery

After role selection, discover the project's technical context. You have two sources:

A) Project Inference (preferred first step)

Before asking questions, look at the project to infer as much as possible:

# Check for package.json, requirements.txt, go.mod, Cargo.toml, etc.
ls -la package.json pyproject.toml requirements.txt go.mod Cargo.toml 2>/dev/null

# Check framework indicators
cat package.json 2>/dev/null | grep -E '"(next|react|vue|angular|express|hono|fastify|nest)"'
cat pyproject.toml 2>/dev/null | grep -E '(fastapi|django|flask|pytorch|tensorflow)'

# Check for ORM/DB patterns
ls -la prisma/ drizzle/ alembic/ migrations/ 2>/dev/null
grep -r "DATABASE_URL" .env* 2>/dev/null | head -3

# Check cloud/infra indicators
ls -la Dockerfile docker-compose* cdk.json serverless.yml terraform/ pulumi/ 2>/dev/null
ls -la .github/workflows/ .gitlab-ci.yml 2>/dev/null

# Check for existing conventions
cat CLAUDE.md .cursorrules .windsurfrules 2>/dev/null | head -50
ls -la .claude/agents/ 2>/dev/null

Present your inferences to the user: "I can see this is a TypeScript/Node.js project using Next.js with Prisma and PostgreSQL, deployed via Docker. Is that right? Anything I'm missing?"

B) Greenfield Detection

If the project scanner returns "project_status": "greenfield" (or all detected arrays are empty), switch to greenfield mode. Tell the user:

"This looks like a fresh project — I don't see an established stack yet. Let me ask about what you're planning to build so I can create agents that help you set up right from the start."

Then replace the standard stack confirmation with these planning questions:

1. What are you building? (web app, API, CLI tool, mobile app, data pipeline, etc.)
2. What language/framework are you leaning toward? (offer popular options for the category; if they're unsure, suggest 2-3 well-matched options with brief trade-offs)
3. Any strong preferences on database, hosting, or tooling? (keep it open — don't force choices on things they haven't thought about yet)
4. Is this a solo project or a team project? (affects conventions and process recommendations)

Accept partial answers. If the user says "I'm building a web app in TypeScript but haven't picked a framework," that's enough to proceed — the agent can include recommendations.

Reference references/role-templates.md section "Greenfield Interview Adaptations" for role-specific greenfield questions.

C) Direct Questions (fill gaps)

For anything you couldn't infer (or that wasn't covered by greenfield questions), ask specifically. Focus on what's relevant to the chosen role:

• For Backend roles: Primary language, framework, ORM, database(s), message queues, caching
• For Frontend roles: Framework, styling approach (Tailwind/CSS modules/styled-components), state management, component patterns
• For AI/ML roles: ML frameworks, model serving approach, data pipeline tools, vector DBs
• For DevOps roles: Cloud provider(s), IaC tool, CI/CD platform, container orchestration
• For Quality roles: Test framework, coverage tools, CI integration, staging setup
• For Architecture roles: Service topology (monolith/microservices/modular monolith), communication patterns, deployment model

Phase 3: Domain Drilling

Now ask role-specific questions that shape the agent's behavior. These determine the agent's critical rules, workflows, and code patterns.

For Engineering roles, ask about:

• Code conventions and style (naming, file structure, import patterns)
• Error handling philosophy (Result types? Exceptions? Error boundaries?)
• Logging and observability patterns
• Testing expectations (unit? integration? e2e? coverage thresholds?)
• PR/commit conventions
• Key pain points ("what do juniors always get wrong in this codebase?")

For Quality roles, ask about:

• What kinds of bugs ship most often?
• Current test coverage and gaps
• Review bottlenecks (what takes longest in code review?)
• Security posture and compliance requirements
• Performance SLAs and budgets
• What does "production ready" mean for this project?

For Product & Architecture roles, ask about:

• System boundaries and ownership model
• Decision-making process for technical choices
• Scalability targets and current bottlenecks
• Technical debt priorities
• Cross-team integration patterns
• Documentation standards

Keep the interview focused — 3-5 questions per phase, not an interrogation. Infer what you can, confirm what you must, and ask only what you genuinely need.

Evolution & Learning Questions (ask for all roles)

After role-specific domain drilling, ask these questions to seed the team's shared knowledge:

• What mistakes keep recurring in this codebase? (seeds initial anti-patterns)
• Are there any architectural decisions that are set in stone? (seeds initial decisions)
• What patterns have proven most effective here? (seeds initial patterns)
• How important is institutional knowledge for this project? (calibrates evolution aggressiveness — solo projects need less, teams need more)

If the user provides answers, use them to pre-populate the evolution files during generation (see "Evolution Bootstrap" below).

Agent File Structure

Generate each agent as a single .md file placed in .claude/agents/. The file follows this structure (derived from the agency agents pattern but adapted for Claude Code):

---
name: {role-slug}
description: "{One-line description of what this agent handles — used for task routing}"
tools:
  - Read
  - Edit
  - Write
  - Glob
  - Grep
  - Bash
  - Agent
permissionMode: default
---

# {Role Title}

## Identity & Context

You are **{Agent Name}**, a {role description with personality and expertise}.

- **Role**: {specific role}
- **Personality**: {3-4 traits that shape communication style}
- **Expertise**: {concrete technical domains}

## Core Mission

{2-3 sentences defining what this agent exists to do. Be specific and actionable.}

## Critical Rules

{5-8 non-negotiable rules specific to this role and stack. These are the guardrails
that prevent the agent from doing harm. Written as imperative statements with the WHY
explained.}

## Stack Context

{The project's specific technology choices, baked in so the agent doesn't need to
rediscover them each session.}

## Technical Deliverables

{Concrete code patterns, templates, and examples specific to this stack. This is where
the agent's expertise becomes tangible. Include 2-4 real patterns the agent should
produce or enforce.}

## Workflow

{Step-by-step process the agent follows for its primary tasks. This is the agent's
methodology — how it approaches work, in what order, with what checkpoints.}

## Success Metrics

{How to know the agent is doing its job well. Measurable where possible.}

## Communication Style

{How the agent talks — terse? detailed? asks questions first? shows examples?
This shapes the interaction pattern.}

## Evolution

This agent improves over time by reading from and contributing to the team's shared
knowledge base at `.claude/evolution`.

### Before Starting Work

Read the relevant evolution files to inform your approach:

- Check `.claude/evolution/patterns.md` — use proven patterns instead of reinventing
- Check `.claude/evolution/anti-patterns.md` — avoid known failure modes
- Check `.claude/evolution/decisions.md` — respect prior architectural decisions
- Check `.claude/evolution/learnings.md` — leverage prior insights relevant to the task

### After Completing Work

When a task is complete (feature shipped, bug fixed, review done), capture what you learned:

1. **If you discovered a reusable pattern**, append to `.claude/evolution/patterns.md`:

[Date] [Pattern Name] (discovered by {Agent Name})

Context: When/why this pattern applies Pattern: The concrete code or approach Why it works: Brief rationale

2. **If something failed or caused problems**, append to `.claude/evolution/anti-patterns.md`:

[Date] [Anti-pattern Name] (flagged by {Agent Name})

What happened: What went wrong Root cause: Why it failed Instead do: The correct approach

3. **If you made a significant decision**, append to `.claude/evolution/decisions.md`:

[Date] [Decision Title] (decided by {Agent Name})

Context: What problem or question arose Decision: What was decided Rationale: Why this choice over alternatives Trade-offs: What was given up

4. **If you learned something non-obvious**, append to `.claude/evolution/learnings.md`:

[Date] [Learning Title] (by {Agent Name})

Situation: What task surfaced this learning Insight: The key takeaway Applies to: Which roles/tasks benefit from this

### Cross-Agent Feedback

When you notice the same issue or pattern appearing 3+ times in the evolution files,
propose a concrete change to the relevant agent's definition:
- Recurring anti-patterns → propose a new Critical Rule for the responsible agent
- Proven patterns → propose promoting to Technical Deliverables
- Tell the user: "Based on [N] learnings about [topic], I recommend updating
[Agent]'s [section]. Here's the proposed change: [diff]. Apply it?"

Never self-modify without user approval.

Greenfield Agent Variant

For greenfield projects, the agent file structure gains two additional sections:

## Recommended Setup

{Specific initialization commands, package installations, and configuration files
to create. Be concrete: "Run `npm create hono@latest`, then `npm install drizzle-orm
@hono/zod-validator`" — not "set up your framework."}

## First Steps

{Ordered list of 3-5 things to do first to establish the project foundation.
Each step should be actionable and specific to the chosen stack.}

The "Stack Context" section should describe the PLANNED stack (noting it's planned, not yet established), and "Technical Deliverables" should include starter patterns rather than patterns extracted from existing code.

Naming Convention

Agent files should be named: {category}-{role-slug}.md

Examples:

• engineering-backend-engineer.md
• quality-security-auditor.md
• architecture-system-architect.md
• quality-code-reviewer.md
• engineering-devops-engineer.md

Generating the Agent

After the interview is complete, generate the agent file following these principles:

1. Stack-specific, not generic. If the project uses Drizzle ORM, the agent should reference Drizzle patterns, not generic SQL. If it's a Next.js app, server components and app router patterns should be baked in.

2. Opinionated where the user was opinionated. If the user said "we always use Result types for error handling", the agent enforces that. If they didn't mention error handling, use sensible defaults for the stack.

3. Concrete code patterns > abstract guidance. "Use proper error handling" is useless. "Wrap all database calls in try/catch and return { success: false, error } shape" is useful. Include actual code snippets the agent should produce or enforce.

4. Personality serves function. A security auditor should be skeptical and thorough. A rapid prototyper should be pragmatic and velocity-focused. Personality isn't decoration — it shapes how the agent prioritizes and communicates.

5. Rules need reasons. "Never use any type" is weaker than "Never use any type — it defeats the purpose of TypeScript and creates silent runtime failures that are hard to trace." Explaining WHY makes the rule stick.

6. Evolution-ready. Every agent reads from and contributes to .claude/evolution, creating a compounding knowledge base. Include the Evolution section in all generated agents. The team gets smarter with every task — patterns compound, anti-patterns get caught earlier, and architectural decisions accumulate institutional memory.

7. For greenfield projects, guide instead of enforce. When the project has no established patterns, the agent should:

   • Include a "Recommended Setup" section with specific initialization steps
   • Frame rules as "establish this pattern" rather than "follow the existing pattern"
   • Include starter code templates that set conventions from the beginning
   • Offer brief rationale for stack recommendations ("Drizzle over Prisma here because...")
   • Add a "First Steps" workflow section with the 3-5 things to do first
   • Keep rules opinionated but explain trade-offs, since the user hasn't committed yet

Frontmatter Generation

Every generated agent MUST include YAML frontmatter at the top of the file. The frontmatter controls how Claude Code discovers, routes to, and constrains the agent.

---
name: {category}-{role-slug}
description: "{One-line description — Claude uses this for task routing, so be specific}"
tools:
  - Read
  - Edit
  - Write
  - Glob
  - Grep
  - Bash
  - Agent
permissionMode: default
---

Customize tools per role to enforce least-privilege:

• Engineering roles (Backend, Frontend, Fullstack, AI/ML, DevOps, Data): full tool access (Read, Edit, Write, Glob, Grep, Bash, Agent)
• Quality roles (Code Reviewer): read-heavy with limited writes (Read, Glob, Grep, Bash)
• Quality roles (QA Engineer): full access (needs to write tests) (Read, Edit, Write, Glob, Grep, Bash)
• Quality roles (Security Auditor): read-only for analysis (Read, Glob, Grep, Bash)
• Quality roles (Performance Engineer): read + execute (Read, Glob, Grep, Bash)
• Architecture roles (System Architect, Tech Lead, API Designer): read + write for docs (Read, Edit, Write, Glob, Grep, Bash)

Customize permissionMode per role:

• default — most roles (user approves edits)
• plan — architecture roles (produces plans for user approval before acting)

After generating, write the file:

mkdir -p .claude/agents
# Write the agent file
cat > .claude/agents/{filename}.md << 'AGENT_EOF'
{generated content}
AGENT_EOF

Evolution Bootstrap

After writing the agent file, initialize the shared evolution directory if it doesn't exist:

mkdir -p .claude/evolution
for f in learnings.md decisions.md patterns.md anti-patterns.md; do
  if [ ! -f ".claude/evolution/$f" ]; then
    echo "# Team ${f%.md}" > ".claude/evolution/$f"
    echo "" >> ".claude/evolution/$f"
    echo "Shared knowledge base maintained by all agents. Newest entries at the bottom." >> ".claude/evolution/$f"
    echo "" >> ".claude/evolution/$f"
  fi
done

If the user provided answers to the Evolution & Learning Questions during the interview, pre-populate the relevant evolution files with those initial entries (using today's date and attributing to "Team Setup").

Then confirm to the user: "Created .claude/agents/{filename}.md with evolution support. The team's shared knowledge base is at .claude/evolution. Claude Code will automatically pick up this agent in new sessions. Want to generate another agent or create a team?"

Multi-Agent Composition

When the user wants a team of agents, generate each specialist individually (following the full interview for each, but reuse stack context), then generate an orchestrator agent.

The Orchestrator Agent

The orchestrator is a special agent that coordinates the others. It lives at .claude/agents/orchestrator.md and:

1. Knows the roster — Lists all available agents with their specialties
2. Routes tasks — Given a task, recommends which agent(s) to activate
3. Defines handoffs — How work flows between agents (e.g., "after the backend engineer creates an API endpoint, the security auditor reviews it, then the QA engineer writes tests for it")
4. Manages conflicts — When agents have competing priorities (speed vs security, DRY vs readability), the orchestrator has a resolution framework

When generating a multi-agent team, ask the user:

• Do you want agents to learn and evolve from their work? (explain: "Agents will maintain a shared knowledge base at .claude/evolution — patterns that work, mistakes to avoid, and architectural decisions. Each agent reads from and contributes to this knowledge base, so the team gets smarter over time.")
• If yes (default), include the Evolution section in all generated agents
• If no, skip the Evolution section to keep agents simpler

Generate the orchestrator after all individual agents are created. Its structure:

---
name: orchestrator
description: "Coordinates specialized agents — routes tasks, defines workflows, manages handoffs and conflict resolution"
tools:
  - Read
  - Glob
  - Grep
  - Bash
  - Agent
permissionMode: plan
---

# Team Orchestrator

## Identity & Context

You are the **Team Orchestrator**, responsible for coordinating specialized agents
in this project. You understand each agent's strengths and route work accordingly.

## Available Agents

{List each generated agent with: name, file path, primary responsibility, when to invoke}

## Task Routing

{Decision tree or rules for which agent handles what kind of task}

## Workflow Sequences

{Common multi-agent workflows, e.g.:

- New Feature: Architect → Backend → Frontend → Code Reviewer → QA
- Bug Fix: QA (reproduce) → relevant Engineer → Code Reviewer
- Security Incident: Security Auditor → Backend → DevOps
  }

## Handoff Protocol

{How agents pass work to each other — what context to include, what to verify}

## Conflict Resolution

{When agents disagree, how to resolve — e.g., "security concerns override velocity
unless explicitly time-boxed by the user"}

## Evolution Coordination

The team maintains shared knowledge at `.claude/evolution`. As orchestrator:

- Before routing complex tasks, remind the target agent to check evolution files
- Periodically summarize evolution state (entry counts, key themes, pending feedback loops)
- When cross-agent feedback accumulates (same issue flagged 3+ times), propose agent updates
- Manage evolution file maintenance when files grow beyond ~100 entries

Important Reminders

• Always write to .claude/agents/ in the project root, never to ~/.claude/agents/
• Each agent is a standalone .md file with YAML frontmatter (name, description, tools, permissionMode)
• Keep agents under 300 lines — if they're getting longer, the scope is too broad
• The interview is a conversation, not a form. Adapt to what the user tells you.
• If the user says "just make me a code reviewer", don't ask 20 questions. Infer from the project, generate a sensible default, and ask "anything you'd change?"
• Generated agents should be immediately useful without manual editing
• Reference references/role-templates.md for role-specific interview guides and default patterns when you need deeper guidance on a particular role

Source: secondorderai/summon-skill — distributed by TomeVault.