القائمة
Use when creating new protocols, editing existing protocols, or validating protocols work before deployment
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when starting any conversation - establishes how to locate and invoke skills, mandating Skill tool usage before ANY response including clarifying questions
Use when building ANY website, web app, landing page, or web-based UI - searches real template marketplaces for professionally designed layouts in the user's industry or niche, then extracts layout structure, color palettes, typography choices, and section sequences as the design blueprint instead of generating from assumptions
Use when about to build any feature, library, or system - searches GitHub and package registries for existing implementations to study, harvest patterns from, or use directly instead of building from scratch
Use when starting any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements, and design before implementation.
Use when making technology, hosting, or infrastructure decisions — recommends services, databases, and deployment strategies based on project requirements and what the user actually has available
Use when starting a session, running shell commands, installing packages, or diagnosing platform-specific failures - detects OS, shell, runtime, package manager, and toolchain before any command execution
| name | protocol-authoring |
| description | Use when creating new protocols, editing existing protocols, or validating protocols work before deployment |
Authoring protocols IS Test-Driven Development applied to process documentation.
Personal protocols live in agent-specific directories (~/.claude/skills for Claude Code, ~/.agents/skills/ for Codex)
You design test scenarios (pressure-based exercises with subagents), observe failure (baseline behavior), author the protocol (documentation), observe compliance (agents follow the protocol), and harden (seal loopholes).
Core principle: If you never observed an agent fail without the protocol, you cannot know what the protocol needs to prevent.
REQUIRED BACKGROUND: You MUST understand godmode:test-first before using this skill. That skill defines the foundational RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
A protocol is a reference guide for proven techniques, patterns, or tools. Protocols help future Claude instances discover and apply effective approaches.
Protocols are: Reusable techniques, patterns, tools, reference guides
Protocols are NOT: Narratives about how you solved something once
| TDD Concept | Protocol Creation |
|---|---|
| Test case | Pressure scenario with subagent |
| Production code | Protocol document (SKILL.md) |
| Test fails (RED) | Agent breaks rule without protocol (baseline) |
| Test passes (GREEN) | Agent complies when protocol is present |
| Refactor | Seal loopholes while maintaining compliance |
| Write test first | Run baseline scenario BEFORE authoring protocol |
| Watch it fail | Record exact rationalizations the agent uses |
| Minimal code | Author protocol addressing those specific violations |
| Watch it pass | Confirm agent now complies |
| Refactor cycle | Discover new rationalizations, plug them, re-verify |
The entire protocol creation process follows RED-GREEN-REFACTOR.
Create when:
Do not create for:
Concrete method with steps to follow (event-based-waiting, root-cause-tracing)
Cognitive framework for approaching problems (flatten-with-flags, test-invariants)
API documentation, syntax guides, tool documentation (office docs)
skills/
protocol-name/
SKILL.md # Primary reference (required)
supporting-file.* # Only when necessary
Flat namespace — all protocols in one searchable namespace
Separate files for:
Keep inline:
Frontmatter (YAML):
name and descriptionname: Letters, numbers, and hyphens only (no parentheses or special characters)description: Third-person, describes ONLY when to use (NOT what it does)
---
name: Protocol-Name-With-Hyphens
description: Use when [specific trigger conditions and symptoms]
---
# Protocol Name
## Overview
What is this? Core principle in 1-2 sentences.
## When to Use
[Small inline flowchart IF decision non-obvious]
Bullet list with SYMPTOMS and use cases
When NOT to use
## Core Pattern (for techniques/patterns)
Before/after code comparison
## Quick Reference
Table or bullets for scanning common operations
## Implementation
Inline code for simple patterns
Link to file for dense reference or reusable tools
## Common Mistakes
What goes wrong + fixes
## Real-World Impact (optional)
Concrete results
Critical for visibility: Future Claude instances must FIND your protocol.
Purpose: Claude reads the description to decide which protocols to load. Make it answer: "Should I read this protocol right now?"
Format: Start with "Use when..." focusing on trigger conditions.
CRITICAL: Description = When to Use, NOT What the Protocol Does
The description should ONLY describe trigger conditions. Do NOT summarize the protocol's workflow.
Why this matters: Testing revealed that when a description summarizes the workflow, Claude may follow the description instead of reading the full protocol. A description mentioning "review between tasks" caused Claude to perform ONE review, even though the protocol's flowchart clearly showed TWO reviews (spec compliance then code quality).
When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), Claude correctly read the flowchart and followed the two-stage review process.
The trap: Descriptions that summarize workflow create a shortcut Claude will take. The protocol body becomes documentation Claude skips.
# BAD: Summarizes workflow - Claude may follow this instead of reading protocol
description: Use when executing plans - launches subagent per task with review between tasks
# BAD: Too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor
# GOOD: Just trigger conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session
# GOOD: Trigger conditions only
description: Use when implementing any feature or bugfix, before writing implementation code
Content:
# BAD: Too abstract, vague, no trigger conditions
description: For async testing
# BAD: First person
description: I can help you with async tests when they're flaky
# BAD: Mentions technology but protocol isn't specific to it
description: Use when tests use setTimeout/sleep and are flaky
# GOOD: Starts with "Use when", describes problem, no workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
# GOOD: Technology-specific protocol with explicit trigger
description: Use when using React Router and handling authentication redirects
Use words Claude would search for:
Use active voice, verb-first:
creating-protocols not protocol-creationevent-based-waiting not async-test-helpersGerunds (-ing) work well for processes:
creating-protocols, validating-protocols, debugging-with-logsProblem: Getting-started and frequently-referenced protocols load into EVERY conversation. Every token counts.
Target word counts:
Techniques:
Defer details to tool help:
# BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
# GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.
Use cross-references:
# BAD: Repeat workflow details
When searching, dispatch subagent with template...
[20 lines of repeated instructions]
# GOOD: Reference other protocol
Always use subagents (50-100x context savings). REQUIRED: Use [other-protocol-name] for workflow.
Compress examples:
# BAD: Verbose example (42 words)
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]
# GOOD: Minimal example (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent -> synthesis]
Eliminate redundancy:
Verification:
wc -w skills/path/SKILL.md
# getting-started workflows: aim for <150 each
# Other frequently-loaded: aim for <200 total
Name by what you DO or the core insight:
event-based-waiting > async-test-helpersusing-protocols not protocol-usageflatten-with-flags > data-structure-refactoringroot-cause-tracing > debugging-techniquesWhen writing documentation that references other protocols:
Use protocol name only, with explicit requirement markers:
**REQUIRED SUB-PROTOCOL:** Use godmode:test-first**REQUIRED BACKGROUND:** You MUST understand godmode:fault-diagnosisSee skills/testing/test-first (unclear if required)@skills/testing/test-first/SKILL.md (force-loads, burns context)Why no @ links: @ syntax force-loads files immediately, consuming 200k+ context before you need them.
digraph when_flowchart {
"Need to show information?" [shape=diamond];
"Decision where I might go wrong?" [shape=diamond];
"Use markdown" [shape=box];
"Small inline flowchart" [shape=box];
"Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
"Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
"Decision where I might go wrong?" -> "Use markdown" [label="no"];
}
Use flowcharts ONLY for:
Never use flowcharts for:
See graphviz-conventions.dot in this directory for graphviz style rules.
Visualizing for your human partner: Use render-graphs.js in this directory to render a protocol's flowcharts to SVG:
./render-graphs.js ../some-protocol # Each diagram separately
./render-graphs.js ../some-protocol --combine # All diagrams in one SVG
One outstanding example beats many mediocre ones
Choose the most relevant language:
Strong example:
Avoid:
You are skilled at porting — one strong example is sufficient.
defense-in-depth/
SKILL.md # Everything inline
When: All content fits, no dense reference needed
event-based-waiting/
SKILL.md # Overview + patterns
example.ts # Working helpers to adapt
When: Tool is reusable code, not just narrative
pptx/
SKILL.md # Overview + workflows
pptxgenjs.md # 600 lines API reference
ooxml.md # 500 lines XML structure
scripts/ # Executable tools
When: Reference material too large for inline
NO PROTOCOL WITHOUT A FAILING TEST FIRST
This applies to NEW protocols AND EDITS to existing protocols.
Author before testing? Delete it. Start over. Edit without testing? Same violation.
No exceptions:
REQUIRED BACKGROUND: The godmode:test-first protocol explains why this matters. Same principles apply to documentation.
Different protocol types require different test approaches:
Examples: TDD, completion-gate, design-before-coding
Test with:
Success criteria: Agent follows the rule under maximum pressure
Examples: event-based-waiting, root-cause-tracing, defensive-programming
Test with:
Success criteria: Agent successfully applies technique to a new scenario
Examples: reducing-complexity, information-hiding concepts
Test with:
Success criteria: Agent correctly identifies when and how to apply the pattern
Examples: API documentation, command references, library guides
Test with:
Success criteria: Agent finds and correctly applies reference information
| Rationalization | Truth |
|---|---|
| "Protocol is obviously clear" | Clear to you does not mean clear to other agents. Test it. |
| "It's just a reference" | References can have gaps and unclear sections. Test retrieval. |
| "Testing is overkill" | Untested protocols have issues. Always. 15 minutes of testing prevents hours of confusion. |
| "I'll test if problems surface" | Problems mean agents cannot use the protocol. Test BEFORE deploying. |
| "Too tedious to test" | Testing is less tedious than debugging a bad protocol in production. |
| "I'm confident it's solid" | Overconfidence guarantees issues. Test anyway. |
| "Academic review is sufficient" | Reading is not using. Test application scenarios. |
| "No time to test" | Deploying untested protocols wastes more time fixing them later. |
All of these mean: Test before deploying. No exceptions.
Protocols that enforce discipline (like TDD) must resist rationalization. Agents are sophisticated and will discover loopholes under pressure.
Do not just state the rule — forbid specific workarounds:
# Insufficient
Author code before test? Delete it.
# Sufficient
Author code before test? Delete it. Start over.
**No exceptions:**
- Do not keep it as "reference"
- Do not "adapt" it while writing tests
- Do not look at it
- Delete means delete
Add a foundational principle early:
**No exceptions. No workarounds. No shortcuts.**
This closes off the entire class of "I'm following the spirit" rationalizations.
Capture rationalizations from baseline testing. Every excuse agents produce goes in the table:
| Rationalization | Truth |
|-----------------|-------|
| "Too simple to test" | Simple code breaks. Testing takes 30 seconds. |
| "I'll test afterward" | Tests that pass immediately prove nothing about design. |
| "Tests-after achieve the same result" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
Make it easy for agents to self-check when rationalizing:
## Guardrails - HALT and Start Over
- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."
**All of these mean: Delete code. Start over with TDD.**
Add to description: symptoms of when you are ABOUT to violate the rule:
description: Use when implementing any feature or bugfix, before writing implementation code
Follow the TDD cycle:
Run a pressure scenario with a subagent WITHOUT the protocol. Document exact behavior:
This is "watch the test fail" — you must observe what agents naturally do before authoring the protocol.
Author a protocol that addresses those specific rationalizations. Do not add content for hypothetical cases.
Run the same scenarios WITH the protocol. The agent should now comply.
Agent found a new rationalization? Add an explicit counter. Re-test until airtight.
Testing methodology: See @testing-skills-with-subagents.md for the complete testing methodology:
"In session 2025-10-03, we found empty projectDir caused..." Why bad: Too specific, not reusable
example-js.js, example-py.py, example-go.go Why bad: Mediocre quality, maintenance burden
step1 [label="import fs"];
step2 [label="read file"];
Why bad: Cannot copy-paste, hard to read
helper1, helper2, step3, pattern4 Why bad: Labels should carry semantic meaning
After authoring ANY protocol, you MUST STOP and complete the deployment process.
Do NOT:
The deployment checklist below is MANDATORY for EACH protocol.
Deploying untested protocols = deploying untested code. It violates quality standards.
RED Phase - Write Failing Test:
GREEN Phase - Author Minimal Protocol:
REFACTOR Phase - Seal Loopholes:
Quality Checks:
Deployment:
How future Claude discovers your protocol:
Optimize for this flow — put searchable terms early and often.
Creating protocols IS TDD for process documentation.
Same Prime Directive: No protocol without failing test first. Same cycle: RED (baseline) -> GREEN (author protocol) -> REFACTOR (seal loopholes). Same benefits: Higher quality, fewer surprises, airtight results.
If you follow TDD for code, follow it for protocols. It is the same discipline applied to documentation.