Imported from wyattowalsh/panel-debate-skill (
AGENTS.md). Install upstream withnpx skills add wyattowalsh/panel-debate-skill. Copyright stays with the author.
AGENTS.md - panel-debate-skill Development Guide
AI agent development instructions for the panel-debate-skill project.
Project Overview
panel-debate-skill is a Claude Code skill that hosts interactive expert panel discussions. It facilitates multi-expert debates where Claude plays the role of multiple domain experts with distinct perspectives, engaging in structured dialogue that produces actionable synthesis through Hegelian dialectic.
Key Characteristics
- Pure markdown skill: No Python/JavaScript runtime required
- Entry point: SKILL.md (contains all core logic via YAML frontmatter + markdown prompts)
- Supporting patterns: references/ directory contains reusable patterns and algorithms
- Distribution: Installable via
npx skills add - Execution model: Claude reads SKILL.md and follows embedded instructions to generate panel discussions
What Makes This Different
Unlike code-based skills, panel-debate-skill is a prompt-engineered interaction pattern. The skill file itself contains structured instructions that guide Claude through:
- Generating diverse expert personas
- Facilitating natural turn-taking dialogue
- Synthesizing insights using dialectic principles
- Producing formatted terminal output
Architecture
File Structure
panel-debate-skill/
├── SKILL.md # Main entry point (frontmatter + workflow)
├── AGENTS.md # This file
├── README.md # User-facing docs with research context
├── LICENSE # MIT License
├── .gitignore # Standard gitignore
├── references/ # Supporting pattern documentation
│ ├── expert-generation.md # Expert persona generation algorithms
│ ├── research-foundations.md # Full research citations
│ ├── turn-taking.md # Conversation flow mechanics
│ ├── synthesis-patterns.md # Hegelian dialectic synthesis templates
│ └── output-formats.md # Terminal output formatting specs
├── examples/ # Sample panel discussions
│ ├── architecture-decision.md
│ ├── business-strategy.md
│ └── security-implementation.md
└── tests/ # Testing utilities
├── quality_checklist.md
└── test_topics.md
Component Roles
SKILL.md (Core Workflow)
- YAML frontmatter defines skill metadata (name, description)
- Markdown body contains lean execution directives (~150 lines)
- Orchestrates: complexity check → expert generation → discussion → synthesis → report
- Progressive disclosure: References detailed algorithms in
references/directory - Execution-focused: Contains actionable rules, not research explanations
references/ (Pattern Library)
- Expert generation algorithms and persona templates
- Turn-taking mechanics based on adjacency pair research
- Synthesis generation using Hegelian dialectic
- Terminal UI formatting specifications
- These files are REFERENCED by SKILL.md but not executed directly
Tech Stack
Dependencies
None. This is a pure markdown skill.
Runtime Requirements
- Claude Code CLI (skill execution environment)
- Terminal with Unicode support (for box-drawing characters)
- No Python, Node.js, or other runtimes
Formats Used
- YAML: Frontmatter in SKILL.md for metadata
- Markdown: All content, instructions, and examples
- Unicode: Box-drawing characters for terminal UI
Code Style Guidelines
Prompt Engineering Principles
1. Be Direct, Not Hedging
Bad:
You might want to consider generating around 3-5 experts, depending on the topic.
Good:
Generate 3-5 experts based on topic breadth:
- Narrow topics: 3-4 experts
- Medium topics: 4-5 experts
- Broad topics: 5-7 experts
2. Use Concrete Examples Over Abstract Descriptions
Bad:
Experts should have diverse perspectives that create productive tension.
Good:
Include these perspective archetypes:
- Optimist: "This technology could reduce costs by 40%"
- Skeptic: "We've seen 3 similar initiatives fail. What makes this different?"
- Pragmatist: "Given our Q2 deadline, we should start with MVP approach"
3. Expert Personas Should Feel Authentic
Bad:
Expert 1: Technology Person
Expert 2: Business Person
Good:
Dr. Sarah Chen (Principal Security Architect)
- 15 years in application security, formerly at Stripe
- Perspective: Risk-averse specialist
- Typical concerns: "What's the attack surface?" "How do we prevent lateral movement?"
4. Synthesis Should Be Actionable, Not Wishy-Washy
Bad:
Both approaches have merit. It depends on your situation.
Good:
Choose microservices if:
- You have >50 developers
- Services scale independently (measured via resource utilization)
- Teams are blocked by monolith deployment freezes
Choose modular monolith if:
- Team <50 developers
- Shared database is acceptable
- Deploy frequency <10x/day
Markdown Style
- Headings: Use ATX style (
##not underlines) - Code blocks: Always specify language (
yaml,markdown, etc.) - Lists: Use
-for bullets,1.for numbered (auto-increment) - Emphasis:
**bold**for key terms,*italic*for emphasis - Line length: Aim for 80-100 chars in prose, hard wrap at 120
Example Quality Standards
Bad example (too abstract):
Experts should engage in dialogue that explores multiple perspectives.
Good example (concrete, actionable):
## Round 1 Structure
1. Moderator poses question to most relevant expert
2. Expert provides 3-5 sentence response with specific claim
3. Second expert responds using one of these patterns:
- Challenge: "I see it differently because [evidence]"
- Build: "Adding to that point, [extension]"
- Question: "How would that work when [edge case]?"
4. First expert responds to challenge/question
5. Third expert synthesizes or adds new angle
Testing Instructions
Manual Testing
Install the skill:
cd /Users/ww/dev/projects/panel-skill
npx skills add ./
Test basic trigger:
# In Claude Code CLI
/panel-debate "Should we use microservices?"
Test argument parsing:
/panel-debate size:4 depth:deep "Should we migrate to Kubernetes?"
/panel-debate style:adversarial "GraphQL vs REST?"
Test low-complexity warning:
/panel-debate "What port does PostgreSQL use?"
Expected: Warning about low complexity, option to proceed or cancel
Verify output quality:
- Check that 3-5 experts are generated with distinct perspectives
- Verify turn-taking feels natural (not robotic)
- Confirm synthesis blocks appear after rounds
- Ensure final output is actionable (not "it depends" without specifics)
- Validate terminal formatting (box characters render correctly)
Test Cases
1. Technical Architecture Question
/panel-debate "Should we migrate from PostgreSQL to MongoDB?"
Expected: 3-4 experts (DB specialist, backend engineer, data analyst, ops)
2. Broad Strategic Question
/panel-debate "Should we implement a 4-day work week?"
Expected: 5-7 experts (HR, economist, employee advocate, productivity researcher, CEO perspective)
3. Narrow Implementation Question
/panel-debate "Should we use GraphQL or REST for our API?"
Expected: 3 experts (backend specialists with different takes)
4. Values-Based Question
/panel-debate "Should we collect user analytics data?"
Expected: Tension between privacy advocate and business strategist, context-dependent synthesis
Validation Checklist
After running a test panel:
- Experts have realistic names and backgrounds
- At least one contrarian/skeptic present
- At least one synthesizer present
- Perspectives create productive tension (not echo chamber)
- Turn-taking feels conversational (not scripted)
- Synthesis blocks use correct format (📋, bullet points)
- Final recommendations are specific and actionable
- Dissenting views are preserved (not falsely consensus-building)
- Output renders correctly in terminal (Unicode box chars)
- Discussion length is appropriate (not too brief, not too verbose)
Key Patterns
Expert Generation Pattern
See: references/expert-generation.md
Key algorithm:
- Analyze topic → extract domain keywords
- Classify breadth (narrow/medium/broad) → determine panel size
- Identify stakeholder angles → map to expert roles
- Ensure diversity: contrarian + synthesizer + specialist (minimum)
- Generate personas with authentic backgrounds
Critical rule: No more than 2 experts with same primary perspective archetype.
Turn-Taking Pattern
See: references/turn-taking.md
Based on multi-agent debate research (Du et al., ICML 2024; PanelGPT, Sun et al., 2023):
- Self-selection triggers (relevance, disagreement, building)
- Moderator orchestration (balance participation, redirect tangents)
- User intervention points (natural pauses for questions)
- Adaptive patterns (opening round, discussion rounds, synthesis round, closing)
Critical rule: Every expert speaks at least once per round.
Synthesis Pattern
See: references/synthesis-patterns.md
Hegelian dialectic structure:
- Thesis: Initial expert position
- Antithesis: Challenging perspective
- Synthesis: Higher-order integration (not compromise, but emergence)
Per-round synthesis includes:
- Agreements (explicit and convergent)
- Productive tensions (with nature of disagreement)
- Open questions (with resolution paths)
- Emerging insights (hidden assumptions, reframings)
Critical rule: Avoid "wishy-washy" synthesis. If context-dependent, specify the context factors.
Output Format Pattern
See: references/output-formats.md
Terminal UI specifications:
- Panel header with rounded box (
╭─╮╰─╯) - Speaker turns with 🎤 emoji and quoted content
- Synthesis blocks with 📋 emoji and categorized bullets
- Final report with double-line box (
╔═╗╚═╝) - User intervention menus at natural pause points
Critical rule: Follow exact formatting for consistency. Don't improvise UI elements.
Development Workflow
Making Changes to SKILL.md
- Read current SKILL.md to understand existing flow
- Identify what needs to change (expert generation, turn-taking, synthesis, formatting)
- Update SKILL.md with clear, directive prompts
- Test with diverse topics to ensure changes work across scenarios
- Update reference docs if you've changed algorithms
- Commit with descriptive message explaining the improvement
Adding New Reference Patterns
- Create new .md file in references/ with descriptive name
- Follow reference doc structure:
- Overview section
- Algorithm/template sections
- Examples section
- Anti-patterns section
- Reference from SKILL.md if it's part of core workflow
- Add to this AGENTS.md under "Key Patterns"
Prompt Tuning Principles
When revising prompts in SKILL.md:
- Specificity over generality: "Generate 4 experts" > "Generate several experts"
- Examples over descriptions: Show don't tell
- Decision trees over fuzzy logic: If X then Y, else Z
- Concrete over abstract: "15ms latency" > "some overhead"
- Imperative over suggestive: "Include a contrarian" > "Consider adding a contrarian"
Common Issues and Solutions
Issue: Experts All Agree Too Easily
Symptom: Panel reaches consensus in Round 1 without tension.
Solution:
- Strengthen contrarian requirement in expert generation
- Add explicit instruction: "Experts MUST disagree on at least 2 points"
- Review expert archetypes: ensure Skeptic + Contrarian are present
Issue: Synthesis Is Too Abstract
Symptom: Synthesis says "it depends" without specifying dependencies.
Solution:
- Add template requiring context factors
- Strengthen anti-pattern warnings in synthesis instructions
- Reference good vs bad examples from synthesis-patterns.md
Issue: Turn-Taking Feels Scripted
Symptom: Each expert speaks in rigid order, no natural flow.
Solution:
- Emphasize self-selection triggers in instructions
- Add examples of natural interruptions and building
- Reduce moderator orchestration (only intervene for balance)
Issue: Terminal Formatting Breaks
Symptom: Box characters don't render, or layout is misaligned.
Solution:
- Verify Unicode support in terminal
- Check box character usage against output-formats.md reference
- Provide ASCII fallback option for limited terminals
Contributing Guidelines
Before Submitting Changes
- Keep SKILL.md as single entry point: Don't split core logic into multiple files
- Reference docs support but don't replace: SKILL.md should work standalone
- Test with diverse topics: Try technical, strategic, ethical, and implementation questions
- Verify output quality: Run validation checklist
- Update AGENTS.md: Document new patterns or changes
Pull Request Checklist
- SKILL.md changes are clear and directive (not vague)
- SKILL.md body ≤ 200 lines
- Reference file loading instructions present
- Changes tested with at least 3 different topic types
- Reference docs updated if algorithms changed
- AGENTS.md updated if new patterns added
- No regression in output quality (run test cases)
- Terminal formatting validated (Unicode renders correctly)
Code Review Focus Areas
When reviewing PRs:
- Prompt clarity: Are instructions specific and actionable?
- Example quality: Do examples feel authentic, not generic?
- Anti-pattern avoidance: Does it avoid wishy-washy synthesis?
- Format consistency: Does it follow output-formats.md exactly?
- Edge case handling: What if topic is very narrow? Very broad? Values-based?
Performance Considerations
Token Efficiency
panel-debate-skill is relatively token-heavy due to:
- Multiple expert personas (each with background)
- Extended dialogue (multiple rounds)
- Comprehensive synthesis
- Detailed final reports
Optimization strategies:
- Limit panel size based on topic breadth (don't use 7 experts for narrow questions)
- End discussion after 2-3 rounds if consensus is clear
- Use concise expert turns (3-5 sentences, not paragraphs)
- Skip final report if user just wants quick discussion
Response Time
Streaming output improves perceived performance:
- Show expert turns incrementally (word-by-word or sentence-by-sentence)
- Display synthesis blocks immediately when ready
- Don't wait for entire discussion before showing first turn
AI Agent Configuration
When AI agents work on panel-debate-skill, they should be aware of these configuration requirements:
Model Recommendations
| Task Type | Recommended Model | Reasoning |
|---|---|---|
| SKILL.md edits | sonnet/opus | Complex prompt engineering |
| Reference docs | haiku/sonnet | Straightforward content |
| Examples | haiku | Template-based |
| Research alignment | sonnet | Requires nuance |
Parallel Execution
Panel-skill updates benefit from parallel agent execution:
Wave 1 (can run in parallel):
- SKILL.md research sections
- Pre-commit configs
- GitHub workflows
Wave 2 (can run in parallel):
- README
- Issue templates
- Community docs
Wave 3 (depends on Wave 1):
- Examples (need final SKILL.md format)
- Tests (need final structure)
Quality Gates
Before completing work on panel-debate-skill, verify:
- Research alignment: Changes cite supporting research
- Diversity enforcement: Panel composition rules followed
- Contrarian protection: Dissent mechanisms intact
- Confidence weighting: Synthesis uses weighted positions
- Complexity screening: Low-complexity rejection works
Testing Protocol
After making changes:
# Install locally
npx skills add ./
# Test complexity rejection
/panel-debate "What port does PostgreSQL use?"
# Test standard panel
/panel-debate "Redis vs Memcached?"
# Test deep panel
/panel-debate depth:deep "Microservices migration strategy"
Debugging
Enable Verbose Mode
To understand what's happening:
- Add debug comments in SKILL.md temporarily
- Output expert persona YAML before starting discussion
- Show self-selection reasoning ("Speaking because: relevance to my domain")
Common Failure Modes
All experts are the same archetype
- Check: Are archetypes explicitly varied in generation step?
Discussion goes off-topic
- Check: Is moderator redirecting after 3+ off-topic turns?
Synthesis doesn't capture disagreements
- Check: Is synthesis algorithm categorizing tensions vs agreements?
Final report is too long
- Check: Are we synthesizing across rounds, not just concatenating?
Future Enhancements
Potential additions to panel-debate-skill:
- Multi-round deep dives: Allow user to select one tension and spawn new panel
- Expert persistence: Reuse expert panel across related questions
- Visualization: ASCII diagrams showing agreement/disagreement topology
- Export formats: Markdown, PDF, or structured JSON output
- Skill composition: Chain panel-debate-skill output into other skills
When implementing:
- Maintain pure markdown approach (no code dependencies)
- Keep SKILL.md as single entry point
- Preserve output format consistency
- Test extensively before merging
Resources
Internal References
references/expert-generation.md: Persona creation algorithmsreferences/turn-taking.md: Conversation flow mechanicsreferences/synthesis-patterns.md: Dialectic synthesis methodsreferences/output-formats.md: Terminal UI specifications
Research Foundations
The panel-debate-skill design is grounded in peer-reviewed multi-agent debate research:
| Paper | Key Finding | Implementation |
|---|---|---|
| Du et al. (ICML 2024) | Multiple rounds improve factuality | 2-3 round default |
| Wu et al. (Nov 2025) | Diversity is THE dominant driver | Diversity score ≥60 |
| Wu et al. (Nov 2025) | Majority suppresses correction | Contrarian protection |
| A-HMAD (Nov 2025) | Heterogeneous > homogeneous | Max 30% same-archetype |
| CISC (ACL 2025) | Confidence weighting helps | Weighted synthesis |
| ICLR 2025 MAD Analysis | MAD helps complex, not simple | Complexity classifier |
See references/research-foundations.md for comprehensive citations.
Philosophical Foundations
- Hegelian Dialectic (thesis, antithesis, synthesis)
- Socratic Method (productive disagreement techniques)
- Six Thinking Hats (structured perspective-taking)
- Belbin Team Roles (team composition diversity)
Related Skills
/commitskill: Git commit workflow/review-prskill: Pull request review/planskill: Project planning
panel-debate-skill focuses on decision-making through expert dialogue.
