applied-artificial-intelligence/claude-code-toolkit/pyramid-principle

Claude Code and agent skill by applied-artificial-intelligence/claude-code-toolkit

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Hierarchical content structure - answer first, then supporting arguments, then details

Install

npx vskill@latest install applied-artificial-intelligence/claude-code-toolkit/pyramid-principle

SKILL.md

Pyramid Principle Skill

Foundation: Barbara Minto's pyramid principle for clear, logical communication

Core Concept: Start with the answer, then provide supporting arguments, then add details.

Why This Works:

  • Reader gets main point immediately (respects their time)
  • Supporting structure makes logical sense
  • Details are contextualized (not lost)
  • Reader can stop at any level and still understand core idea
  • Reduces cognitive load (top-down, not bottom-up)

The Pyramid Structure

                  [ANSWER / Core Message]
                           |
        ┌──────────────────┼──────────────────┐
        |                  |                  |
   [Argument 1]      [Argument 2]      [Argument 3]
        |                  |                  |
    ┌───┼───┐          ┌───┼───┐          ┌───┼───┐
    |   |   |          |   |   |          |   |   |
  [Details] [Details] [Details] [Details] [Details] [Details]

Levels:

  1. Level 1: The answer/conclusion (what they need to know)
  2. Level 2: Major supporting arguments (why answer is true)
  3. Level 3: Evidence and examples (what proves arguments)
  4. Level 4: Details and elaboration (depth as needed)

Core Rules

Rule 1: Answer First

Always start with the conclusion

❌ Don't do this (bottom-up):

markdown
We analyzed 10 frameworks. We tested each for 6 months.
We measured productivity, reliability, and ease of use.
Framework X performed best. Therefore, we recommend Framework X.

✅ Do this (top-down):

markdown
**We recommend Framework X** because it delivers 30% higher productivity
with proven reliability over 6 months of testing.
 
Here's why:
1.Productivity: 30% improvement vs alternatives
2.Reliability: Zero critical failures in production
3.Ease of adoption: 2-week learning curve vs 2-month for alternatives

Why: Reader knows the answer immediately. Supporting details provide confidence, but aren't prerequisite to understanding recommendation.

Rule 2: Group Related Ideas

Ideas in each group must be:

  • Related to each other (same category)
  • Support the idea above them
  • At same level of abstraction

✅ Good grouping:

Core Message: "CAF transforms Claude Code into domain-specific agents"
├─ Argument 1: Customization spectrum (out-of-box → CAF → SDK)
├─ Argument 2: Domain transformation examples
└─ Argument 3: Proven patterns and constraints

❌ Bad grouping (mixed levels):

Core Message: "CAF transforms Claude Code into domain-specific agents"
├─ Argument 1: Customization spectrum
├─ Argument 2: File-based persistence (this is a detail, not major argument)
└─ Argument 3: Stefan uses it for ML4T book (this is an example, not argument)
Rule 3: Logical Order

Arguments must follow logical sequence:

Structural order: Parts of something

  • Example: "Framework has 3 components: commands, agents, skills"

Chronological order: Time sequence

  • Example: "Workflow: positioning → research → outline → draft → review"

Comparative order: Ranking or comparison

  • Example: "Benefits ranked: reliability > productivity > ease"

Problem-solution order: Issue then resolution

  • Example: "Problem: Generic AI agents fail. Solution: Domain-specific customization."

Application to Content Types

Application 1: Outlines (Architect Agent)

Structure:

markdown
# Outline
 
