Inside Claude Code: 5 Common Traits of Effective Skills

After reading Anthropic engineer Thariq’s tweet titled “Lessons from Building Claude Code: How We Use Skills,” the author realized that many Skills fail because they contain only low‑context information that the model already knows, rather than the high‑context knowledge unique to a team’s workflow.

High‑Context Communication

The article cites Edward T. Hall’s concept of high‑ versus low‑context communication, comparing a Skill to an intern who lacks shared background. Effective Skills must convey the tacit rules, acceptance criteria, and safety constraints that are not documented publicly.

1. Focus on Gotchas

Thariq emphasizes that the densest information in a Skill is the summary of pitfalls. Since Claude already knows generic SDK usage, the real value comes from encoding team‑specific gotchas such as "50 concurrent requests will crash the API"—details that cannot be found in public sources.

2. Description as a Trigger

The description field is not a human‑readable summary but the condition the model uses to decide whether to activate the Skill. A narrow description may miss relevant requests, while an overly broad one can cause false activations. A well‑crafted description works like a precise if statement.

When a user needs to translate an English document (PDF/DOCX/EPUB/web article) into Chinese, including academic papers and terminology‑dense content, trigger the Skill; do not trigger for short casual sentences.

3. Give Skills Memory

Persisting a simple log file (or JSON/SQLite) allows a Skill to recall what it did previously, enabling it to report only changes or avoid repeating work. This reduces the “first‑time‑meeting‑you” problem common in AI assistants.

4. Use the Whole Folder

Beyond the markdown, place reusable scripts, templates, and reference code in the Skill’s scripts/ and assets/ directories. This lets Claude focus on decision‑making instead of recreating queries or formatting logic each time.

5. Add Boundaries with Hooks

On‑demand hooks such as PreToolUse can block dangerous commands (e.g., rm -rf, DROP TABLE) or restrict file edits to specific directories, providing safety rail‑ings that complement the Skill’s capabilities.

Skill Categorization

Anthropic groups hundreds of Skills into nine categories (e.g., API reference, product verification, data analysis, workflow automation, scaffolding, code review, CI/CD, runbooks, infrastructure ops). The most successful Skills focus on either closing a knowledge gap (documenting gotchas, boundaries) or an execution gap (providing scripts, validation), but not both simultaneously.

Five‑Step Checklist for Building a Good Skill

Start by listing the top ten team‑specific pitfalls in a Gotchas file.

Write the description as the exact activation condition, not a generic summary.

Include scripts, templates, or reference code so Claude can reuse them instead of rebuilding logic.

Add a persistent log (or similar) so the Skill remembers its previous state.

Define safety hooks to prevent the Skill from performing prohibited actions.

Following these steps transforms a Skill into a knowledge‑rich, tool‑aware, stateful, and safe work environment, allowing Claude Code to become increasingly reliable as it internalizes a team’s high‑context expertise.