Claude Code Knowledge Management

Part 1: Where Does Knowledge Go?

Evaluate in order. First match wins.

1. TABULAR/REGISTRY DATA (URLs, IDs, contacts, rosters):
   → Used by ONE skill: .claude/skills/{skill}/references/*.md
   → Used repo-wide: reference-data/*.md

2. SITUATIONAL PERSONAL DATA (address, ID, rarely-needed info):
   → Create pointer registry (reference-data/personal-data-sources.md)
   → Registry contains POINTERS to sources (Keep notes, sheets), not data
   → CLAUDE.md has one-liner: "check registry for personal info"
   → PA looks up dynamically when needed, doesn't cache in context
   → Pattern: reference-data/{type}-sources.md with table of pointers

3. NEEDS ISOLATED CONTEXT (heavy processing, browser automation):
   → Propose agent to user, await approval
   → If rejected: create skill instead

4. DOMAIN KNOWLEDGE (procedures, workflows, explanations):
   → .claude/skills/{name}/SKILL.md
   → This is the default for most content

5. ONE-LINER CROSS-CUTTING RULE:
   → CLAUDE.md (only if truly 1-2 lines)

6. UNCLEAR:
   → Ask user

Pointer Registry Pattern (for situational data): When user provides info that PA needs occasionally but shouldn't bloat every session:

1. •Ask: "Should I add this to a source registry for future lookup?"
2. •Create/update reference-data/{domain}-sources.md
3. •Store POINTER (source location), not actual data
4. •Add one-liner to CLAUDE.md: "For X, check reference-data/{domain}-sources.md"
5. •PA dynamically looks up only when needed

Part 2: CLAUDE.md Hygiene

CLAUDE.md bloats fast. Rules:

• •One-liners only - >2-3 lines = extract to skill
• •Pointers not content - "See skill X" not the procedure
• •No procedures - All procedures → skills
• •Skills are default - When in doubt, create skill
• •Minimal edits - Modify existing or remove violations OK; adding = max 1 line
• •Agents need approval - Never auto-create

Part 3: Skill Structure

.claude/skills/{name}/
├── SKILL.md              ← Required (exact filename)
│   ├── YAML frontmatter  ← Required: name + description
│   └── Markdown body     ← Instructions
├── references/           ← Docs loaded on demand
├── scripts/              ← Executable code
└── assets/               ← Templates, files for output

Critical:

• •Path must be .claude/skills/{name}/SKILL.md
• •Frontmatter description determines when skill triggers - be comprehensive
• •Body only loads AFTER skill triggers
• •.claude/ must NOT be gitignored

Part 4: Frontmatter

Official reference: https://code.claude.com/docs/en/skills

Standard template (use for ALL skills):

---
name: skill-name
description: What it does AND when to use it. This is critical - Claude uses it to decide when to apply the skill.
user-invocable: false
---

Complete field reference

Invocation matrix (how fields interact):

String substitutions available in skill body:

• •$ARGUMENTS — all arguments passed on invocation
• •$ARGUMENTS[N] or $N — specific argument by 0-based index
• •${CLAUDE_SESSION_ID} — current session ID
• •!`command` — dynamic context injection (shell command runs before skill content is sent)

Our standard: user-invocable: false

ALL skills MUST include user-invocable: false. Our skills are model-invoked background knowledge (Claude decides when to load them based on description). Only slash commands in .claude/commands/ are user-invocable. Omitting this field defaults to true, which pollutes the / menu with non-actionable entries.

When to propose context: fork

context: fork runs the skill in an isolated subagent context. The skill body becomes the subagent's task prompt — it won't have conversation history.

Propose context: fork when:

• •Skill involves heavy browser automation or screenshot processing
• •Skill processes large data (parsing spreadsheets, logs, transcripts)
• •Skill runs multi-step workflows that could bloat parent context
• •Skill is frequently delegated to Task tool subagents anyway
• •Skill has explicit task instructions (not just guidelines/conventions)

Do NOT use when:

• •Skill is lightweight (lookup, simple procedure, reference)
• •Skill needs to read/write parent conversation state
• •Skill is a quick decision tree or routing logic
• •Skill contains conventions/guidelines without an actionable task (subagent gets guidelines but no task = useless)

Workflow: When creating/editing a skill and context: fork seems beneficial, propose to user: "This skill involves [heavy processing/browser automation/etc.] — recommend adding context: fork so it runs in an isolated context. Approve?" Do NOT add silently. If proposing fork, also suggest an appropriate agent: value.

Troubleshooting Misbehaving Skills

If a skill is not triggering, triggers too often, or behaves unexpectedly, fetch the troubleshooting section from https://code.claude.com/docs/en/skills for current diagnostic steps. Key issues:

Always fetch the live URL — troubleshooting guidance may be updated upstream.

Part 5: Writing Guidelines

1. •Imperative form - "Create documents" not "This skill creates"
2. •Description is trigger - Include all contexts when skill should activate
3. •Don't repeat - Info in SKILL.md OR references, not both
4. •Concise - Claude is smart; only add context it lacks
5. •Compliance reporting - After creating/editing a skill, just say "✅ Compliant with knowledge-architecture" — don't enumerate every rule that was followed
6. •Deterministic output format - When a skill or SOP produces user-facing output (reports, tables, status updates), define the EXACT format in the skill body. Include:
   • •A template/example showing the structure
   • •Emoji legends for visual scanning (e.g., 💻 = code, 📄 = docs, ✅ = done, ⚠️ = attention)
   • •Column names, row ordering, section order
   • •This ensures identical formatting across sessions — user builds muscle memory for scanning output. Ad-hoc formatting = cognitive overhead every time.

Part 6: Size Management

If >500 lines: keep core workflow in SKILL.md, move details to references/.

Part 7: Global vs Local

Part 8: Post-Creation

1. •Frontmatter has name:, description:, and user-invocable: false
2. •Description explains WHAT + WHEN comprehensively
3. •Located at .claude/skills/{name}/SKILL.md
4. •Add to .claude/settings.json: "Skill(name)" in permissions.allow
5. •Register in CLAUDE.md skills index (local skills only)
6. •Evaluate whether context: fork is appropriate — if yes, propose to user
7. •🧪 Evaluate whether a reminder hook is appropriate (see Part 12) — if Claude repeatedly forgets to follow this skill and it maps to a matchable action, create a PostToolUse hook and log it on the tracking issue

Part 9: Agents (Require Approval)

Never auto-create agents. Protocol:

1. •Identify candidate (needs isolated context, heavy processing)
2. •Propose: "This could be an agent because [X]. Create agent?"
3. •User approves → .claude/agents/*.md
4. •User rejects → Create skill instead

Part 10: Search Both Locations

When searching for agents or skills, ALWAYS check both:

Never assume "not found" after checking only one location.

Part 11: Auto-Fix Rule

When this skill is invoked to review an edit that already happened (post-hoc), do NOT ask the user whether to fix violations. Fix them immediately, then report:

1. •What was violated
2. •What was fixed
3. •What was learned

Asking "want me to fix this?" after reading a skill that clearly states the rules wastes the user's time. The rules are unambiguous — just apply them.

Part 12: Skill Reminder Hooks (🧪 Experimental)

Tracking issue: https://github.com/<GITHUB_USER>/PersonalAssistant-ClaudeCode/issues/23 Status: Evaluating until 2026-02-02. When implementing this pattern, comment on the issue with where you applied it (repo, skill name, hook matcher) so we can track all implementations and roll back if needed.

Problem

Claude frequently forgets to load relevant skills before/during actions. CLAUDE.md instructions are suggestions; hooks are deterministic guarantees.

Pattern: PostToolUse Reminder Hook

A PostToolUse hook fires after every tool call matching a pattern. By exiting with code 2 and writing to stderr, the message is fed directly to Claude as feedback (not just shown to the user). This forces Claude to acknowledge and follow the skill.

How It Works

Claude edits file → PostToolUse hook fires → script checks file type →
  If match: exit 2 + stderr reminder → Claude receives feedback, loads skill
  If no match: exit 0 → silent, no overhead

Implementation Steps

When creating or modifying a skill that Claude frequently forgets to follow:

1. •Create the hook script in the skill's scripts/ folder:

#!/usr/bin/env python3
"""PostToolUse reminder hook for {skill-name}."""
import json, sys

try:
    data = json.load(sys.stdin)
except (json.JSONDecodeError, EOFError):
    sys.exit(0)

file_path = data.get("tool_input", {}).get("file_path", "")

# Adjust condition to match the skill's domain
if not file_path.lower().endswith(".md"):
    sys.exit(0)

print(
    "You modified a file relevant to {skill-name}. "
    "Follow the {skill-name} skill (~/.claude/skills/{name}/SKILL.md).",
    file=sys.stderr,
)
sys.exit(2)

1. •Register the hook in ~/.claude/settings.json (global) or .claude/settings.json (project):

🚨 Cross-platform compatibility: Use python -c with os.path.expanduser('~') to resolve the home directory. $HOME doesn't expand on Windows, and hardcoded paths aren't portable. Only $CLAUDE_PROJECT_DIR is reliably injected by Claude Code (for project-scoped hooks only).

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [{
          "type": "command",
          "command": "python -c \"import os;exec(open(os.path.expanduser('~/.claude/skills/{name}/scripts/postToolUse-reminder.py')).read())\"",
          "timeout": 5
        }]
      }
    ]
  }
}

1. •Comment on the tracking issue (https://github.com/<GITHUB_USER>/PersonalAssistant-ClaudeCode/issues/23) with:
   • •Skill name and path
   • •Hook matcher used
   • •File type / condition that triggers the reminder

Hook Event Reference

Matchers: Tool name patterns — Edit|Write|MultiEdit, Bash, mcp__gmail__send_email, * (all), etc.

Exit codes: 0 = silent, 2 = feedback to Claude (stderr), other = non-blocking error.

🚨 Hook stdin input varies by event type:

Stop hooks do NOT receive transcript_summary or tools_used. Must read and parse transcript_path (JSONL, one JSON object per line, entries have type: "assistant" with content blocks containing tool_use and text).

Official docs: https://code.claude.com/docs/en/hooks

Pattern: PreToolUse Blocking Hook

A PreToolUse hook fires before tool execution. Exit code 2 blocks the tool call entirely and feeds the stderr message to Claude. Use this to permanently blacklist dangerous/faulty tool variants.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__dangerous__tool_name",
        "hooks": [{
          "type": "command",
          "command": "echo 'BLOCKED: Use mcp__safe__tool_name instead. Reason: [why].' && exit 2",
          "timeout": 5
        }]
      }
    ]
  }
}

When to use blocking hooks:

• •Two MCP tools overlap in function but one is broken/unsafe
• •A tool silently fails (no error, wrong behavior) — worse than crashing
• •The correct alternative is known and deterministic

When NOT to use:

• •Tool works but needs guardrails → use reminder hook instead
• •Tool is the only option → fix the tool, don't block it

Testing Hooks (Subprocess Verification)

🚨 Hook changes in settings.json only apply to NEW Claude Code sessions. The current session uses the settings loaded at startup.

To verify a hook works without restarting your session:

# Safe test — spawns a fresh CC instance that loads new settings
# Use --print flag to run non-interactively (prints output, exits)
claude --print "Try calling mcp__google-workspace__gmail_send to <YOUR_EMAIL> with subject 'Hook verification test' and body 'This should be blocked by PreToolUse hook.'" --allowedTools "mcp__google-workspace__gmail_send,mcp__google-workspace__gmail_*"

Safety rules for subprocess hook testing:

• •ONLY test blocking hooks — never test reminder hooks this way (they don't block, so the action executes)
• •ONLY use self-targeted test data — send to user's own email, use test subjects
• •NEVER test hooks that involve destructive actions — if the hook fails, the action runs
• •Expected result: The subprocess should report the hook blocked the tool. If the tool executes, the hook is misconfigured.
• •If test fails (tool executes): Check matcher pattern, exit code (must be 2), and that settings.json is valid JSON

When to Add a Reminder Hook

Add a hook when ALL of these are true:

• •Claude repeatedly forgets to follow the skill (proven pattern, not hypothetical)
• •The skill applies to a matchable action (file type, tool name, MCP call)
• •The skill is corrective/preventive (rules to enforce, not just reference info)

Do NOT add hooks for:

• •Informational skills (lookup, reference data)
• •Skills that already trigger reliably via description
• •One-off workflows the user explicitly invokes

Existing Implementations

Common Mistakes