EP2 Skills, memory and hooks: knowledge, procedures and rules, kept apart

In EP1 we wrote a project handbook in CLAUDE.md. After a while everyone hits the same problem: everything goes into that one file, the things to know, how to do each kind of job, and the rules that must never be broken. The file keeps growing until what matters is buried. This episode separates those three kinds of things.

Three kinds of things, three places

Back to the colleague who arrives for their first day, every day. In a real company we give them three things:

What	In a company	In Claude Code	Read when
Knowledge	notes on what was agreed	memory	at the start of every session
Procedures	a how-to for each kind of job	skill	only when doing that job
Enforced rules	systems you cannot skip, like a badge reader on the door	hook	runs by itself, nothing to remember

Principle: keep what must be known, what must be done step by step, and what must be enforced apart.

Memory: knowledge that builds up

Memory is notes the AI writes as it works, such as “the user does not want anything pushed until asked” or “this experiment was tried and failed”. The memory index is loaded in the next session, so it does not ask again.

A lesson from real use: one project kept adding to memory until its index file was 203 lines and 41KB. In the next session only about the first 110 lines were loaded; the other ninety-odd were cut off. Whatever was noted at the end of the file might as well not exist.

The fix is to keep the index to one short line per item, put detail in separate files, and regularly delete what is stale or wrong. Memory is a notebook: if nobody tidies it, eventually nothing can be found.

Skills: procedures that repeat

A skill is a how-to for one kind of job, stored at .claude/skills/<name>/SKILL.md. Its header holds only a name and a description:

---
name: write-article
description: Write an article for the site. Use when the user asks for a new article or to edit one.
---

1. Read docs/ARTICLE_GUIDE.md first
2. Write Thai and English, same file name
3. Run npm run build; it must pass
4. Check both languages at 375px wide

The key point: the AI sees only the description until it needs the skill. When a request matches the description, it reads the full text. You can also call it yourself by typing /write-article. That is why you can have dozens of skills without making every task slower or costlier. The machine this article was written on has 35, from test-first development to reviewing for needless complexity.

So the description is the most important line in the file. Say when to use it, not just what it does. Too broad and it gets picked for the wrong job; too narrow and it never gets picked.

Hooks: rules that must not fail

The trouble with instructions in a file is that the AI can forget, especially on long tasks. If a rule truly must not be broken, do not leave it to memory. Use a hook.

A hook is a shell command Claude Code runs on its own when a given event happens, such as after every file edit or before a command runs. It lives in .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm run lint" }]
      }
    ]
  }
}

This runs lint every time the AI edits or creates a file, whether it remembers to or not. Hooks can also stop dangerous commands: if a hook that runs before a command reports a failure, the command does not run.

A real one from building this site: every time the AI edited a page, a hook reminded it “no preview is open; if this change shows in the browser, open it before finishing”. Checking on a real screen stopped depending on anyone’s memory.

Deciding what goes where

Ask one question at a time:

1. Must it be known every time? Yes → CLAUDE.md (if it is a rule) or memory (if it was learned along the way)
2. Is it how to do one kind of job? Yes → a skill
3. Would getting it wrong cause real damage? Yes → a hook, not just a sentence in a file

Try it in 10 minutes

1. Pick the job you ask the AI for most often and write it as a skill like the one above, ten lines at most
2. Open a new session and ask for that job in plain words. Does it pick up the skill? If not, make the description clearer about when to use it
3. Pick one rule the AI has forgotten before and turn it into a hook

Where a person is needed

The AI can write memory and draft skills, but a person has to curate them: what is worth keeping, what is stale and should go, which rule matters enough to enforce with a hook. Left entirely to the AI, memory bloats like the example above.

Next episode

Our AI now knows the rules, has procedures and has enforced rules, but it still works on one thing at a time in one head. EP3 lets it hand work to subagents, helpers with a room of their own, who can work in parallel without cluttering the main head.