# Improving From Real Transcripts — Claude Code Skills & SKILL.md

Source: https://www.geekswithgeeks.com/en/claude-code-skills/t-iterate

> Watch runs, find where Claude struggled, and fix the skill.

## Observe, fix, re-test

The best improvements come from watching real use. Read the transcript of a run: Did Claude find the skill? Which instruction did it skip or misread? Did it waste steps searching for something the skill could have told it? Did it open files it did not need, or miss one it did? Did it produce output in the wrong shape? Fix the **cause**: add the missing step, sharpen an ambiguous instruction, move a rule higher or make it more concrete, add a **gotcha** for a repeated mistake, tighten the description, or turn a fragile instruction into a **script**. Change one thing at a time, re-run your trigger list and a few real tasks, and keep notes of what changed and why. Ask also whether the skill is still needed: models improve, and instructions that once helped may become unnecessary overhead.

## A skill improvement log

Short entries tie each change to evidence. Dates, numbers and the skill itself are an invented example.

```text
date        observation (from a transcript)                      change                                   re-test
2026-03-02  skill not chosen for "what shipped this week?"         add "what shipped" to trigger phrases     trigger list 6/6
2026-03-09  model invented PR numbers                             gotcha + script prints PRs as JSON       3 tasks OK
2026-03-16  read 900-line reference every run                     "read ONLY if a request fails"           context -40%
2026-04-01  fires on code-review questions                        narrow description; add "not for review" false alarms 0/3
```

## Change one thing at a time

Otherwise you cannot tell which edit fixed or broke the behaviour.

**Quiz:** What is the best source of ideas for improving a skill?

- [ ] Adding more text everywhere
- [ ] Guessing
- [x] Real transcripts showing where Claude misread, skipped or wasted steps
- [ ] Removing the description

*Answer:* Real transcripts showing where Claude misread, skipped or wasted steps. Evidence beats intuition when tuning instructions.