secondsky__claude-skills/docs/reference/COMMON_MISTAKES.md

title, purpose, last_updated, category, type

title	purpose	last_updated	category	type
Common Mistakes to Avoid	Learn from failures without experiencing them yourself	2025-11-21	planning	reference

Common Mistakes to Avoid

Purpose: Learn from failures without experiencing them yourself

Last Updated: 2025-11-21

---

CRITICAL MISTAKES (Break Functionality)

Mistake #0: Using Automated Scripts for Refactoring

❌ WRONG (Automated refactoring):

# Creating Python script to automatically refactor skills
def refactor_skill(skill_file):
    # Programmatically extract sections
    # Auto-generate new SKILL.md
    # Bypass human review

✅ CORRECT (Manual refactoring):

1. Read entire SKILL.md manually
2. Identify sections to extract (human judgment)
3. Copy content to references/<name>.md using Write tool
4. Use Edit tool to replace section with pointer
5. Review each change before proceeding

Why It Matters:

• Human Judgment Required: Skills need context-aware decisions about what to extract vs keep
• Quality Control: Each change must be reviewed for accuracy and clarity
• Error Prevention: Automation can introduce subtle errors that break skills
• Traceability: Manual changes are easier to review in pull requests

Real Impact: Attempted to use Python script to refactor sveltia-cms (2025-11-21), had to revert entire commit

Correct Process:

• Use Read, Edit, Write tools manually
• Review each change before applying
• Use existing scripts in scripts/ directory only (e.g., review-skill.sh, check-versions.sh)
• Follow ONE_PAGE_CHECKLIST.md refactoring guidelines
• Time: 30min-2hrs per skill (INTENTIONAL - quality over speed)

See CLAUDE.md for complete manual refactoring process documentation.

---

⚠️ System Prompt Budget Constraint (TOTAL Across All Skills)

Claude Code has a 15,000 character TOTAL budget for ALL skill descriptions combined in the system prompt. This is NOT per-skill—it's shared across every installed skill.

Impact: With 114 skills in this repository:

• If all installed with 200-char descriptions = 22,800 chars TOTAL → Budget exceeded
• Result: Random skills silently omitted without warnings or errors
• Math: 15,000 chars ÷ 114 skills = ~130 chars average maximum

Best Practice: Keep descriptions under 100 characters to leave headroom for new skills.

Workaround: Set SLASH_COMMAND_TOOL_CHAR_BUDGET=30000 environment variable to double the limit.

Source: https://blog.fsck.com/2025/12/17/claude-code-skills-not-triggering/

---

Mistake #1: Missing YAML Frontmatter

❌ WRONG (Skill is invisible to Claude):

# My Awesome Skill

This skill helps you build stuff...

✅ CORRECT:

---
name: my-awesome-skill
description: |
  This skill provides comprehensive knowledge for building stuff.

  Use when: specific scenarios

  Keywords: technology, use-case, errors
license: MIT
---

# My Awesome Skill

This skill provides...

Why It Matters: Without frontmatter, Claude Code cannot discover your skill. It's invisible.

Real Impact: cloudflare-workers-ai was broken until we added frontmatter (audit: 2025-10-21)

---

Mistake #2: Invalid YAML Frontmatter

❌ WRONG (Breaks parsing):

---
name = my-skill  # ← Wrong: Use colon, not equals
description This skill...  # ← Wrong: Missing colon
license MIT  # ← Wrong: Use quotes or pipe for multiline
--  # ← Wrong: Missing third dash

✅ CORRECT:

---
name: my-skill
description: |
  This skill provides...
license: MIT
---

How to Verify: Copy frontmatter to https://yaml-online-parser.appspot.com/

---

Mistake #3: Name Doesn't Match Directory

❌ WRONG:

Directory: skills/cloudflare-workers/
SKILL.md frontmatter: name: cloudflare-worker  ← Mismatch!

✅ CORRECT:

Directory: skills/cloudflare-workers/
SKILL.md frontmatter: name: cloudflare-workers  ← Match!

Why It Matters: Name MUST match directory name exactly (per official spec)

---

DISCOVERY MISTAKES (Reduce Effectiveness)

Mistake #4: Vague Description

❌ WRONG:

description: "A skill for Cloudflare"

✅ CORRECT:

