Simplification and readability techniques. Use when writing for broad audiences or simplifying complex content. Covers active voice, short sentences, jargon elimination, and accessibility principles from the Plain Language Movement.

2025-11-2580

pyramid-principle

stefan-jansen/claude-code-toolkit

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

2025-11-2580

shared-setup-patterns

stefan-jansen/claude-code-toolkit

Shared configuration patterns for project setup commands. Provides security hooks, Claude framework structure templates, and framework detection patterns used across multiple setup commands.

2025-11-1580

api-authentication

stefan-jansen/claude-code-toolkit

API authentication patterns including JWT, OAuth 2.0, API keys, and session-based auth. Covers token generation, validation, refresh strategies, security best practices, and when to use each pattern. Use when implementing API authentication, choosing auth strategy, securing endpoints, or debugging auth issues. Prevents common vulnerabilities like token theft, replay attacks, and insecure storage.

2025-11-0180

docker-optimization

stefan-jansen/claude-code-toolkit

Docker image optimization patterns including multi-stage builds, layer caching, security hardening, and size reduction techniques. Use when building Docker images, optimizing container size, improving build performance, or implementing Docker security best practices. Reduces image sizes by 70-90% and build times by 50-80%.

2025-11-0180

name	scqa-framework
description	Narrative structure for complex topics - Situation, Complication, Question, Answer
foundation	McKinsey SCQA framework (derived from pyramid principle)
use_case	Opening hooks, persuasive narratives, problem-solution content

SCQA Framework Skill

Foundation: McKinsey's SCQA (Situation-Complication-Question-Answer) framework, derived from Barbara Minto's pyramid principle

Core Concept: Build compelling narrative by establishing situation, introducing complication, raising question, then delivering answer.

Why This Works:

Engages reader with familiar situation
Creates tension with complication (problem)
Raises question reader now wants answered
Delivers answer with impact (reader is primed)
Natural storytelling flow

The SCQA Structure

Four elements in sequence:

1. Situation (S)

What: The stable, uncontroversial starting point everyone agrees on

Purpose: Establish common ground with reader

Example:

"Software engineers use AI coding assistants to boost productivity."

Characteristics:

Non-controversial (reader nods along)
Familiar to target audience
Sets the stage for complication

2. Complication (C)

What: The problem, change, or challenge that disrupts the situation

Purpose: Create tension and make reader care

Example:

"But generic AI agents produce unreliable code - state corruption, context loss, hallucinations. Teams abandon them after weeks of frustration."

Characteristics:

Introduces conflict/problem
Makes status quo untenable
Resonates with audience pain
Creates urgency

3. Question (Q)

What: The question reader now wants answered (often implicit)

Purpose: Focus attention on the answer you're about to provide

Example:

"How can we get AI productivity benefits without the reliability chaos?"

Characteristics:

Natural question arising from complication
What reader is now thinking
Can be explicit or implicit
Sets up your answer

4. Answer (A)

What: Your solution, recommendation, or core message

Purpose: Deliver the answer reader is now primed to receive

Example:

"CAF provides production-grade architecture that prevents AI chaos through stateless, file-based patterns proven over 6 months."

Characteristics:

Directly addresses question
This is your core message
Reader is now receptive
Rest of content supports this answer

Complete Example

Topic: Introducing CAF

Situation:

Claude Code has become a popular AI coding assistant, with developers using it daily for everything from bug fixes to feature development.

Complication:

However, Claude Code out-of-box is a generic assistant. It doesn't understand your domain, workflows, or constraints. As projects grow complex, generic responses become frustrating - developers spend more time correcting AI suggestions than coding.

Question (implicit):

How can we customize Claude Code for our specific domain without losing the ease of the IDE-based experience?

Answer:

The Claude Agent Framework (CAF) transforms Claude Code into domain-specific agents through simple markdown-based customization. Define domain commands, specialized agents, and behavioral skills - no programming required.

Variations

SCQ (Implicit Answer)

When to use: Answer is your entire document

Structure:

Situation
Complication
Question
[Your entire article/doc is the answer]

Example opening:

Situation: AI coding assistants promise productivity gains. Complication: Generic assistants don't understand domain specifics. Question: How do we customize AI for our domain?

[Rest of white paper answers this question]

SCA (Implicit Question)

When to use: Question is obvious from complication

Structure:

Situation
Complication
Answer (question implied)

Example:

Situation: Developers use AI assistants daily. Complication: But generic AI produces unreliable code - state corruption, context loss. Answer: CAF prevents this through stateless architecture.

[Implied question: "How do we prevent AI reliability issues?"]

CSA (Situation Assumed)

When to use: Audience already knows situation

Structure:

Complication (jump right to problem)
[Situation implied]
Answer

Example:

Complication: Generic AI assistants keep producing unreliable code. Answer: Domain-specific customization through CAF solves this.

[Implied situation: "We're using AI assistants"]

Application to Content Types

Application 1: Opening Hook

Use SCQA for article/document opening:

# [Title]

[Situation - 1 paragraph]
Establish the current state that readers recognize.

[Complication - 1-2 paragraphs]
Introduce the problem or challenge that disrupts equilibrium.
Make readers feel the pain.

[Question - optional, can be implicit]
What readers are now asking.

[Answer - 1 paragraph]
Your core message / solution / recommendation.
This is what the rest of the document will elaborate on.

