From skills-by-amrit
Use when creating new skills for the skills library. Defines the structure, format, quality standards, and testing requirements for new skills.
npx claudepluginhub boparaiamrit/skills-by-amritThis skill uses the workspace's default tool permissions.
Skills are the building blocks of this system. A well-written skill makes AI assistants genuinely better. A poorly-written skill adds noise.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Compresses source documents into lossless, LLM-optimized distillates preserving all facts and relationships. Use for 'distill documents' or 'create distillate' requests.
Skills are the building blocks of this system. A well-written skill makes AI assistants genuinely better. A poorly-written skill adds noise.
Core principle: If following the skill doesn't produce measurably better results, the skill shouldn't exist.
Master reference: All skills inherit from _rules/SKILL.md. Read it before writing any skill.
EVERY SKILL MUST HAVE A CLEAR IRON LAW, DEFINED ACTIVATION CONDITIONS, AND A VERIFIABLE PROCESS.
using-skills)YOU CANNOT:
- Create a skill without an Iron Law -- if it has no non-negotiable rule, it's advice, not a skill
- Write "Use when..." descriptions that are vague -- "Use when coding" activates for everything
- Include "it depends" in a skill -- skills are prescriptive, not suggestive
- Skip the Common Rationalizations section -- every process has excuses people make to skip it
- Write a process with vague steps -- "make sure it's good" is not a verifiable step
- Create a skill that duplicates another skill's scope -- check existing skills first
- Skip the Anti-Shortcut Rules -- they prevent the most common ways the skill gets bypassed
- Write Iron Questions that can be answered without evidence -- "Did you check?" != "What was the output?"
- Omit the Red Flags section -- without observable violation indicators, the skill cannot self-enforce
- Skip the Integration section -- isolated skills are broken skills
| Rationalization | Reality |
|---|---|
| "This skill is too short to need all sections" | Short skills still need structure. Sections prevent shortcuts. |
| "The process is self-explanatory" | To you, maybe. To an LLM following instructions literally, no. |
| "Iron Questions are overkill" | They're the accountability mechanism. Without them, skills get skipped. |
| "Not every skill needs rationalizations" | Every process has excuses for skipping it. Document them. |
| "I'll add the missing sections later" | Later never comes. Complete the skill now. |
| "This is a simple skill" | Simple skills with poor structure produce poor results. |
| "I'll just copy another skill and modify it" | Copying without understanding produces cargo-cult skills. Understand the WHY. |
| "The Red Flags are obvious" | If they were obvious, people wouldn't violate them. Write them down. |
1. Does this skill have an Iron Law? (absolute, falsifiable, concise)
2. Does the description start with "Use when..."? (enables automatic activation)
3. Does every process step have a verifiable outcome? (not just "do X")
4. Are there Anti-Shortcut Rules? (preventing bypass -- at least 6 specific prohibitions)
5. Are there Common Rationalizations with rebuttals? (preventing excuses -- at least 5)
6. Are there Iron Questions that require evidence-based answers? (accountability -- at least 8)
7. Does it have When NOT to Use? (preventing misapplication -- with redirects to correct skills)
8. Does it integrate with other skills? (skills compose, they don't standalone)
9. Could someone follow this skill LITERALLY and produce good results?
10. Is there an existing skill that already covers this? (check for duplication)
11. Does the skill have a Red Flags section with observable violations?
12. Does the skill conform to the _rules master reference?
Every SKILL.md begins with YAML frontmatter:
---
name: skill-name # Required. kebab-case, matches directory name
description: "Use when..." # Required. MUST start with "Use when" for activation
---
Rules for name:
code-review, systematic-debuggingwriting-plans, security-auditbest-practices, tips, misc, utilsRules for description:
Every skill MUST contain these sections in this order:
| Section | Purpose | Required? |
|---|---|---|
# [Title] | Human-readable skill name | Yes |
## Overview | 2-3 sentences + core principle | Yes |
## The Iron Law | Non-negotiable rule in code block | Yes |
## When to Use | Specific activation conditions | Yes |
## When NOT to Use | Counter-examples with skill redirects | Yes |
## Anti-Shortcut Rules | "YOU CANNOT:" prohibitions in code block | Yes |
## Common Rationalizations | Table of excuses with rebuttals | Yes |
## Iron Questions | Numbered evidence-requiring questions in code block | Yes |
## The Process | Phased, sequential, verifiable steps | Yes |
## Output Format | Template for skill output | If applicable |
## Red Flags -- STOP | Observable violation indicators | Yes |
## Integration | Cross-references to related skills | Yes |
Overview: Exactly 2-3 sentences describing what the skill does and why it matters, followed by a bold "Core principle:" statement. Some skills add "Violating the letter of this rule is violating the spirit of this rule." for emphasis.
The Iron Law: A single non-negotiable rule inside a code block. Must be SCREAMING_CASE. Must be absolute (no "try to" or "when possible"). Must be falsifiable (you can determine if it's being followed).
When to Use: Bullet list with specific, measurable conditions. Split into "Always" and "Optional" sub-sections if some conditions are mandatory and others are discretionary.
When NOT to Use: Bullet list with specific redirects. Each item should say what to do instead: "The task is a bug fix with clear reproduction steps (use systematic-debugging)".
Anti-Shortcut Rules: Code block starting with "YOU CANNOT:" followed by 6-8 specific prohibitions. Each prohibition names the exact shortcut and explains why it's wrong.
Common Rationalizations: Table with two columns: Rationalization and Reality. At least 5 rows. Each rebuttal is a one-line shutdown, not a paragraph.
Iron Questions: Numbered list inside a code block. At least 8 questions. Each question must require evidence to answer -- not just "yes" or "no". Include parenthetical guidance: (what was the output?).
The Process: Broken into numbered phases (Phase 1, Phase 2, etc.) with numbered steps inside each phase. Steps use action verbs in CAPS: READ, VERIFY, CHECK, RUN, TRACE. Each step has a clear "done" condition.
Red Flags: Bullet list of observable behaviors that indicate the skill is being violated. These are the "stop and course-correct" triggers.
Integration: Bullet list showing how this skill connects to others. Uses format: **After:** skill-name completes X or **Before:** skill-name starts Y.
Run this checklist against every new skill before considering it complete:
1. IDENTIFY the domain the skill covers -- what specific activity does it improve?
2. CHECK existing skills -- does any existing skill already cover this? (list them)
3. DEFINE the boundary -- what is IN scope and what is OUT of scope?
4. READ the _rules master reference to understand inherited principles
5. READ 2-3 existing well-crafted skills as reference (code-review, verification-before-completion, brainstorming are good examples)
1. WRITE the Iron Law first -- this defines the skill's non-negotiable rule
2. WRITE the description -- "Use when..." with specific activation triggers
3. WRITE When to Use -- specific conditions that activate this skill
4. WRITE When NOT to Use -- with redirects to correct skills
5. VERIFY the Iron Law is absolute, falsifiable, and concise
1. WRITE Anti-Shortcut Rules -- at least 6 specific prohibitions
- Think: "What are the most common ways someone would skip this process?"
- Each rule must name the specific shortcut and explain why it's wrong
2. WRITE Common Rationalizations -- at least 5 with one-line rebuttals
- Think: "What excuses would someone give for not following this skill?"
3. WRITE Iron Questions -- at least 8 evidence-requiring questions
- Think: "What questions, if answered honestly with evidence, guarantee quality?"
- Each must require showing output/evidence, not just saying "yes"
1. BREAK the process into 3-6 sequential phases
2. WRITE numbered steps for each phase using action verbs (READ, VERIFY, CHECK, RUN)
3. ADD decision points where outcomes branch (IF/THEN)
4. ENSURE each step has a verifiable "done" condition
5. ADD tables and examples where they improve clarity
6. TEST by reading the process literally -- would a strict rule-follower succeed?
1. WRITE Red Flags -- observable behaviors that indicate violation
2. WRITE the Integration section -- how does this connect to other skills?
3. WRITE the Output Format -- what does the skill produce? (if applicable)
4. ADD an Overview with core principle
1. RUN the full Quality Checklist (above) against the skill
2. SCORE the skill against the value rubric (below) -- every cell must say "10/10"
3. READ the skill from top to bottom as if you've never seen it -- is it clear?
4. VERIFY no section is missing
5. CHECK that the skill conforms to _rules master reference principles
Copy this template when creating a new skill:
---
name: skill-name
description: "Use when [specific activation condition] -- [example triggers]."
---
# [Skill Title]
## Overview
[2-3 sentences: what this skill does and why it matters.]
**Core principle:** [One-sentence principle that captures the skill's philosophy.]
## The Iron Law
\```
[NON-NEGOTIABLE RULE IN SCREAMING CASE]
\```
[1-2 sentences explaining the Iron Law and its implications.]
## When to Use
**Always:**
- [Condition 1]
- [Condition 2]
**Optional but valuable:**
- [Condition 3]
## When NOT to Use
- [Counter-example 1] (use `other-skill` instead)
- [Counter-example 2] (use `other-skill` instead)
## Anti-Shortcut Rules
\```
YOU CANNOT:
- [Specific prohibition 1] -- [why it's wrong]
- [Specific prohibition 2] -- [why it's wrong]
- [Specific prohibition 3] -- [why it's wrong]
- [Specific prohibition 4] -- [why it's wrong]
- [Specific prohibition 5] -- [why it's wrong]
- [Specific prohibition 6] -- [why it's wrong]
\```
## Common Rationalizations (Don't Accept These)
| Rationalization | Reality |
|----------------|---------|
| "[Excuse 1]" | [One-line rebuttal] |
| "[Excuse 2]" | [One-line rebuttal] |
| "[Excuse 3]" | [One-line rebuttal] |
| "[Excuse 4]" | [One-line rebuttal] |
| "[Excuse 5]" | [One-line rebuttal] |
## Iron Questions
\```
1. [Evidence-requiring question]? ([what evidence to show])
2. [Evidence-requiring question]? ([what evidence to show])
3. [Evidence-requiring question]? ([what evidence to show])
4. [Evidence-requiring question]? ([what evidence to show])
5. [Evidence-requiring question]? ([what evidence to show])
6. [Evidence-requiring question]? ([what evidence to show])
7. [Evidence-requiring question]? ([what evidence to show])
8. [Evidence-requiring question]? ([what evidence to show])
\```
## The Process
### Phase 1: [Phase Name]
\```
1. [ACTION VERB]: [What to do] -- [done condition]
2. [ACTION VERB]: [What to do] -- [done condition]
3. [ACTION VERB]: [What to do] -- [done condition]
\```
### Phase 2: [Phase Name]
\```
1. [ACTION VERB]: [What to do] -- [done condition]
2. IF [condition] THEN [action]
3. [ACTION VERB]: [What to do] -- [done condition]
\```
## Output Format
\```markdown
## [Skill Output Title]
### [Section 1]
[Template for output]
### [Section 2]
[Template for output]
\```
## Red Flags -- STOP
- [Observable violation behavior 1]
- [Observable violation behavior 2]
- [Observable violation behavior 3]
- [Observable violation behavior 4]
## Integration
- **Before:** `skill-name` -- [relationship]
- **After:** `skill-name` -- [relationship]
- **Complements:** `skill-name` -- [relationship]
BAD: "Try to verify your work"
GOOD: "NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE"
The Iron Law must be absolute. If it contains "try", "should", "consider", or "when possible", it's not an Iron Law -- it's a suggestion.
BAD: "Did you check the tests?"
GOOD: "Have I run the FULL test suite in THIS response? (what was the output?)"
If the question can be answered "yes" without providing evidence, it's useless. The parenthetical forces specificity.
BAD: "Don't skip steps"
GOOD: "YOU CANNOT: Say 'tests pass' without test output in this response -- stale evidence is not evidence"
Each prohibition must name the exact shortcut, the exact thing being prohibited, and why.
A skill without "When NOT to Use" will be activated incorrectly. Every skill must explicitly redirect to the correct skill for out-of-scope tasks.
BAD: "1. Review the code"
GOOD: "1. READ each changed file 2. CHECK for edge cases (null, empty, max, negative) 3. LIST all findings with severity"
Each step must have an observable outcome. "Review" is not observable. "READ and LIST findings" is.
Copying another skill's structure and swapping words produces a cargo-cult skill. Understand WHY each section exists:
A process with 10 phases and 50 steps will be ignored. Keep it to 3-6 phases with 3-5 steps each. If the process is too long, the skill's scope is too broad -- split it into two skills.
Skills don't exist in isolation. Every skill must specify:
Before adding a skill to the library, verify it meets quality standards:
1. READ the skill top to bottom -- is every required section present?
2. RUN the Quality Checklist above -- does every item pass?
3. SCORE against the value rubric -- does every cell say "10/10"?
1. READ the process as if you are a strict rule-follower with no domain knowledge
2. FOLLOW every step exactly as written
3. IDENTIFY any step that is ambiguous, vague, or unverifiable
4. FIX those steps until they pass the literal interpretation test
1. READ the description -- does it clearly match the intended use cases?
2. LIST 5 scenarios where this skill SHOULD activate -- does the description match?
3. LIST 5 scenarios where this skill should NOT activate -- does it correctly exclude them?
4. CHECK for overlap with existing skills -- would two skills both claim to activate?
1. TRY to skip the process by finding loopholes -- do the Anti-Shortcut Rules catch you?
2. TRY to claim completion without evidence -- do the Iron Questions catch you?
3. TRY to rationalize skipping steps -- do the Common Rationalizations pre-rebut your excuse?
4. TRY to violate the Iron Law while technically following the process -- does the Red Flags section catch you?
1. APPLY the skill to a real task (not a toy example)
2. COMPARE the result to what you would produce WITHOUT the skill
3. IF the skill doesn't produce measurably better results, it shouldn't exist
4. COLLECT feedback -- what was confusing? What was missing? What was unnecessary?
| Property | 10/10 | 5/10 | 1/10 |
|---|---|---|---|
| Iron Law | Absolute, falsifiable, one sentence | Present but soft | Missing |
| Anti-Shortcut Rules | 6-8 specific prohibitions | Generic "don't skip" | Missing |
| Common Rationalizations | 5-8 realistic excuses with rebuttals | 2-3 weak ones | Missing |
| Iron Questions | 8-10 evidence-requiring questions | 3-4 yes/no questions | Missing |
| Process | Phased, verified, specific | Present but vague | Missing |
| When NOT to Use | Specific redirects to other skills | "When it doesn't apply" | Missing |
| Red Flags | Observable, specific behaviors | Generic warnings | Missing |
| Integration | Specific skill references with trigger conditions | "Works with other skills" | Missing |
| Description | "Use when..." with specific triggers | Generic one-liner | Missing or vague |
| Frontmatter | name + description, both correct | Partial | Missing |
skills/
└── skill-name/
└── SKILL.md # Required: The skill definition
Skills are single-file. All information lives in SKILL.md. No external dependencies.
kebab-case, verb-first or noun-phrasetest-driven-development, systematic-debugging, security-auditgood-coding, useful-stuff, misc-tips_rules -- all skills inherit core principles from hereusing-skills -- how to discover and apply skillscode-review of the SKILL.md file itself