New: Earn 20% as an AgentAlley affiliate. Share your link and earn on every sale you refer. Join now New: Earn 20% as an affiliate. Join now

Intent Documentation Layer

Qi layer

by haowjy · Apache-2.0 license · ★ 506 on GitHub

Qi layer cover

Use when writing or maintaining AGENTS.md, .context/CONTEXT.md, or CLAUDE.md mirrors: keep intent docs minimal and load-bearing.

---
name: qi-layer
description: 'Use when writing or maintaining AGENTS.md, .context/CONTEXT.md, or CLAUDE.md mirrors: keep intent docs minimal and load-bearing.'
---

# qi-layer

`/qi-maintenance` owns when colocated knowledge must move with source changes.
This skill owns how to write and structure that knowledge.

Load `/knowledge-layers` for where each layer lives and what it holds.
Load `/llm-writing` if it isn't already loaded.

This skill is about **how to write and maintain** the directory-local pair:
AGENTS.md and `.context/CONTEXT.md`. The pair governs any tree agents work
in — code, the KB, docs, work directories. AGENTS.md loads into an agent's
bounded context as standing instructions: write it like a prompt, minimal,
every line load-bearing.

Overview

/qi-maintenance owns when colocated knowledge must move with source changes. This skill owns how to write and structure that knowledge.

Manual install (npx, ZIP)
Claude Codenpx skills add haowjy/creative-writing-skills --skill qi-layer -g -a claude-code
Claude Code (degit)npx degit haowjy/creative-writing-skills/cw/skills/qi-layer#main ~/.claude/skills/qi-layer
Claude.ai / desktopZip the folder and upload it under Settings → Capabilities → Skills.
Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

  • SKILL.md5.3 KB
Read SKILL.md here
haowjy/main1 file shown
SKILL.md
Show the full text118 lines

qi-layer

/qi-maintenance owns when colocated knowledge must move with source changes. This skill owns how to write and structure that knowledge.

Load /knowledge-layers for where each layer lives and what it holds. Load /llm-writing if it isn't already loaded.

This skill is about how to write and maintain the directory-local pair: AGENTS.md and .context/CONTEXT.md. The pair governs any tree agents work in — code, the KB, docs, work directories. AGENTS.md loads into an agent's bounded context as standing instructions: write it like a prompt, minimal, every line load-bearing.

The Four Principles

  1. Fractal Compression: leaf AGENTS.md summarizes its directory's content; parent AGENTS.md summarizes its children. Each level is a compression of the level below.
  2. Hierarchical Summarization: root provides broad architectural frame. Leaves provide local working knowledge. Agents accumulate understanding as they descend.
  3. LCA Deduplication: shared knowledge appears once at the shallowest node covering all relevant paths. Never duplicate between siblings.
  4. Progressive Disclosure: give just enough to work correctly at this level. Link to .context/CONTEXT.md for depth.

Writing AGENTS.md

Agents read AGENTS.md before opening anything else in the tree — write for that moment. Ask: what must someone understand before working here? That's what AGENTS.md captures.

Keep AGENTS.md as short as the directory allows, rarely past 200 lines. Include only what has substance:

  • Purpose: what this area IS and what it ISN'T (1–3 sentences)
  • Mental model: how to think about this area, key abstractions
  • Key rules: constraints, what breaks if you get it wrong
  • Anti-patterns: what NOT to do here
  • Downlinks: to .context/ for depth, to related areas

An agent that only reads AGENTS.md should be able to work correctly here. An agent that also reads .context/ should be able to change things safely.

Writing .context/CONTEXT.md

Reference depth, co-located with the code it describes. Where an agent goes when it needs contracts, architecture, or rationale in detail.

Sections (use only those with substance):

  • Contracts: interfaces, invariants, what breaks if violated
  • Architecture: component relationships, data flow, dependency direction
  • Rationale: why X over Y, rejected alternatives
  • Patterns: how to work here, concrete pitfalls

The .context/ directory is extensible: additional files alongside CONTEXT.md for specialized concerns.

What Does NOT Belong in AGENTS.md

Apply the every-session test: root AGENTS.md loads on every session. If knowledge is only relevant when working in a specific domain, it belongs in that domain's AGENTS.md or .context/, not root.

Apply the think-vs-lookup test: text whose removal would cause a wrong decision belongs in AGENTS.md. Text an agent would merely have to look up belongs in .context/. Text that changes no behavior gets deleted — agents already know how to code and follow common conventions.

Specific failure modes:

  • Session bleed: LLM working notes that calcified into the instruction file. Tells: status-update language ("deleted", "shipped", "deferred"), implementation terms packed without framing, history narration.
  • Reference material posing as intent: tables, command blocks, full scheme vocabularies, implementation specifics.
  • Redundant guards: prose warnings for invariants already enforced by tests or types. The code is the real guard; prose rots faster.
  • Duplicated knowledge: restating what lives in a skill, a domain .context/, or a KB page. Point, don't duplicate.
  • Domain-specific detail at root: URI scheme tables, gateway pricing internals, auth implementation details. These belong in their domain's AGENTS.md, not root.

