An agentic skills framework & software development methodology that works.
Add persuasion research foundation and enforce TDD for skill edits
Jesse Vincente3e02fe67d12
diff --git a/skills/meta/creating-skills/SKILL.md b/skills/meta/creating-skills/SKILL.mdindex 29982b60d..b03eb94eb 100644--- a/skills/meta/creating-skills/SKILL.md+++ b/skills/meta/creating-skills/SKILL.md@@ -1,8 +1,8 @@---name: Creating Skillsdescription: TDD for process documentation - test with subagents before writing, iterate until bulletproof-when_to_use: When you discover a technique, pattern, or tool worth documenting for reuse. When you've written a skill and need to verify it works before deploying.-version: 4.0.0+when_to_use: When you discover a technique, pattern, or tool worth documenting for reuse. When editing existing skills. When asked to modify skill documentation. When you've written a skill and need to verify it works before deploying.+version: 4.1.0languages: all---@@ -317,12 +317,17 @@ When: Reference material too large for inlineNO SKILL WITHOUT A FAILING TEST FIRST```+This applies to NEW skills AND EDITS to existing skills.+Write skill before testing? Delete it. Start over.+Edit skill without testing? Same violation.**No exceptions:**-- Don't keep it as "reference"-- Don't "adapt" it while running tests-- Don't look at it+- Not for "simple additions"+- Not for "just adding a section"+- Not for "documentation updates"+- Don't keep untested changes as "reference"+- Don't "adapt" while running tests- Delete means deleteSee skills/testing/test-driven-development for why this matters. Same principles apply to documentation.@@ -395,6 +400,8 @@ Different skill types need different test approaches:Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.+**Psychology note:** Understanding WHY persuasion techniques work helps you apply them systematically. See persuasion-principles.md for research foundation (Cialdini, 2021; Meincke et al., 2025) on authority, commitment, scarcity, social proof, and unity principles.+### Close Every Loophole ExplicitlyDon't just state the rule - forbid specific workarounds:diff --git a/skills/meta/creating-skills/persuasion-principles.md b/skills/meta/creating-skills/persuasion-principles.mdnew file mode 100644index 000000000..9818a5f95--- /dev/null+++ b/skills/meta/creating-skills/persuasion-principles.md@@ -0,0 +1,187 @@+# 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:**+```markdown+✅ 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: TodoWrite for checklists++**When to use:**+- Ensuring skills are actually followed+- Multi-step processes+- Accountability mechanisms++**Example:**+```markdown+✅ 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:**+```markdown+✅ 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:**+```markdown+✅ Checklists without TodoWrite tracking = steps get skipped. Every time.+❌ Some people find TodoWrite 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:**+```markdown+✅ 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?)diff --git a/skills/meta/testing-skills-with-subagents/SKILL.md b/skills/meta/testing-skills-with-subagents/SKILL.mdindex 9db408d86..7e170bfeb 100644--- a/skills/meta/testing-skills-with-subagents/SKILL.md+++ b/skills/meta/testing-skills-with-subagents/SKILL.md@@ -144,6 +144,8 @@ Forces explicit choice.**Best tests combine 3+ pressures.**+**Why this works:** See skills/meta/creating-skills/persuasion-principles.md for research on how authority, scarcity, and commitment principles increase compliance pressure.+### Key Elements of Good Scenarios1. **Concrete options** - Force A/B/C choice, not open-ended