Index of every page on this site: llms.txt
All skills
obra avatar

/writing-skills

@22f0b46 official
by Jesse Vincentobra/superpowers312k stars
27,751
Run it yourself

Use when creating new skills, editing existing skills, or verifying skills work before deployment

Use this Skill: https://skilld.dev/gh/obra/superpowers/writing-skills

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencespersuasion-principles.md

≈1.5k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Persuasion Principles for Skill Design

Overview

LLMs respond to the same persuasion principles as humans. Understanding this psychology helps you design more effective skills - not to manipulate, but to ensure critical practices are followed even under pressure.

Research foundation: Meincke et al. (2025) tested 7 persuasion principles with N=28,000 AI conversations. Persuasion techniques more than doubled compliance rates (33% → 72%, p < .001).

The Seven Principles

1. Authority

What it is: Deference to expertise, credentials, or official sources.

How it works in skills:

  • Imperative language: "YOU MUST", "Never", "Always"
  • Non-negotiable framing: "No exceptions"
  • Eliminates decision fatigue and rationalization

When to use:

  • Discipline-enforcing skills (TDD, verification requirements)
  • Safety-critical practices
  • Established best practices

Example:

✅ Write code before test? Delete it. Start over. No exceptions.
❌ Consider writing tests first when feasible.

2. Commitment

What it is: Consistency with prior actions, statements, or public declarations.

How it works in skills:

  • Require announcements: "Announce skill usage"
  • Force explicit choices: "Choose A, B, or C"
  • Use tracking: todos for checklists

When to use:

  • Ensuring skills are actually followed
  • Multi-step processes
  • Accountability mechanisms

Example:

✅ When you find a skill, you MUST announce: "I'm using [Skill Name]"
❌ Consider letting your partner know which skill you're using.

3. Scarcity

What it is: Urgency from time limits or limited availability.

How it works in skills:

  • Time-bound requirements: "Before proceeding"
  • Sequential dependencies: "Immediately after X"
  • Prevents procrastination

When to use:

  • Immediate verification requirements
  • Time-sensitive workflows
  • Preventing "I'll do it later"

Example:

✅ After completing a task, IMMEDIATELY request code review before proceeding.
❌ You can review code when convenient.

4. Social Proof

What it is: Conformity to what others do or what's considered normal.

How it works in skills:

  • Universal patterns: "Every time", "Always"
  • Failure modes: "X without Y = failure"
  • Establishes norms

When to use:

  • Documenting universal practices
  • Warning about common failures
  • Reinforcing standards

Example:

✅ Checklists without todo tracking = steps get skipped. Every time.
❌ Some people find a todo list helpful for checklists.

5. Unity

What it is: Shared identity, "we-ness", in-group belonging.

How it works in skills:

  • Collaborative language: "our codebase", "we're colleagues"
  • Shared goals: "we both want quality"

When to use:

  • Collaborative workflows
  • Establishing team culture
  • Non-hierarchical practices

Example:

✅ We're colleagues working together. I need your honest technical judgment.
❌ You should probably tell me if I'm wrong.

6. Reciprocity

What it is: Obligation to return benefits received.

How it works:

  • Use sparingly - can feel manipulative
  • Rarely needed in skills

When to avoid:

  • Almost always (other principles more effective)

7. Liking

What it is: Preference for cooperating with those we like.

How it works:

  • DON'T USE for compliance
  • Conflicts with honest feedback culture
  • Creates sycophancy

When to avoid:

  • Always for discipline enforcement

Principle Combinations by Skill Type

Skill Type Use Avoid
Discipline-enforcing Authority + Commitment + Social Proof Liking, Reciprocity
Guidance/technique Moderate Authority + Unity Heavy authority
Collaborative Unity + Commitment Authority, Liking
Reference Clarity only All persuasion

Why This Works: The Psychology

Bright-line rules reduce rationalization:

  • "YOU MUST" removes decision fatigue
  • Absolute language eliminates "is this an exception?" questions
  • Explicit anti-rationalization counters close specific loopholes