Structural Rules

  • Relative paths for all links
  • AGENTS.md and .context/ at the same directory level (siblings)
  • Link to files, not headings (headings change more often)
  • Lateral links between .context/ directories with contracts between them
  • LCA deduplication: if two siblings share context, put it in the parent

CLAUDE.md Mirrors

Claude harnesses read CLAUDE.md, not AGENTS.md. Give every AGENTS.md a sibling CLAUDE.md whose first line is @AGENTS.md — normally the whole file. Run meridian qi claude-md-fix <target-root> on the containing tree after creating or moving AGENTS.md files: it creates missing mirrors, skips exact ones, and reports anything else as a conflict.

Never write shared instructions into CLAUDE.md. Claude-only knowledge is rare; when it exists, put it below the @AGENTS.md import and expect claude-md-fix to keep flagging the file, so the divergence stays visible.

Loading differs by level. At the root, each harness auto-loads its own file every session: Claude reads CLAUDE.md, others read AGENTS.md. In subdirectories, Claude auto-injects CLAUDE.md when it touches files there; other agents see nested AGENTS.md only by reading it on entry. Don't lean on Claude's auto-injection: a nested AGENTS.md carries the local additions an agent needs on entry, with everything else inherited from ancestors.

1---
2name: qi-layer
3description: 'Use when writing or maintaining AGENTS.md, .context/CONTEXT.md, or CLAUDE.md mirrors: keep intent docs minimal and load-bearing.'
4---
5 
6# qi-layer
7 
8`/qi-maintenance` owns when colocated knowledge must move with source changes.
9This skill owns how to write and structure that knowledge.
10 
11Load `/knowledge-layers` for where each layer lives and what it holds.
12Load `/llm-writing` if it isn't already loaded.
13 
14This skill is about **how to write and maintain** the directory-local pair:
15AGENTS.md and `.context/CONTEXT.md`. The pair governs any tree agents work
16in — code, the KB, docs, work directories. AGENTS.md loads into an agent's
17bounded context as standing instructions: write it like a prompt, minimal,
18every line load-bearing.
19 
20## The Four Principles
21 
221. **Fractal Compression**: leaf AGENTS.md summarizes its directory's
23 content; parent AGENTS.md summarizes its children. Each level is a
24 compression of the level below.
252. **Hierarchical Summarization**: root provides broad architectural
26 frame. Leaves provide local working knowledge. Agents accumulate
27 understanding as they descend.
283. **LCA Deduplication**: shared knowledge appears once at the shallowest
29 node covering all relevant paths. Never duplicate between siblings.
304. **Progressive Disclosure**: give just enough to work correctly at this
31 level. Link to `.context/CONTEXT.md` for depth.
32 
33## Writing AGENTS.md
34 
35Agents read AGENTS.md before opening anything else in the tree — write for
36that moment. Ask: **what must someone understand before working here?**
37That's what AGENTS.md captures.
38 
39Keep AGENTS.md as short as the directory allows, rarely past 200 lines.
40Include only what has substance:
41 
42- **Purpose**: what this area IS and what it ISN'T (1–3 sentences)
43- **Mental model**: how to think about this area, key abstractions
44- **Key rules**: constraints, what breaks if you get it wrong
45- **Anti-patterns**: what NOT to do here
46- **Downlinks**: to `.context/` for depth, to related areas
47 
48An agent that only reads AGENTS.md should be able to work correctly here.
49An agent that also reads .context/ should be able to change things safely.
50 
51## Writing .context/CONTEXT.md
52 
53Reference depth, co-located with the code it describes. Where an agent
54goes when it needs contracts, architecture, or rationale in detail.
55 
56Sections (use only those with substance):
57 
58- **Contracts**: interfaces, invariants, what breaks if violated
59- **Architecture**: component relationships, data flow, dependency direction
60- **Rationale**: why X over Y, rejected alternatives
61- **Patterns**: how to work here, concrete pitfalls
62 
63The `.context/` directory is extensible: additional files alongside
64CONTEXT.md for specialized concerns.
65 
66## What Does NOT Belong in AGENTS.md
67 
68Apply the **every-session test**: root AGENTS.md loads on every session.
69If knowledge is only relevant when working in a specific domain, it belongs
70in that domain's AGENTS.md or .context/, not root.
71 
72Apply the **think-vs-lookup test**: text whose removal would cause a
73*wrong decision* belongs in AGENTS.md. Text an agent would merely have to
74*look up* belongs in .context/. Text that changes no behavior gets
75deleted — agents already know how to code and follow common conventions.
76 
77Specific failure modes:
78 
79- **Session bleed**: LLM working notes that calcified into the instruction
80 file. Tells: status-update language ("**deleted**", "shipped", "deferred"),
81 implementation terms packed without framing, history narration.
82- **Reference material posing as intent**: tables, command blocks, full
83 scheme vocabularies, implementation specifics.
84- **Redundant guards**: prose warnings for invariants already enforced by
85 tests or types. The code is the real guard; prose rots faster.
86- **Duplicated knowledge**: restating what lives in a skill, a domain
87 .context/, or a KB page. Point, don't duplicate.
88- **Domain-specific detail at root**: URI scheme tables, gateway pricing
89 internals, auth implementation details. These belong in their domain's
90 AGENTS.md, not root.
91 
92## Structural Rules
93 
94- Relative paths for all links
95- AGENTS.md and .context/ at the same directory level (siblings)
96- Link to files, not headings (headings change more often)
97- Lateral links between `.context/` directories with contracts between them
98- LCA deduplication: if two siblings share context, put it in the parent
99 
100## CLAUDE.md Mirrors
101 
102Claude harnesses read CLAUDE.md, not AGENTS.md. Give every AGENTS.md a
103sibling CLAUDE.md whose first line is `@AGENTS.md` — normally the whole
104file. Run `meridian qi claude-md-fix <target-root>` on the containing tree
105after creating or moving AGENTS.md files: it creates missing mirrors, skips
106exact ones, and reports anything else as a conflict.
107 
108Never write shared instructions into CLAUDE.md. Claude-only knowledge is
109rare; when it exists, put it below the `@AGENTS.md` import and expect
110`claude-md-fix` to keep flagging the file, so the divergence stays visible.
111 
112Loading differs by level. At the root, each harness auto-loads its own
113file every session: Claude reads CLAUDE.md, others read AGENTS.md. In
114subdirectories, Claude auto-injects CLAUDE.md when it touches files there;
115other agents see nested AGENTS.md only by reading it on entry. Don't lean
116on Claude's auto-injection: a nested AGENTS.md carries the local additions
117an agent needs on entry, with everything else inherited from ancestors.
118 
View all files on GitHub →