description: |
  This skill provides production-tested patterns for Cloudflare Workers with
  Hono routing, Vite plugin, and Static Assets.

  Use when: creating Workers projects, configuring Hono routing, deploying with
  Wrangler, or encountering "Static Assets 404" or routing conflicts.

  Keywords: Cloudflare Workers, Hono, Wrangler, Static Assets, CF Workers,
  deployment errors, routing issues

Impact: Vague = Poor discovery. Detailed = Good discovery.

---

Mistake #5: Missing Keywords

❌ WRONG (Minimal keywords):

description: This skill helps with React setup.

✅ CORRECT (Comprehensive keywords):

description: |
  This skill provides React + Vite + TypeScript setup patterns.

  Use when: scaffolding Vite projects, configuring TypeScript for React,
  setting up HMR, or encountering "React is not defined" or HMR issues.

  Keywords: react, vite, typescript, hmr, vite config, react hooks,
  jsx transform, "React is not defined", "HMR not working"

Pro Tip: Include error messages users search for!

---

Mistake #6: Second-Person Description

❌ WRONG (Second-person):

description: Use this skill when you want to build Workers.

✅ CORRECT (Third-person):

description: |
  This skill should be used when building Cloudflare Workers projects.

Why: Official Anthropic standard uses third-person

---

STRUCTURE MISTAKES

Mistake #7: Non-Standard Frontmatter Fields

❌ WRONG (Custom fields):

---
name: my-skill
version: 1.0.0  # ← Not in spec
author: Me  # ← Not in spec
tags:  # ← Not in spec
  - cloudflare
description: ...
---

✅ CORRECT (Standard fields only):

---
name: my-skill
description: |
  ...
license: MIT
# Optional official fields:
# allowed-tools: [bash, python]
# metadata:
#   category: "cloudflare"
---

Impact: Non-standard fields may be ignored or break future versions

Real Example: cloudflare-vectorize used custom fields - fixed in audit (2025-10-21)

---

Mistake #8: Second-Person Instructions

❌ WRONG:

To set up the project, you should run:

✅ CORRECT:

To set up the project, run:

Rule: Use imperative/infinitive form, not second-person

---

Mistake #9: Wrong Directory Names

❌ WRONG:

skill-name/
├── SKILL.md
├── template/  # ← Singular
├── reference/  # ← Singular
└── script/  # ← Singular

✅ CORRECT (Official Anthropic structure):

skill-name/
├── SKILL.md
├── scripts/  # ← Plural
├── references/  # ← Plural
└── assets/  # ← Plural

Note: We're standardizing to official naming

---

CONTENT MISTAKES

Mistake #10: Outdated Package Versions

❌ WRONG:

# Documented versions (not verified):
- hono@3.5.1  # ← Old version

✅ CORRECT:

# Verified 2025-10-21:
- hono@4.10.1  # ← Latest stable

Process:

npm view hono version  # Verify before documenting

---

Mistake #11: Untested Templates

❌ WRONG:

// Template that was never tested
import { Hono } from 'hono'
const app = new Hono()
// ... untested code

✅ CORRECT:

// Tested in production: https://example.com
import { Hono } from 'hono'
const app = new Hono()
// ... verified working code

Process: Build example project using templates before committing

---

Mistake #12: No Error Sources

❌ WRONG:

### Issue: Colors Not Working
This is a common problem.

✅ CORRECT:

### Issue: Colors Not Working
**Source**: GitHub Issue #3955 (https://github.com/honojs/hono/issues/3955)
**Why**: Using wrong export pattern
**Fix**: Use `export default app` not `{ fetch: app.fetch }`

---

TESTING MISTAKES

Mistake #13: Not Installing Locally

❌ WRONG:

# Just commit without testing
git add skills/my-skill
git commit -m "Add skill"

✅ CORRECT:

# Install and test first
/plugin install my-skill@claude-skills
# Try using it in Claude Code
# Verify discovery works
# THEN commit

---

Mistake #14: Leaving [TODO:] Markers

❌ WRONG:

## Quick Start

[TODO: Fill this in later]

✅ CORRECT:

## Quick Start

1. Install dependencies: `npm install hono@4.10.1`
2. Configure wrangler.jsonc
3. Run dev server: `npm run dev`

Check Before Commit:

grep -r "\[TODO" skills/my-skill/
# Should return nothing

---

GIT MISTAKES

