/gaia-storytelling

What it does

/gaia-storytelling crafts a compelling narrative using story frameworks and emotional design. It collects your audience, desired feeling, desired action, and core message, then selects a story framework (Hero's Journey, Before/After, etc.), constructs the narrative with emotional beats, and polishes with a 3-second hook test.

When to use it

• You need a compelling narrative for a product launch, investor pitch, blog post, or internal communication.
• You want to apply proven story frameworks (Hero's Journey, Before/After, etc.) to your message.
• You need a hook that grabs attention in the first three seconds and a clear call-to-action at the end.

Prerequisites

• No strict prerequisites. Works best when planning artifacts exist for context.

Orchestration mode

When /gaia-storytelling starts in subagent mode (Mode A -- the default), the framework emits a one-shot warning to your conversation. The warning text:

────────────────────────────────────────────────────────────────────────────
GAIA orchestration: running in subagent mode (Mode A)

The skill you're invoking belongs to a class (heavy-procedural or
conversational) whose output benefits from cross-step context. Mode A
dispatches each sub-agent in its own forked context, so context may
be lossy between steps — sub-agents return summaries, not full reasoning.

For the full-fidelity experience, enable Mode B (Agent Teams):
  1. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment.
  2. Add orchestration.mode: team to .gaia/config/project-config.yaml.

Mode B uses persistent teammates that preserve in-conversation state
across dispatches.

This warning is shown once per session.
────────────────────────────────────────────────────────────────────────────

Why Mode B is better for this command

The /gaia-storytelling skill declares orchestration_class: heavy-procedural in its SKILL.md frontmatter. Heavy-procedural skills produce output that benefits from cross-step context -- under Mode A every sub-agent dispatch runs in its own forked context and can only return a summary back to the orchestrator, losing the full reasoning trace of every prior step. Mode B uses persistent teammates that retain in-conversation state across dispatches, so each agent's contribution can build on what was said before instead of receiving only a summary.

How to enable Mode B

Both steps are required. If either is missing, the framework falls back silently to Mode A and the warning fires again on the next session.

Step 1 -- set the environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Add this to your shell rc file to persist across sessions, or set it in Claude Code's settings.json.

Step 2 -- add the YAML block to .gaia/config/project-config.yaml:

orchestration:
  mode: team

One-shot semantics

The warning is emitted once per Claude Code session. A marker file at _memory/checkpoints/orchestration-warning-shown.<session-id> suppresses the warning for the rest of the session. Starting a new session re-emits the warning once.

How to invoke

/gaia-storytelling Our company origin story

What it does step by step

1. Audience and purpose Collects target audience, desired feeling, desired action, and core message.
2. Framework selection Picks a story framework from the catalog based on your goals.
3. Story construction Builds the narrative with a transformation arc -- the protagonist must change state.
4. Emotional beats Maps emotional highs and lows through the narrative.
5. Polish and present Tests the 3-second hook rule and performs a read-aloud test.
6. Generate artifact Writes to .gaia/artifacts/creative-artifacts/story-{date}.md.

Inputs

Outputs

Example session

> /gaia-storytelling Our company origin story

Audience: Potential customers
Desired feeling: Trust and inspiration
Desired action: Book a demo
Core message: We built this because we lived the problem.

Framework: Founder's Journey
Hook: passes 3-second test.

Written to .gaia/artifacts/creative-artifacts/story-2026-05-07.md

What to run next

• Use the narrative in a /gaia-pitch-deck or /gaia-slide-deck presentation.
• Refine the story's emotional beats and polish the hook for your specific audience.

Troubleshooting

Topic not provided

The command asks for your topic interactively if no argument is given.

I keep seeing the GAIA orchestration warning every time I start this command

The warning is shown once per session, so if it fires again that's a new session -- not a per-skill repeat. If you want to silence it entirely, enable Mode B (full-fidelity orchestration via Agent Teams). Both of these conditions must be true:

• echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS returns 1 (not empty)
• .gaia/config/project-config.yaml contains:

  orchestration:
    mode: team

If either is missing the framework silently uses Mode A and re-emits the warning each session.

Related commands