How I Burned $15K on Claude Code in a Month and Finally Mastered Skill Writing

In one month the author’s AlgoMooc project generated a Claude Code and Codex bill of $14,942 , about fifteen times the May cost, while most of the dozens of written skills were never called. A log added to the script entry revealed that the early skills were effectively ignored.

Stage 1 – Skills as Ignored Markdown

The first skills were simple markdown files describing how to generate animation solutions for algorithm problems. Claude never proactively used them because it only reads the description line from each skill’s entry, not the full document. The author discovered the "progressive disclosure" mechanism: at conversation start Claude loads only the skill names and their one‑line descriptions, which together may occupy at most SKILL_BUDGET_CONTEXT_PERCENT = 0.01 of the context window, and each description is limited to MAX_LISTING_DESC_CHARS = 250. Descriptions longer than 250 characters are truncated:

return desc.length > MAX_LISTING_DESC_CHARS
    ? desc.slice(0, MAX_LISTING_DESC_CHARS - 1) + '…'
    : desc;

Because the original descriptions were vague adjectives, Claude never matched them. Rewriting them as concrete usage scenarios (e.g., "when a user requests an animation for an algorithm problem or uses the /anim command, invoke me") increased trigger rate from 0/5 to 4/5 in five test runs.

Stage 2 – Validation Reveals Black Screens

Even after triggers worked, the generated animations often resulted in black screens. Claude reported "animation completed" because its code executed without error, but the visual output was missing. The author added a verification step that forces the animation to run, capture multiple frames, and assert that key data appears on screen, eliminating false completions.

Stage 3 – Over‑Detailed Skill Bodies

Writing overly verbose skill bodies with redundant instructions added noise. The official guidance is to include only information Claude cannot infer, mainly "pitfall" entries. Real examples include:

Capture screenshots only after the 30th frame, because earlier frames are blank.

After publishing a page to CDN, manually refresh the cache or the old version will be served.

Force color tokens from the assets folder to maintain contrast for color‑blind users.

These pitfalls cannot be deduced from code alone and dramatically improve reliability.

Stage 4 – Skills as Folders

Skills evolve into folders containing SKILL.md , references/ , assets/ , outputs/ , and scripts/ . Example layout:

algomooc-animator/
├── SKILL.md          # required: when to use + guide + pitfalls
├── references/       # high‑quality solution pages for style learning
├── assets/           # color tokens, animation component specs
├── outputs/          # generated HTML animation pages
└── scripts/
    ├── render_check.py   # verification script from Stage 2
    └── deploy.py          # deploy and refresh CDN cache

During execution Claude receives the root directory path, then lazily loads referenced files as needed, preserving the three‑layer progressive disclosure (description → SKILL.md → referenced files). Additional techniques include: Packaging reusable scripts so Claude can call them instead of rewriting boilerplate. Storing persistent configuration in config.json to give the skill memory across sessions. Using temporary hooks (e.g., a freeze hook) that activate only during skill execution to prevent unintended file modifications.

Stage 5 – Measuring Skill Utility

By attaching a PreToolUse hook, the author logged each skill invocation, revealing that the animation skill was called over a hundred times per month while a color‑adjustment skill was called only four times. This data guided the author to focus optimization effort on the high‑frequency skill, reducing its rendering time from ~15 s to 3–4 s. In team settings, skills can be packaged as plugins for an internal marketplace, allowing popular skills to gain traction organically.

Interview Guidance

The author outlines a four‑step answer for interviewers asking about Claude Code skills: Explain that a skill is a folder, not just a markdown file. Describe progressive disclosure and the strict description limits. Highlight the importance of a concise pitfall list in the skill body. Showcase advanced features: bundled scripts, persistent memory, and temporary hooks, plus usage metrics to identify high‑impact skills. Following this structure demonstrates practical experience with Claude Code agents.