القائمة
Use when creating new skills, editing existing skills, or verifying skills work before deployment
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
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 facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
Use when the user explicitly requests a code review, or during subagent-driven development where review is part of the workflow
Use when executing implementation plans with independent tasks in the current session
| name | sr-writing-skills |
| description | Use when creating new skills, editing existing skills, or verifying skills work before deployment |
Writing skills IS Test-Driven Development applied to process documentation.
You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
| TDD Concept | Skill Creation |
|---|---|
| Test case | Pressure scenario with subagent |
| Production code | Skill document (SKILL.md) |
| Test fails (RED) | Agent violates rule without skill (baseline) |
| Test passes (GREEN) | Agent complies with skill present |
| Refactor | Close loopholes while maintaining compliance |
| Write test first | Run baseline scenario BEFORE writing skill |
| Watch it fail | Document exact rationalizations agent uses |
| Minimal code | Write skill addressing those specific violations |
| Watch it pass | Verify agent now complies |
| Refactor cycle | Find new rationalizations → plug → re-verify |
Core principle: If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
REQUIRED BACKGROUND: You MUST understand sr-test-driven-development before using this skill.
A skill is a reference guide for proven techniques, patterns, or tools. Skills help future instances find and apply effective approaches.
Skills are: Reusable techniques, patterns, tools, reference guides
Skills are NOT: Narratives about how you solved a problem once
Create when:
Don't create for:
Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)
Way of thinking about problems (flatten-with-flags, test-invariants)
API docs, syntax guides, tool documentation
skills/
skill-name/
SKILL.md # Main reference (required)
supporting-file.* # Only if needed
Frontmatter (YAML):
name and description (see agentskills.io/specification for all supported fields)name: Use letters, numbers, and hyphens only (no parentheses, special chars)description: Third-person, describes ONLY when to use (NOT what it does)
---
name: skill-name
description: Use when [specific triggering conditions and symptoms]
---
# Skill Name
## Overview
What is this? Core principle in 1-2 sentences.
## When to Use
Bullet list with SYMPTOMS and use cases
## Core Pattern
Before/after code comparison
## Quick Reference
Table or bullets for scanning
## Common Mistakes
What goes wrong + fixes
Critical for discovery: Future agents need to FIND your skill
Purpose: Your agent reads the description to decide which skills to load for a given task.
CRITICAL: Description = When to Use, NOT What the Skill Does
The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.
Why this matters: When a description summarizes the skill's workflow, an agent may follow the description instead of reading the full skill content. The description becomes a shortcut agents will take, and the skill body becomes documentation agents skip.
# BAD: Summarizes workflow - agents may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks
# GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session
Use words an agent would search for:
Problem: Frequently-referenced skills load into every conversation. Every token counts.
Techniques:
--help instead of documenting all flags)Before writing guidance, classify the baseline failure:
| Baseline failure | Right form | Wrong form |
|---|---|---|
| Skips/violates a rule under pressure | Prohibition + rationalization table + red flags | Soft guidance ("prefer...", "consider...") |
| Complies, but output has the wrong shape | Positive recipe or contract: state what the output IS | Prohibition list ("don't restate", "never narrate") |
| Omits a required element | Structural: REQUIRED field or slot in the template | Prose reminders near the template |
| Behavior should depend on a condition | Conditional keyed to an observable predicate | Unconditional rule + exemption clauses |
Rules for whichever form you pick:
NO 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:
Run pressure scenario WITHOUT the skill. Document exact behavior.
Write skill that addresses those specific rationalizations. Run same scenarios WITH skill.
Agent found new rationalization? Add explicit counter. Re-test until bulletproof.
Different skill types need different test approaches:
| Skill Type | Test With | Success Criteria |
|---|---|---|
| Discipline (rules/requirements) | Pressure scenarios, combined pressures | Agent follows rule under maximum pressure |
| Technique (how-to guides) | Application scenarios, edge cases | Agent successfully applies technique |
| Pattern (mental models) | Recognition scenarios, counter-examples | Agent correctly identifies when/how to apply |
| Reference (documentation/APIs) | Retrieval scenarios, gap testing | Agent finds and correctly applies info |
Skills that enforce discipline need to resist rationalization. Agents are smart and will find loopholes under pressure.
Scope: This toolkit is for discipline failures — an agent that knows the rule and skips it under pressure. For wrong-shaped output or omitted elements, use the forms in Match the Form to the Failure instead.
Don't just state the rule - forbid specific workarounds.
Add foundational principle early:
**Violating the letter of the rules is violating the spirit of the rules.**
List every excuse agents use and counter each one specifically.
RED Phase:
GREEN Phase:
name and description (see agentskills.io/specification)REFACTOR Phase:
Deployment:
Stop and reassess if you catch yourself:
description that summarizes the skill's process instead of triggering conditions