Implementation intentions create automatic behavior:

  • Clear triggers + required actions = automatic execution
  • "When X, do Y" more effective than "generally do Y"
  • Reduces cognitive load on compliance

LLMs are parahuman:

  • Trained on human text containing these patterns
  • Authority language precedes compliance in training data
  • Commitment sequences (statement → action) frequently modeled
  • Social proof patterns (everyone does X) establish norms

Ethical Use

Legitimate:

  • Ensuring critical practices are followed
  • Creating effective documentation
  • Preventing predictable failures

Illegitimate:

  • Manipulating for personal gain
  • Creating false urgency
  • Guilt-based compliance

The test: Would this technique serve the user's genuine interests if they fully understood it?

Research Citations

Cialdini, R. B. (2021). Influence: The Psychology of Persuasion (New and Expanded). Harper Business.

  • Seven principles of persuasion
  • Empirical foundation for influence research

Meincke, L., Shapiro, D., Duckworth, A. L., Mollick, E., Mollick, L., & Cialdini, R. (2025). Call Me A Jerk: Persuading AI to Comply with Objectionable Requests. University of Pennsylvania.

  • Tested 7 principles with N=28,000 LLM conversations
  • Compliance increased 33% → 72% with persuasion techniques
  • Authority, commitment, scarcity most effective
  • Validates parahuman model of LLM behavior

Quick Reference

When designing a skill, ask:

  1. What type is it? (Discipline vs. guidance vs. reference)
  2. What behavior am I trying to change?
  3. Which principle(s) apply? (Usually authority + commitment for discipline)
  4. Am I combining too many? (Don't use all seven)
  5. Is this ethical? (Serves user's genuine interests?)

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning17d5 checks · Risk MEDIUM
  • Gen Agent Trust Hub17d

    This skill provides a comprehensive framework for creating and testing AI agent skills using a Test-Driven Development (TDD) approach. It includes utilities for rendering Graphviz diagrams and methodologies for ensuring agent compliance through the use of psychological persuasion principles. Security considerations include the dynamic execution of external commands and the use of instructional patterns designed to override agent reasoning processes.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer8mo

    1/7 files flagged

  • ZeroLeaks6mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 22f0b46. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 5 days ago.

Activeupdated 3 weeks ago
  • Documentation
  • skills
  • tdd
  • test-driven-development
  • writing
  • agents
  • claude
  • patterns
  • reference
  • methodology

README badge

README badge for obra/superpowers/writing-skills

Guides skill authors through test-driven development applied to documentation: write baseline tests showing agents fail without the skill, write the skill to make tests pass, then refactor to close loopholes. Covers skill structure, discovery optimization, and token efficiency for frequently-loaded skills.

Generated from the current SKILL.md.

What's the difference between this skill and standard documentation best practices?
This skill applies test-driven development to skill authoring—you write pressure test scenarios with subagents first, watch agents fail without the skill (baseline), then write the skill to make tests pass. It's documentation built on proven compliance, not best guesses.
Do I need to read superpowers:test-driven-development before using this skill?
Yes. This skill adapts the RED-GREEN-REFACTOR cycle to documentation, so you must understand the TDD fundamentals first.
Should I create a skill for every technique or pattern I discover?
No. Create skills only when a technique wasn't intuitively obvious to you, you'd reference it across projects, and others would benefit. Don't create skills for one-off solutions, standard practices already well-documented, or project-specific conventions (use CLAUDE.md instead).
Why does the description field matter so much?
The description tells Claude whether to load the skill for a task. If you summarize the skill's workflow in the description, Claude may follow that short summary instead of reading the full skill content. Keep descriptions focused only on triggering conditions.
How long should a skill be?
Getting-started workflows should be under 150 words; frequently-loaded skills under 200 words total; other skills under 500 words. Use cross-references and tool help flags to avoid repeating details that load into every conversation.

Generated from the current SKILL.md. These answers refresh after source changes.