## Opening (Level 1: Answer)
-Hook (grab attention)
-Core message (the answer)
-Preview (what's coming)
 
## Body (Level 2: Arguments)
### Argument 1: [First supporting point]
-Evidence (Level 3)
-Examples (Level 3)
-Details (Level 4)
 
### Argument 2: [Second supporting point]
-Evidence (Level 3)
-Examples (Level 3)
-Details (Level 4)
 
### Argument 3: [Third supporting point]
-Evidence (Level 3)
-Examples (Level 3)
-Details (Level 4)
 
## Closing (Level 1: Reinforce Answer)
-Restate core message
-Call to action

Example for CAF white paper:

markdown
Opening: "Transform Claude Code into specialized domain agents"
├─ Argument 1: Customization spectrum (out-of-box → CAF → SDK)
│  ├─ Evidence: What each level provides
│  ├─ Example: Content management workflow
│  └─ Details: When to use each level
├─ Argument 2: Domain transformation mechanism
│  ├─ Evidence: How markdown customization works
│  ├─ Example: Commands, agents, skills
│  └─ Details: Technical architecture
└─ Argument 3: Proven patterns and constraints
   ├─ Evidence: 6 months production use
   ├─ Example: Specific patterns
   └─ Details: How constraints prevent failure
Closing: Reinforce transformation message + CTA
Application 2: Business Communication

Memo structure:

markdown
Subject: Recommendation
 
**Recommendation**: [The answer - one sentence]
 
**Rationale**: [3-5 supporting arguments]
1.Argument 1
2.Argument 2
3.Argument 3
 
**Details**: [Evidence for each argument]
[Expand on arguments with data, examples, elaboration]

Why this works: Executive reads first line, gets answer, decides if they need to read more.

Application 3: Technical Explanations

Explain "What is CAF?":

❌ Bottom-up (reader lost):

markdown
Claude Code has plugins. Plugins have commands. Commands invoke agents.
Agents use skills. Skills provide patterns. Patterns create frameworks.
Therefore, CAF is a meta-framework for domain-specific agent customization.

✅ Top-down (pyramid):

markdown
**CAF transforms Claude Code into domain-specific agents through markdown-based customization.**
 
How it works:
1.Commands: Encapsulate domain workflows
2.Agents: Provide specialized capabilities
3.Skills: Define behavior patterns
 
Why it matters:
-Transforms generic AI into domain-expert
-Uses simple markdown (no coding required)
-Proven patterns prevent common failures

Reader benefit: Understands "what it is" immediately, can drill into details if interested.

Common Mistakes

Mistake 1: Burying the Lede

❌ Don't hide the answer:

markdown
We conducted extensive research. We analyzed frameworks.
We tested implementations. We gathered feedback.
After 6 months, we discovered that...

✅ Answer first:

markdown
**CAF prevents AI chaos through stateless, file-based architecture.**
 
Evidence from 6 months testing:
-Zero state corruption failures
-100% reproducible results
-Context preserved across sessions
Mistake 2: Mixed Abstraction Levels

❌ Arguments at different levels:

1. Customization spectrum (high-level concept)
2. File-based persistence (implementation detail)
3. Domain transformation (high-level concept)

✅ Same level:

1. Customization spectrum (what CAF provides)
2. Domain transformation (how it works)
3. Proven patterns (why it's reliable)
Mistake 3: Illogical Order

❌ Random order:

1. Benefits
2. How it works
3. What it is

✅ Logical order:

1. What it is (establish understanding)
2. How it works (explain mechanism)
3. Benefits (show value)
Mistake 4: No Hierarchy

❌ Flat list:

- Point 1
- Point 2
- Point 3
- Point 4
- Point 5
(All at same level, no structure)

✅ Hierarchical:

Core Message
├─ Major Point 1
│  ├─ Supporting detail
│  └─ Example
├─ Major Point 2
│  ├─ Supporting detail
│  └─ Example
└─ Major Point 3
   ├─ Supporting detail
   └─ Example

Quality Checklist

When applying pyramid principle, verify:

  • [ ] Answer/conclusion stated first (Level 1)
  • [ ] 3-5 major supporting arguments identified (Level 2)
  • [ ] Each argument supports answer above it
  • [ ] Evidence/examples provided for arguments (Level 3)
  • [ ] Details elaborated as needed (Level 4)
  • [ ] Arguments grouped logically (related ideas together)
  • [ ] Arguments ordered logically (structural/chronological/comparative/problem-solution)
  • [ ] Each level is at consistent abstraction level
  • [ ] Reader can stop at any level and still understand core idea
  • [ ] No "burying the lede" (answer hidden at end)

Integration with Other Skills

Pyramid + excellent-writing:

  • Pyramid: What structure to use
  • excellent-writing: How to write clearly within that structure

Pyramid + SCQA:

  • Pyramid: Overall hierarchical structure
  • SCQA: How to structure narrative within pyramid (especially opening)

Pyramid + positioning-first:

  • Positioning: What the core message is (Level 1 of pyramid)
  • Pyramid: How to structure arguments supporting that message

References

Foundation: Barbara Minto, "The Pyramid Principle: Logic in Writing and Thinking"

Key insight: "Any intelligent reader can absorb only one thought at a time, and will automatically assume that any sentence that follows a previous one is intended to explain that thought further."

Application: Therefore, organize content to match how readers naturally process information - top-down, hierarchical, answer-first.

Skill Version: 1.0 Created: 2025-10-31 Used by: architect agent (outlines), author agent (optional) Key Innovation: Answer-first hierarchical structure that respects reader's cognitive load

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewPassed

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

Repository stars
44
Repository forks
12
7-day trend score
19

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 19 Mar 2026, 7 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/applied-artificial-intelligence/claude-code-toolkit/pyramid-principle/badge)](https://verified-skill.com/skills/applied-artificial-intelligence/claude-code-toolkit/pyramid-principle)

Something wrong with this skill or its page? Tell us.