Skip to main content
skill CX Codex

knowledge-layers · haowjy, claude — Claude Code skill: what it does, how to install

The knowledge-layers Claude Code skill sorts project knowledge across nearby docs, a knowledge base, and work directories. It activates when choosing where information belongs or editing durable documentation.

Apache-2.0 441 installs ★ 601 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add haowjy/creative-writing-skills --skill knowledge-layers -a claude-code
Open on GitHub

What knowledge-layers does

The skill helps place project knowledge in one of three locations: documentation beside the code or content it describes, a knowledge base (KB), or a work directory. AGENTS.md and .context/ describe their own directory; the KB holds project reasons and facts that do not belong to one directory; a work directory tracks one task’s progress, decisions, and open questions.

Load /creative-writing-skills:qi-layer before writing AGENTS.md or .context/. Before editing a KB, read its own AGENTS.md; when moving or renaming a page, update its references. Deferred work spanning directories or needing outside visibility belongs in an issue tracker. The skill also describes how to capture settled changes and sweep a KB for stale pages; /creative-writing-skills:md-validation checks links and diagrams.

What it helps with

  • place project knowledge in the right layer
  • separate lasting facts from the state of active work
  • record why a project choice was made beside the work it describes
  • find stale KB pages and repair references

Example prompts for the agent

  • Sort these module notes into AGENTS.md, .context/, the KB, or the current work directory.
  • Write a lasting note about this project choice, including its reason and cost.
  • Sweep the KB for outdated claims and check its links.

How to install knowledge-layers

1Skills CLI (Vercel)

npx skills add haowjy/creative-writing-skills --skill knowledge-layers -a claude-code

2Manually: put the files in place

~/.claude/skills/knowledge-layers/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/knowledge-layers/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about knowledge-layers

How do I install knowledge-layers in Claude Code?

Run npx skills add haowjy/creative-writing-skills --skill knowledge-layers -a claude-code. The skill file is at ~/.claude/skills/knowledge-layers/SKILL.md.

What does knowledge-layers do?

It guides agents on where to store project knowledge: nearby documentation, a KB, or a work directory. It also covers documenting the reasons behind choices and keeping KB content current.

What should I load before editing AGENTS.md or .context/?

Load /creative-writing-skills:qi-layer first. Before writing to a KB, read that KB’s own AGENTS.md as well.

Source text

SKILL.md · Apache-2.0
---
name: knowledge-layers
description: 'Use when deciding where knowledge goes or reading/writing durable docs: AGENTS.md and .context/ beside what they describe, the KB, and work directories.'
metadata:
  type: reference
---

# Knowledge Layers

Knowledge lives next to what it describes. Load `/creative-writing-skills:qi-layer` before writing
`AGENTS.md` or `.context/`.

## Three Places

| Place | What goes there | Reader |
|---|---|---|
| Beside what it describes (`AGENTS.md`, `.context/`) | Knowledge about this directory and what's in it (code, chapters, docs), and its deferred work in `.context/TODO` (must-do) and `FUTURE` (nice-to-have) | An agent about to work in the directory |
| KB | Why the project is the way it is, where no one directory owns the reason; domain concepts; facts about the outside world | A future agent or the owner, without this work's context |
| Work directory | This work item's state: what's in progress, its decisions and their reasons, open questions, scratch | Agents on this work item |

Colocate first. Knowledge about one part of the project goes in its
`AGENTS.md` or `.context/`, even when it reads like a concept: a doc far from
what it describes isn't updated when that thing changes. The KB holds what
would survive rewriting any one part. Deferred work that spans
directories or needs outside visibility goes to the issue tracker.

## The KB Records Why

A KB page says what the project does, or what the human chose it should
do, and why: the reason, the fact or
constraint behind it, and what would change it. The reason is the content.
An agent that knows it can tell when it stops holding; an agent given only
the verdict can only obey it. A rule whose reason nobody can state gets
deleted. State the behavior and its reason without names, quotes or session
IDs: a line lifted from a conversation reads as a ruling.

