Writing Helper

Claude Code skills that help you communicate more effectively using established communication frameworks.

Two modes: coaching (apply a framework to your draft right now) and practice (learn frameworks through deliberate exercises so you can apply them yourself).

The practice mode in this project is inspired by Dr. Cat Hicks' Learning Opportunities plugin for Claude Code. Her work applies peer-reviewed learning science to AI-assisted workflows -- showing that the conditions which make learning slower in the short term (prediction, generation, retrieval) produce better long-term retention and transfer. We adapted her techniques from the coding domain to written communication: the same risks she identified (fluency illusion, suppressed metacognition, blocked transfer) apply when AI rewrites your prose. If you're interested in evidence-based skill development with AI tools, start with her plugin and PRINCIPLES.md.

Requires Claude Code. Run these commands inside Claude Code:

/plugin marketplace add virginiais4lovers/writing-helper
/plugin install writing-helper@virginiais4lovers-writing-helper

Or just run /plugin and use the interactive Discover tab to browse and install.

Once installed, the skills are available as slash commands in any project. No need to clone this repo.

Apply a framework directly to a piece of writing you're working on:

/pyramid-principle Here's my draft email to the VP about the Q2 roadmap...
/nvc I need to give feedback to a teammate who keeps missing deadlines
/bluf [paste your draft]
/scqa I'm writing a proposal to switch our deployment process
/ladder-of-inference [paste an argument you're making]

Each skill analyzes your writing through the framework's lens, diagnoses specific issues, and suggests concrete revisions with before/after examples. If you invoke a skill without a draft, it guides you interactively.

Learn and internalize the frameworks through interactive exercises grounded in learning science:

/writing-practice pyramid
/writing-practice nvc
/writing-practice bluf

The practice skill uses evidence-based learning techniques adapted from Dr. Cat Hicks' Learning Opportunities framework (CC-BY-4.0). Instead of just applying frameworks for you, it builds genuine communication skill through:

• Prediction -- "What do you think the main issue is?" (then analyze together)
• Generation -- "Try rewriting this yourself first" (then compare)
• Reflection -- "What surprised you? What matched your intuition?"
• Self-testing -- "Explain this framework as if I'm a colleague who's never heard of it"

AI tools can rewrite your text to be clearer, but that creates a fluency illusion -- the polished output feels like understanding, but you may not be able to produce it yourself next time. The practice skill addresses this by making you do the thinking, with feedback that helps you improve.

You have writing to improve
        |
        v
  Coaching Skill (/bluf, /pyramid-principle, etc.)
  Applies framework, suggests revisions
        |
        v
  "Want to practice what we just used?"
        |
        v
  Practice Skill (/writing-practice)
  Exercises build understanding of WHY the revisions work
        |
        v
  Next time: you apply the framework independently

• Coaching skills are for when you have real writing to improve right now
• Practice skill is for when you want to learn the frameworks so you can apply them yourself
• After a coaching session, use practice to reinforce why the changes worked
• After a practice exercise, use the coaching skill on real work to apply what you learned

Not sure which framework to use?

Frameworks combine well: SCQA opening + Pyramid Principle body for proposals, NVC tone + BLUF structure for feedback that's both direct and empathetic.

writing-helper/                              # Repo root (also the marketplace)
├── .claude-plugin/
│   └── marketplace.json                     # Marketplace catalog
├── writing-helper/                          # The plugin
│   ├── .claude-plugin/
│   │   └── plugin.json                      # Plugin manifest
│   └── skills/
│       ├── ladder-of-inference/SKILL.md     # Coaching: reasoning transparency
│       ├── pyramid-principle/SKILL.md       # Coaching: top-down structure
│       ├── scqa/SKILL.md                    # Coaching: narrative framing
│       ├── bluf/SKILL.md                    # Coaching: direct communication
│       ├── nvc/SKILL.md                     # Coaching: difficult conversations
│       └── writing-practice/                # Practice: deliberate learning
│           ├── SKILL.md
│           └── resources/
│               └── PRINCIPLES.md            # Learning science foundation
├── images/                                  # Mermaid-generated SVG diagrams
├── writing-helper-spec.ipynb                # Full spec & documentation
├── CLAUDE.md
└── README.md

• Chris Argyris -- Ladder of Inference
• Barbara Minto -- Pyramid Principle, SCQA
• Marshall Rosenberg -- Nonviolent Communication
• U.S. Military / business writing tradition -- BLUF

• Dr. Cat Hicks -- Learning Opportunities framework and the learning science principles adapted here (CC-BY-4.0)
• The underlying research by Bjork, Dunlosky, Roediger, Karpicke, and others cited in PRINCIPLES.md

Learning science adaptations are based on work licensed under CC-BY-4.0 by Dr. Cat Hicks.