From skills-development
Crafts token-efficient recipes (skills/SKILL.md files) using progressive disclosure, compact syntax, and minimal examples. Use when creating, writing, updating, editing, modifying, or optimizing skills/recipes/SKILL.md files for Claude's Kitchen.
npx claudepluginhub andercore-labs/claudes-kitchen --plugin skills-developmentThis skill uses the workspace's default tool permissions.
**BEFORE creating/editing ANY recipe file:**
Implements structured self-debugging workflow for AI agent failures: capture errors, diagnose patterns like loops or context overflow, apply contained recoveries, and generate introspection reports.
Monitors deployed URLs for regressions in HTTP status, console errors, performance metrics, content, network, and APIs after deploys, merges, or upgrades.
Provides React and Next.js patterns for component composition, compound components, state management, data fetching, performance optimization, forms, routing, and accessible UIs.
BEFORE creating/editing ANY recipe file:
1. Read this entire skill → internalize ALL patterns
2. Apply ALL optimization rules → zero exceptions
3. Self-validate → run BEFORE Saving checklist
4. REJECT output → if ANY validation fails
When editing existing recipes:
1. Read existing file → identify violations
2. Rewrite using aggressive LLM patterns
3. Validate → must pass ALL checklist items
4. NO partial fixes → rewrite section completely if needed
This skill applies to ITSELF - when updating recipes, follow these exact patterns.
NO SHORTCUTS - every recipe edit must pass full validation.
Main SKILL.md body: under 500 lines for optimal performance.
Exceeds 500? → Create support file immediately.
DO NOT compact further - recipes already use aggressive optimization. Split content to reference files using progressive disclosure.
Three-tier loading:
Pattern:
my-skill/
├── SKILL.md # Overview + core patterns (<500 lines)
├── advanced.md # Deep details (loads when needed)
├── examples.md # Comprehensive examples (loads when needed)
└── reference.md # API specs (loads when needed)
Format: Gerund form (action-oriented)
✓ "Processing PDFs"
✓ "Building REST APIs"
✓ "Reviewing security patterns"
✗ "Process PDFs" (imperative)
✗ "PDF Processing Tool" (not gerund)
Include: What it does + When to use it
Third person, specific:
✓ "Extracts text from PDFs, fills forms, merges documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction."
✗ "This skill helps with PDFs" (vague)
✗ "I can help you work with PDF files" (first person)
# Skill Name
## Quick Reference
[Most common patterns - 50-100 tokens]
## When to Use
[Trigger conditions - 30-50 tokens]
## Core Patterns
[Essential patterns with minimal examples - 300-500 tokens]
## Advanced Topics
See [advanced.md](advanced.md) for:
- Edge cases
- Performance optimization
- Complex scenarios
## Examples
See [examples.md](examples.md) for complete workflows
## Reference
See [reference.md](reference.md) for API documentation
See optimization-guide.md for token budget recommendations.
FORBIDDEN (not useful to LLMs):
├─ Comments: # in markdown, // /* in code
├─ Explanatory labels: "Note:", "Important:", "Remember:"
├─ Redundant prose: "As mentioned above", "Let's review"
├─ Meta-commentary: "This section describes...", "The following shows..."
└─ Human formatting: Extra whitespace for visual separation
REQUIRED (LLM-executable):
├─ Code blocks: Actual commands/patterns
├─ Tables: Structured data
├─ Symbols: ✓✗→| for relationships
├─ Examples: Working code only
└─ Patterns: Action → Outcome format
# ✓ Show actual commands
git fetch origin main
git checkout -b feature/VC-1234-desc origin/main
# ✗ Explain in sentences
"First fetch the latest changes, then create a new branch..."
JWT: env var → validate → Result<Token, Error>
Rate limit: @Throttle(10, 60) → 429 → retry+backoff
Auth fail: missing token → 401 | invalid → 403 | expired → refresh
NOT:
When JWT authentication, obtain secret from environment, validate token,
return Result with Token or Error...
| Pattern | Fix | Severity |
|---------|-----|----------|
| No auth | @RequireRole | CRITICAL |
| Weak hash | bcrypt.hash(12) | CRITICAL |
NOT:
When missing authorization, add RequireRole decorator because...
For weak hashing, use bcrypt with cost 12 because it's more secure...
condition → action | alternative
expired → refresh | valid → proceed
lines > limit → split | lines ≤ limit → create
has_test → pass | no_test → ABORT
missing_auth → 401 | invalid_auth → 403
NOT:
If expired then refresh, otherwise if valid proceed
If lines greater than limit split PR, else create PR
RC = race_condition
THEN: RC at await → CRITICAL | RC sync → SAFE
NOT:
race_condition at await → CRITICAL
race_condition in sync → SAFE
race_condition detected...
CHECK:
- [ ] pattern? → action
- [ ] condition? → result
NOT:
You should check whether the pattern exists, and if it does, then...
Efficient (50 tokens):
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
Inefficient (150 tokens):
PDFs are Portable Document Format files. To work with them in Python,
you can use the pdfplumber library which is a tool designed to extract
text content. First you need to open the PDF file, then you can access
individual pages...
Claude already knows:
Only include:
See syntax-patterns.md for symbolic operators (✓✗→|) and conditional syntax patterns.
See consolidation-patterns.md for removing duplicate tables, redundant sections, and merging overlapping content.
CRITICAL: Recipes are already aggressively optimized. DO NOT try to compact further.
When to split:
Action when hitting 500 lines:
500 lines reached → Identify least-critical section → Move to support file
NOT: Try to compact further (already optimized)
How to split:
## Authentication Patterns
Quick pattern:
```typescript
const token = await auth.validate(req.headers.authorization);
For OAuth, JWT variants, and edge cases: auth-advanced.md
**File naming:**
- Descriptive: `form_validation_rules.md` ✓
- Generic: `doc2.md` ✗
## BEFORE Saving (MANDATORY VALIDATION)
**Run through EVERY item. If ANY fails → REJECT and fix.**
VALIDATE:
IF all pass → save IF any fail → fix before saving
**NO SHORTCUTS** - validate EVERY recipe change against this list.
## Validation Workflow (Execute After Creation/Edit)
**MANDATORY: Run after every recipe creation or edit.**
| Phase | Action |
|-------|--------|
| 1. Execute | Create/edit SKILL.md |
| 2. Validate | Gather evidence from execution, confirm output validity |
| 3. Report | ✓ ALL pass → Proceed \| ✗ ANY fail → List violations with evidence |
| 4. Fix | Violations found → Fix each → Re-run validation |
| 5. Store Metrics | After ALL validation passes, call mcp__agent-orchestrator__store-skill-metrics |
**Validation principle:**
Validation = Evidence gathering + Output confirmation NOT re-running operations
**Validation method:**
Review file content (Read tool output or Write tool input) → Gather evidence from created file → Run through BEFORE Saving checklist → Cite specific lines for violations → Confirm output validity, don't re-execute
**Output format (with evidence):**
VALIDATION REPORT: ✓ Lines: 245 (<500) [Evidence] wc -l output ✓ Naming compliance: Folder: skills/auth-recipe/ Name: designing-auth-recipe Match: "auth" in both ✓ ✓ Format: {gerund}-{topic}-recipe [Evidence] Line 2: name: designing-auth-recipe ✓ Tables: Used throughout [Evidence] Lines 45-60 contain table ✓ No human-only content: [Evidence] No comments, explanatory prose, or redundant labels ✗ FAIL: Symbolic operators missing in lines 45-60 ✗ FAIL: Verbose prose in "Background" section (lines 120-135)
VIOLATIONS (2):
ACTION: Fix violations and re-validate
**Re-validation required after fixes. Repeat until ALL checks pass.**
**Metrics storage (Phase 5):**
ALL validation checks pass → Store effectiveness metrics
mcp__agent-orchestrator__store-skill-metrics({ sessionId: "[from conversation context]", skill: "crafting-recipes", initialViolations: 2, iterations: 1, fixesApplied: 2, finalViolations: 0, validationPassed: true, durationSeconds: 45, metadata: { recipe: "auth-recipe", lines: 245 } })
✓ Metrics stored → Skill effectiveness tracked
## Common Mistakes & Optimization
See [optimization-guide.md](optimization-guide.md) for common mistakes and optimization impact details.
## Template for New Recipes
```markdown
---
name: [gerund]-[topic]-recipe
description: [Action] [topic] [details]. Use when [trigger conditions].
---
# [Topic] [Type]
## Quick Reference
...
Naming convention:
Folder: skills/{topic}-recipe/
Skill name: {gerund}-{topic}-recipe
Examples:
- skills/github-recipe/ → name: managing-github-recipe
- skills/jira-recipe/ → name: managing-jira-recipe
- skills/security-recipe/ → name: reviewing-security-recipe
See template.md for complete recipe template structure with validation workflow sections.
This recipe follows its own rules:
Use this recipe when crafting new recipes for Claude's Kitchen.