Organize by topic, not as a register of decisions: no decision IDs, no
`decisions/` tree, no lists of rejected options. Keep a rejected option only
with the fact that sank it ("a fixed request deadline killed healthy long
generations"). Without its reason it reads as a ban nobody can re-examine.

Two things reach the KB: what the human chose, and what finished work
established. An option they floated, a question they asked, or a list they
gave without picking stays in the work directory until they choose. Read how
they said it: "maybe X?" is not a choice, and a choice made with a hedge is
written "for now" or "trying".

Before writing about some work, read the docs, `AGENTS.md`, `.context/` and
comments it updated. Link to them and write only what they don't say. When
they say all of it, the KB gets a link or nothing.

## Every Choice Is a Tradeoff

Every choice a project records gave something up for what it gained, and
holds while that trade still pays. Write each as how things stand now, with
its reason and what it costs, beside the work it describes, so a later agent
can tell when the trade stops paying. Change it when the reason stops
holding or the human asks for something else (`/creative-writing-skills:intent-modeling`), and
update the page in the same change. A choice the human made, such as what
the product does for its users, changes when they say so: bring them the
evidence.

Write a choice as behavior and reason, not as a rule. Don't add a "must",
"never" or "always" the human didn't say, or a line for what a careful agent
protects unprompted, such as users' data or a passing build. Written down as
a rule, it gets applied past its reason: an agent told that users' data
must survive keeps code whose only job is to keep old links working.

Instructions about how agents work (permissions, approvals, what needs the
human, lessons from past mistakes) are not tradeoffs: follow them, and write
them as instructions.

## Current Truth

Every durable layer states the best current understanding and never
narrates its own history. Delete superseded content, and content whose
subject is gone, on sight, even with nothing to put in its place: agents
reason from what they load, and stale knowledge is worse than a gap.
Delete rather than move aside: version control is the archive, and a tree
without it, other than a work directory, gets a copy before you delete.
Commit untracked files before deleting them, and say in the commit message
what went and why. The agent that owns a tree's content deletes from it; a
structural role flags instead.

`AGENTS.md` and `.context/` describe the tree that contains them: update
them in the same change as what they describe. In a code project,
`resources/code.md` maps this onto branches and merges.

## KB Operations

A KB carries its own `AGENTS.md`, written per `/creative-writing-skills:qi-layer`. Read it before
writing; for that KB it wins over this skill. `resources/bootstrap.md` is a
starting layout for a new KB.

- **Ingest:** to capture a settled change, follow `resources/capture.md`.
- **Maintain:** when moving or renaming a page, fix every reference to it.
- **Sweep:** when asked, read each page in the tree against the project as
  it is now (the code, the other pages, the docs) and delete or correct what
  no longer holds: stale claims, contradictions, orphan pages, rules with no
  reason. `/creative-writing-skills:md-validation` checks links and diagrams.

Flag what needs the human inline, with the date and both sides:

```markdown
> [!FLAG] **Needs human review**: this page says X; `other-page.md` says Y.
> Both may be partly right. Flagged 2026-04-28.
```

© haowjy · Apache-2.0 · haowjy/creative-writing-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

knowledge-layers by other authors comes first.

knowledge-layers haowjy knowledge-layers — a skill that decides which layer holds a piece of knowledge: AGENTS.md, .context/, KB, docs/ or a work directory. Useful when the agent keeps looking in the wrong place. CX Codex +1 441installs layers-domain jamiemill layers-domain is a Claude Code skill for mapping domain concepts, terminology clashes, and bounded contexts before product design. CX Codex +1 2,000installs layers-conceptual-model jamiemill The layers-conceptual-model skill maps a product’s objects, relationships, states, and vocabulary before interface work. Use it when the domain model still needs decisions. CX Codex +1 2,000installs firecrawl-knowledge-ingest firecrawl firecrawl-knowledge-ingest — a skill to save documentation sites, help centers and knowledge bases as markdown or JSON. Handles JavaScript rendering, auth and pagination—requires Firecrawl API key. CX Codex +1 31,600installs open-knowledge-discovery Inkeep open-knowledge-discovery explains how OpenKnowledge works, guides repository setup with ok init, and previews loose Markdown files in a temporary session without touching repository files. CX Codex +1 15,300installs okf-knowledge-base Inkeep okf-knowledge-base is a Claude Code skill for creating and checking knowledge bundles in Open Knowledge Format. It applies to OKF files, okf plugin warnings, and decisions about types or links. CX Codex +1 9,400installs retrieving-developer-knowledge official Google LLC retrieving-developer-knowledge — a skill for Claude Code that retrieves official Google developer documentation. It pulls exact CLI flags, API signatures, and IAM roles straight into the conversation context. CX Codex +1 4,100installs

From the same set32

The whole set →
zoom-out zoom-out spawns parallel explorers across structure, knowledge, and decision history, then merges their reports into a single orientation map of the area. CX Codex +1 443installs zoom-out zoom-out is a Claude Code skill that maps an unfamiliar part of a project. It starts when someone asks to get oriented or takes over work in an unfamiliar subsystem. CX Codex +1 443installs structured-artifact structured-artifact — a skill for building structured HTML artifacts: the agent decides how to present the content first, then picks the tools. CX Codex +1 443installs qi-layer The qi-layer skill provides a structure for maintaining agent instructions in AGENTS.md and .context/CONTEXT.md. It activates when writing or updating project-level context. CX Codex +1 441installs md-validation The md-validation Claude Code skill checks Markdown links and Mermaid syntax. Run it after documentation edits and before committing. CX Codex +1 441installs md-validation md-validation is a Claude Code skill that checks Markdown links and Mermaid diagrams. It activates on requests to validate links or diagrams before delivery. CX Codex +1 441installs knowledge-layers knowledge-layers — a skill that decides which layer holds a piece of knowledge: AGENTS.md, .context/, KB, docs/ or a work directory. Useful when the agent keeps looking in the wrong place. CX Codex +1 441installs qi-layer qi-layer — a skill that sets the rules for writing and maintaining AGENTS.md and .context/CONTEXT.md so intent docs stay short and load-bearing. CX Codex +1 441installs

Project sponsors

Companies that keep this analytics open