---

[Rest of document provides evidence and detail for the answer]

Application 2: Persuasive Narrative

Structure for convincing readers:

Situation: "Here's how things are..." Complication: "But this problem exists..." Question: "So what should we do?" Answer: "We recommend [solution]"

Body: Provide evidence for answer Closing: Reinforce answer + call to action

Application 3: Problem-Solution Content

SCQA maps to problem-solution:

Situation + Complication = Problem definition
Question = Bridge to solution
Answer = Solution statement
Body = Solution elaboration

Application 4: Positioning Statement

SCQA for competitive positioning:

Situation: "Current alternatives exist (Alt A, Alt B)" Complication: "But they have these limitations..." Question: "What's needed?" Answer: "We provide [unique value] that alternatives don't"

Integration with Pyramid Principle

SCQA + Pyramid work together:

SCQA: How to structure the opening/hook (narrative flow) Pyramid: How to structure the answer and supporting arguments (hierarchical)

Combined structure:

Opening (SCQA):
├─ Situation
├─ Complication
├─ Question
└─ Answer [This is Level 1 of pyramid]

Body (Pyramid):
├─ Argument 1 supporting Answer [Level 2]
│  └─ Evidence [Level 3]
├─ Argument 2 supporting Answer [Level 2]
│  └─ Evidence [Level 3]
└─ Argument 3 supporting Answer [Level 2]
   └─ Evidence [Level 3]

Closing:
└─ Reinforce Answer + CTA

SCQA gets reader to care about your answer. Pyramid organizes proof of answer.

Crafting Effective Components

Crafting Situation

Good situation:

✅ Familiar to audience
✅ Non-controversial
✅ Concise (1 paragraph)
✅ Sets stage for complication

Bad situation:

❌ Controversial (audience disagrees)
❌ Unfamiliar (audience confused)
❌ Too long (reader loses interest)
❌ Doesn't connect to complication

Crafting Complication

Good complication:

✅ Resonates with audience pain
✅ Creates urgency
✅ Makes status quo untenable
✅ Leads naturally to question

Bad complication:

❌ Audience doesn't relate
❌ No urgency (so what?)
❌ Too dramatic (not believable)
❌ Doesn't set up your answer

Crafting Question

Good question:

✅ Natural from complication
✅ What reader is thinking
✅ Your answer addresses it
✅ Can be implicit (often better)

Bad question:

❌ Disconnected from complication
❌ Too broad or vague
❌ Your answer doesn't address it
❌ Stated explicitly when obvious

Crafting Answer

Good answer:

✅ Directly addresses question
✅ Your core message
✅ Concise and memorable
✅ Rest of content supports it

Bad answer:

❌ Doesn't answer question
❌ Vague or generic
❌ Too complex (save detail for body)
❌ Not your actual core message

Common Mistakes

Mistake 1: Starting with Complication

❌ Don't jump to problem without context:

AI coding assistants produce unreliable code...

Why: Reader doesn't have context. What AI assistants? Who's using them?

✅ Establish situation first:

Software engineers use AI coding assistants daily. But these assistants produce unreliable code...

Mistake 2: Weak Complication

❌ Complication doesn't create urgency:

Situation: Developers use AI assistants.
Complication: Sometimes the suggestions could be better.

Why: "Could be better" doesn't create enough tension.

✅ Strong complication with real pain:

Situation: Developers use AI assistants.
Complication: But 40% abandon them within weeks due to state corruption and unreliable output - wasted time, broken code, lost trust.

Mistake 3: Answer Doesn't Match Question

❌ Mismatched Q&A:

Question: How do we make AI assistants more reliable?
Answer: CAF provides markdown-based customization.

Why: Answer talks about customization, not reliability.

✅ Matched Q&A:

Question: How do we make AI assistants more reliable?
Answer: CAF prevents failures through stateless architecture and file-based persistence.

Mistake 4: Answer Too Complex

❌ Answer tries to explain everything:

Answer: CAF is a meta-framework that provides commands, agents, and skills organized in a plugin architecture with markdown-based configuration that allows...

Why: Too much detail. Save for body.

✅ Concise answer, details later:

Answer: CAF transforms Claude Code into domain-specific agents through markdown-based customization.

[Body provides details about commands, agents, skills]

Quality Checklist

When applying SCQA, verify:

Integration with Positioning

SCQA + Positioning Manifest:

From positioning manifest:

Core message = Your Answer (A)
Audience context/pain = Informs Complication (C)
Desired action = Influences how you state Answer

Example:

{
  "core_message": "CAF transforms Claude Code into domain agents",
  "audience_context": "Developers frustrated by generic AI assistants"
}

Becomes SCQA:

S: Developers use AI assistants
C: But generic assistants frustrate with domain-ignorant responses
Q: How to get domain-specific AI?
A: CAF transforms Claude Code into domain agents

References

Foundation: McKinsey's SCQA framework, derived from Barbara Minto's pyramid principle

Key insight: People engage with stories that start where they are (Situation), introduce tension (Complication), raise a question they want answered (Question), then deliver the answer (Answer).

Application: Use SCQA for openings and persuasive narratives. Use Pyramid for organizing supporting evidence.

Skill Version: 1.0 Created: 2025-10-31 Used by: author agent (optional, for narrative structure) Key Innovation: Narrative engagement that primes reader to receive core message