Claude Code Usage Guide

assetactive

Claude Code Usage Guide

Interactive reference guide and migration toolkit for Claude Code project configuration. Covers the full .claude/ directory anatomy, CLAUDE.md best practices, rules, commands, skills, agents, settings, memory, and upgrade workflows.

Provenance

Ingested from Workspace_Tools/claude-code-guide.jsx on 2026-03-28. Originally a React JSX component ("Claude Code Companion") with two modes: Reference Guide and Upgrade/Migration tools.

Two-Scope Architecture

Claude Code reads configuration from two places:

Project-Level (.claude/ — committed to git)

  • CLAUDE.md at project root for core instructions
  • settings.json for permissions & hooks
  • commands/, rules/, skills/, agents/
  • settings.local.json for personal overrides (gitignored)

Global/Personal (~/.claude/ — never committed)

  • CLAUDE.md for cross-project preferences
  • skills/ and commands/ available everywhere
  • projects/ folder with auto-memory (MEMORY.md)
  • keybindings.json, config.json

Loading order: Global ~/.claude/CLAUDE.md first, then project CLAUDE.md, then subdirectory CLAUDE.md files. Most specific instruction wins.

CLAUDE.md Best Practices

  • Only include what Claude cannot infer from reading your code
  • Keep under 200 lines per file
  • Start with /init, then delete aggressively
  • Add rules only when Claude makes mistakes
  • Phrase as "Prefer X over Y" not "Do not Y"
  • Don't duplicate what your linter enforces
  • Use CLAUDE.local.md for personal preferences (gitignored)

Key Directories

rules/ — Modular Guidance

Break CLAUDE.md into focused domain files when any topic exceeds ~50 lines. Each .md file loads as additional context. Use for: code-style, testing, api-conventions, security, database patterns.

skills/ — Context-Aware Automation (preferred over commands)

Each skill is a directory with SKILL.md plus optional scripts/templates. Supports frontmatter: context: fork, agent:, allowed-tools:, disable-model-invocation:. Key advantage: auto-invocation — Claude can use skills without explicit slash commands.

commands/ — Legacy Slash Commands

Markdown files that become /project:<name> commands. Still work but new workflows should use skills. Support $ARGUMENTS parameterization and ! backtick preprocessing.

agents/ — Isolated Subagent Personas

Specialized personas with own system prompts, tool restrictions, and isolation. Define who does the work (vs skills which define what work gets done). Invoked explicitly or via skill frontmatter agent: field.

settings.json — Permissions & Hooks

  • permissions.allow / permissions.deny for tool access
  • hooks.PostToolUse for auto-formatting on edit/write
  • settings.local.json for personal overrides (gitignored)
  • Keep hooks fast (<2s) — they run on every edit

Migration Prompts (3 included)

  1. Audit & Upgrade — Single project scan: inventory configs, find stale rules, propose migrations (commands→skills, rules extraction, hook setup), execute after approval.

  2. Global Config — Personal ~/.claude/ setup: cross-project preferences, global skills, permissions, keybindings.

  3. Sync Repos — Multi-repo consistency: compare .claude/ configs across projects, find contradictions/gaps, harmonize shared vs project-specific settings.

Migration Checklist Categories

  • CLAUDE.md Health Check (8 items) — verify commands, delete linter-enforced rules, rephrase negatives
  • Commands → Skills Migration (7 items) — identify candidates, add frontmatter, add tool restrictions
  • settings.json Setup (7 items) — formatter hooks, deny rules, personal settings separation
  • Global ~/.claude/ Setup (5 items) — cross-project CLAUDE.md, global skills, auto-memory pruning
  • Git & Team Hygiene (5 items) — commit .claude/, gitignore local files, PR review process

Setup Sequence for New Project

  1. Run /init to generate starter CLAUDE.md
  2. Delete everything Claude can infer — aim for under 200 lines
  3. Set up .claude/settings.json with permissions and formatter hook
  4. Add rules/ files only when CLAUDE.md gets too long
  5. Create skills/ as you discover repeatable workflows
  6. Add agents/ when you need isolated, specialized reviewers
  7. Commit .claude/ to git; gitignore settings.local.json and CLAUDE.local.md