Thomas Hu Knowledge Base

Claude Code Skills

4 min read

Claude Code Skills

Summary

  • Skills are structured workflow guides that Claude Code loads and follows automatically or on demand. Three key skills: Superpowers (workflow discipline), Writing Plans (plan-before-code), and NotebookLM (knowledge synthesis from notes).

Key Points

  • Skills live in .claude/skills/ (or a configured path) and are invoked via the Skill tool or triggered automatically by hooks.
  • Skills tell Claude how to approach a task, not just what to do — they enforce process discipline.
  • A skill that doesn’t fit the situation can be ignored after invoking; invoking it is what matters (it may reveal it doesn’t apply).
  • Skills complement slash commands: commands control the session, skills control behavior.

Superpowers

What It Is

A curated collection of workflow skills (superpowers:*) that enforce structured, disciplined approaches to common development tasks. Covers the full development lifecycle: brainstorming → planning → implementation → testing → review → completion.

Key skills in the family:

SkillPurpose
superpowers:brainstormingExplore intent and requirements before any implementation
superpowers:writing-plansWrite a file-based plan before touching code
superpowers:test-driven-developmentWrite tests before implementation code
superpowers:systematic-debuggingDiagnose root cause before proposing a fix
superpowers:requesting-code-reviewVerify work meets requirements before completing
superpowers:verification-before-completionRun and confirm output before claiming success

Scenario

  • You ask Claude to “add a new feature” and want it to think through requirements first rather than jumping straight to code.
  • You want consistent behavior across sessions (e.g. always brainstorm before building, always debug systematically).
  • You notice Claude tends to over-engineer or skip steps — skills prevent this.

How to Use

Skills are loaded automatically via hooks configured in .claude/settings.json. You can also invoke them explicitly by naming them in your prompt, or Claude checks for applicable skills at the start of every task using the using-superpowers entry skill.

The flow:

  1. User sends a message or task.
  2. Claude checks if any skill applies (even 1% chance → invoke it).
  3. Relevant skill loads and Claude follows it exactly (rigid skills) or adapts it (flexible skills).

Example

User: "Add a dark mode toggle to the settings page"

→ superpowers:brainstorming fires first
  - Asks: where should toggle live? persist to localStorage or user profile?
  - Explores existing theme system before writing any code

→ superpowers:writing-plans (if multi-file)
  - Writes plan.md with affected files and steps
  - Waits for approval before implementing

Planning with Files

What It Is

The superpowers:writing-plans skill. Before touching any code, Claude writes a structured implementation plan to a Markdown file (e.g. plan.md), presents it for review, and only proceeds after explicit approval. The plan file becomes a persistent record of intent.

Scenario

  • The task touches 3 or more files.
  • Multiple valid approaches exist and you want to choose before Claude starts coding.
  • You want a reviewable artifact before any changes are made (especially useful for large refactors or new features).
  • You’re working asynchronously and need to hand off context to another session.

How to Use

  1. Tell Claude the task. Claude enters plan mode (EnterPlanMode).
  2. Claude explores the codebase (reads relevant files, searches for patterns).
  3. Claude writes the plan to a .md file with: goal, affected files, step-by-step actions, trade-offs considered.
  4. Claude calls ExitPlanMode — you review the plan file and approve or give feedback.
  5. On approval, Claude executes the plan step by step, marking steps complete as it goes.

Use /plan slash command to manually trigger plan mode.

Example

User: "Refactor the auth system to support OAuth"

→ Plan written to plan.md:
  ## Goal
  Replace session-based auth with OAuth 2.0.

  ## Affected Files
  - src/auth/login.py
  - src/auth/middleware.py
  - src/routes/user.py
  - tests/test_auth.py

  ## Steps
  1. Add OAuth provider config to settings
  2. Replace login route with OAuth callback handler
  3. Update middleware to validate JWT instead of session
  4. Update tests

→ User reviews, approves → Claude executes step by step
  • AI/Claude Code/index
  • AI/Claude Code/Usage of Claude Code
  • AI/Claude Code/Slash Commands Reference
  • AI/Claude Code/Introduction

Graph View

Backlinks