Mistake #15: Vague Commit Messages

❌ WRONG:

git commit -m "Add skill"

✅ CORRECT:

git commit -m "Add cloudflare-d1 skill for D1 database

- Provides D1 setup with wrangler + migrations
- Errors prevented: 6
- Package versions: wrangler@4.43.0

Production tested: Working in 3 projects
Research log: planning/research-logs/cloudflare-d1.md"

---

Mistake #16: Committing Secrets

❌ WRONG:

// template file
const API_KEY = "sk-real-api-key-here"  // ← NEVER!

✅ CORRECT:

// template file
const API_KEY = process.env.API_KEY  // ← Use env vars

Check Before Commit:

git diff | grep -i "api.key\|secret\|password"

---

DOCUMENTATION MISTAKES

Mistake #17: No "Last Updated" Date

❌ WRONG:

# My Skill

This skill helps with...

✅ CORRECT:

# My Skill

**Status**: Production Ready ✅
**Last Updated**: 2025-10-21
**Latest Versions**: package@x.y.z

---

Mistake #18: Broken Links

❌ WRONG:

See [documentation](./docs/guide.md)  # ← File doesn't exist

✅ CORRECT:

See [documentation](references/guide.md)  # ← Actual path

Verify:

# Test all links work
for link in $(grep -o '\[.*\](.*\.md)' SKILL.md); do
  # Verify file exists
done

---

WORKFLOW MISTAKES

Mistake #19: No Research Log

❌ WRONG:

# Build skill from memory
# No documentation of research

✅ CORRECT:

# Create research log first
touch planning/research-logs/my-skill.md
# Document:
# - Official docs reviewed
# - Package versions verified
# - Issues researched
# - Example built

---

Mistake #20: Skipping Checklist

❌ WRONG:

# Commit without verification
git commit -m "Done!"

✅ CORRECT:

# Verify against ../getting-started/ONE_PAGE_CHECKLIST.md
# Ensure all boxes checked
# THEN commit

---

BEFORE/AFTER EXAMPLES

Example 1: cloudflare-workers-ai (Fixed 2025-10-21)

BEFORE (Broken):

# Cloudflare Workers AI - Complete Reference

Production-ready knowledge domain...

❌ No frontmatter = Invisible to Claude Code

AFTER (Fixed):

---
name: Cloudflare Workers AI
description: |
  This skill provides Workers AI knowledge...

  Use when: implementing AI inference...

  Keywords: workers ai, llm, @cf/meta/llama...
license: MIT
---

# Cloudflare Workers AI - Complete Reference

✅ Properly discoverable

---

Example 2: cloudflare-vectorize (Fixed 2025-10-21)

BEFORE (Non-standard):

---
name: cloudflare-vectorize
version: 1.0.0  # ← Custom field
author: Claude Skills Maintainers  # ← Custom field
tags: [cloudflare, vectorize]  # ← Custom field
description: Complete guide...
---

⚠️ Works but non-standard

AFTER (Standard):

---
name: Cloudflare Vectorize
description: |
  This skill provides comprehensive knowledge...

  Use when: creating vector indexes...

  Keywords: vectorize, vector database, RAG...
license: MIT
---

✅ Follows official spec

---

PREVENTION CHECKLIST

Before committing, verify you DIDN'T make these mistakes:

• ✅ YAML frontmatter exists
• ✅ Frontmatter is valid YAML
• ✅ name matches directory name
• ✅ Description is detailed (not vague)
• ✅ Keywords comprehensive
• ✅ Third-person description
• ✅ Imperative instructions (not "you should")
• ✅ Only standard frontmatter fields
• ✅ Package versions current
• ✅ Templates tested
• ✅ Error sources documented
• ✅ Installed and tested locally
• ✅ No [TODO:] markers
• ✅ No secrets in code
• ✅ "Last Updated" date present
• ✅ All links work
• ✅ Research log created
• ✅ Checked ../getting-started/ONE_PAGE_CHECKLIST.md

All boxes checked = Ready to commit! ✅

---

Learn More

• START_HERE.md - Workflow overview
• ONE_PAGE_CHECKLIST.md - Verification checklist
• STANDARDS_COMPARISON.md - Official standards
• CLOUDFLARE_SKILLS_AUDIT.md - Example audit

---

Remember: These mistakes were all made during development. Learn from them!