Claude Code Skills, CLAUDE.md and Hooks: What Each Feature Does

Updated 28 October 2026 · Sources & corrections

Skills, memory files and hooks solve different problems. A skill packages instructions for a task; a project memory file provides standing context; a hook responds to a lifecycle event. Keeping these roles separate makes configuration easier to inspect and troubleshoot.

A minimal skill

The current skills documentation explains the supported locations and frontmatter. A minimal project skill can be stored as .claude/skills/review-change/SKILL.md:

---
name: review-change
description: Review a proposed change against its stated requirements
---

Read the requirements and the diff.
Identify concrete defects and missing acceptance checks.
Explain each finding with a file reference.
Do not claim tests passed unless their output is available.

This is a small configuration example, not a claim that a particular repository has been reviewed. Check the official reference for discovery, invocation and supported options in your installed version.

Project memory

Use CLAUDE.md for repository context such as build commands, directory structure and constraints. Keep instructions factual and maintain them with the repository. A memory file is not an access-control boundary; permission settings still matter.

Hooks

Hooks can run commands around supported events. Begin with a command that only reports an event before introducing a formatter or mutation. The following JSON is a minimal structural example:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"File tool completed\""
          }
        ]
      }
    ]
  }
}

The example prints a fixed message. It does not validate or format the edited file. File-formatting hooks require careful handling of the event payload, quoting, paths, runtime dependencies and failure status. The previous formatter example contained invalid nested JSON quoting and has been replaced.

Check changes incrementally

• Record the Claude Code version.
• Add one skill or hook at a time.
• Verify it is loaded using the tools provided by that version.
• Test it in a disposable repository before allowing file-changing commands.
• Keep private tokens and machine-specific paths out of shared configuration.

For MCP integrations, use the separate MCP server guide. For initial setup, see the installation guide.

When a Claude Code skill does not appear or trigger

First separate discovery, manual invocation and automatic selection. A missing command and a skill that Claude does not choose are different observations. Inspect the actual SKILL.md and installed version before editing settings.

The official invocation reference explains these independent controls. Hiding a command from the user is not an instruction to disable automatic selection. Neither field replaces permission settings.

Use a harmless diagnostic copy in a disposable project. Give it a unique name and ask it only to return a fixed marker such as SKILL-CHECK-ONLY, without commands, files or external actions. This is a proposed check, not a recorded Claude Code run.

1. Confirm the intended project directory and exact skill path, including the uppercase SKILL.md filename.
2. Inspect frontmatter and any visibility override before changing permissions.
3. Try direct invocation at the start of a message, then separately try the task description. Record which path loaded the skill.
4. Compare the loaded instructions with the file you intended to test. Check for another skill with the same name.
5. If it still fails, retain the version, path and minimal file, then consult the current discovery and reload guidance instead of deleting every skill.

A successful marker proves only that diagnostic instruction loaded. It does not prove the real workflow has valid tools, permissions or outputs. Replace one variable at a time, keep the previous configuration, and recheck the actual result before introducing side effects.

Keep failure layers separate: the MCP guide covers external server discovery, while the API error guide covers failed model requests. Changing a skill description does not repair a provider outage.

Editorial update, 28 October 2026: added the manual-versus-automatic invocation diagnostic. No live skill invocation was performed; examples and configuration were checked locally. The original publication date is retained.