Details

License
Apache-2.0
Stars on the repo
★ 506
Checked
Source
haowjy/creative-writing-skills ↗
Creator
haowjy · 22 listings
View creator

Similar skills

See all →
Browser Testing Suiteaddyosmani/agent-skills · by addyosmaniTests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data. Requires the chrome-devtools MCP server to be configured.★ 98.7k GitHub starsEverything MCPmodelcontextprotocol/servers · by modelcontextprotocolThis MCP server attempts to exercise all the features of the MCP protocol. It is not intended to be a useful server, but rather a test…★ 90.5k GitHub starsWeb Content Fetchermodelcontextprotocol/servers · by modelcontextprotocolA Model Context Protocol server that provides web content fetching capabilities. This server enables LLMs to retrieve and process content…★ 90.5k GitHub starsFilesystem Operationsmodelcontextprotocol/servers · by modelcontextprotocolNode.js server implementing Model Context Protocol (MCP) for filesystem operations.★ 90.5k GitHub starsLibrary Reference Toolupstash/context7 · by upstashThis skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.★ 62.3k GitHub starsChrome DevTools DebuggerChromeDevTools/chrome-devtools-mcp · by ChromeDevToolsUses Chrome DevTools via MCP for efficient debugging, troubleshooting and browser automation. Use when debugging web pages, automating browser interactions, analyzing performance, or inspecting network requests. This skill does not apply to `--slim` mode (MCP configuration).★ 52.4k GitHub stars

More from haowjy

Character Voice Simulatorhaowjy/creative-writing-skills · by haowjySpeak as a specified character from their current knowledge, voice, and emotional state. Use for skill-only workflows that need in-character conversation, voice discovery, or relationship pressure tests.★ 506 GitHub starsStory Research Assistanthaowjy/creative-writing-skills · by haowjyLoad when a story needs factual grounding the writer doesn't have: historical detail, cultural texture, domain accuracy, or how other authors handled similar material. Pass the question and story context; returns a sourced report the writer can draw from.★ 506 GitHub starsFiction Writing Craft Guidehaowjy/creative-writing-skills · by haowjyCraft references for writing fiction well: prose, scenes, style, voice, and genre/page-level technique. Load when a writer, critic, or muse needs how-to-write guidance rather than a production mode.★ 506 GitHub starsWriting Mode Guidehaowjy/creative-writing-skills · by haowjyCreative-writing addendum to /llm-writing. Load when putting prose on the page: draft, revise, bridge, vary, or polish.★ 506 GitHub starsMulti-Mode Writing Studiohaowjy/creative-writing-skills · by haowjyLoad when no subagents are available and one agent must plan, draft, critique, research, and capture memory by switching stances.★ 506 GitHub starsOutput Information Hierarchyhaowjy/creative-writing-skills · by haowjyLoad for large human-facing outputs: reports, docs, multi-section explanations, artifacts. Choose the right form for each beat (prose, diagram, table, mockup) and put the answer first, depth behind it. If the medium allows, use progressive disclosure.★ 506 GitHub stars