# Cognitive Externalization

> Use when designing or reviewing an agent or skill system and deciding what should live in the prompt versus be pushed out to durable memory, a reusable skill, a typed protocol, or the harness (hooks/permissions) — especially before adding "just one more instruction" to an already-long system prompt or CLAUDE.md.

- Skill: `presidenteog/cognitive-externalization` (Agent Skill)
- Install (CLI): `npx skillmds@latest add presidenteog/cognitive-externalization`
- Raw SKILL.md: https://api.skillmd.com/api/skills/presidenteog/cognitive-externalization/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: PresidenteOG (https://skillmd.com/u/presidenteog)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/presidenteog/cognitive-externalization

---


# Cognitive Externalization

Adapted from https://raw.githubusercontent.com/ai-boost/awesome-prompts/main/prompts/cognitive_externalization_architect.txt (ai-boost/awesome-prompts, GPL-3.0) — rewritten, not copied.

## Overview
A weak agent design stuffs everything the model needs — facts, procedures, contracts, safety rules — into one growing prompt. A strong one deliberately pushes each kind of cognition to the layer built to hold it, so each piece can be tested, swapped, or audited on its own. In this workspace those four layers already exist as concrete folders and mechanisms, not abstractions to invent.

## When to use
- Adding capability to an agent or skill and unsure whether it belongs in the prompt, a memory file, a skill, or a hook.
- A `CLAUDE.md`, agent body, or skill has grown long enough that it's doing more than one layer's job.
- Designing a new crew-* agent or skill from scratch.

## Precondition — don't over-engineer
Skip this entirely when the task is single-turn, under five tool calls, with nothing that needs to outlive the current turn — externalizing a one-off adds overhead with no payoff. Also don't propose it without knowing exactly what must persist; demand the specific facts, procedures, or contracts first.

## The four layers, mapped to this workspace
| Layer | Question | Lives here | Anti-pattern |
|---|---|---|---|
| Memory | What must the agent remember past this turn? | `Memory/` (curated, human-facing), claude-mem's session database (automatic, cross-session), `MEMORY.md` index | Treating raw chat log as memory — no extraction, no eviction, it just grows |
| Skills | What procedure should be reused instead of rederived every time? | `~/.claude/skills/<name>/SKILL.md`, kebab-case, YAML frontmatter for discovery | One mega-prompt containing every workflow the model has to page through each turn |
| Protocols | What's the typed contract between agents and tools? | Tool schemas, each `crew-*` agent's declared `## Output contract` (a caveman-compressed fixed-field block), MCP tool definitions | Free-text tool calls and prose "reports" the caller has to parse ad hoc |
| Harness | What should the runtime enforce so the model never has to decide it? | `settings.json` permissions, hooks, the constraint that subagents can't spawn subagents | "The model decides whether this destructive action is safe" — irreversible or high-risk calls belong to permission gating, not model judgment |

Keep in the prompt only: this-turn working state, the current goal, and which layers/entry points exist — never a duplicate copy of what a layer already holds.

## Design process
1. **Inventory** — list every piece of cognition the agent or skill needs; tag each as memory / skill / protocol / harness / prompt-only.
2. **Flag candidates** — anything tagged prompt-only that's needed across more than one session, or that's irreversible if the model gets it wrong, is a candidate to push to a layer.
3. **Assign layer and contract** — for each candidate, name the target layer and write a one-line contract: input, output, side effect.
4. **Check interfaces** — skills may read memory but shouldn't bypass its write path; the harness enforces protocol contracts, the model doesn't; the prompt names entry points, never duplicates their content.
5. **Verify invariants** — separation of concerns (one job per layer), least privilege, inspectability (plain text or a viewer), reversibility, and that each layer's version or format is stated somewhere.

## Heuristics
- If the model would have to rediscover it every turn, externalize it.
- If getting it wrong is irreversible, it belongs to the harness, not the prompt.
- If a human needs to audit it, it has to be plain text on disk.
- If two agents need to share it, route it through memory or a protocol — never duplicate it into both prompts.

## Common mistakes
- Cramming all four layers into one `CLAUDE.md` or agent body because it's easier than deciding where something belongs.
- Externalizing so aggressively the prompt loses the integrative reasoning it's there for — the agent becomes a router instead of a thinker.
- Adding a memory file with no eviction policy, so it accretes until it crowds out anything useful.