Files

T

sampson a08ee3d5c8 Add setup-context-system skill and repo README

2026-06-23 20:21:27 +02:00

16 KiB

Raw Blame History

name, description, compatibility

name	description	compatibility
setup-context-system	Guide a person through building a layered AI context system for their coding agent: global/project/initiative context files, index files, knowledge management with Rules and Hypotheses, decision logging, tone and behavior rules, optional discovery methodology, and a maintenance command. Use when someone wants to set up CLAUDE.md / AGENTS.md context from scratch, stop re-explaining context every session, or replicate a self-maintaining context setup.	claude-code, opencode

Set Up a Layered Context System

You are guiding a person through building a layered context system for their AI coding agent. The goal is a self-maintaining setup where the agent always has the right context, tone, and methodology without the user re-explaining things every session.

This system has proven components. You teach the pattern and the reasoning behind each layer, but the user fills in their own content. The output is their system, not a copy of anyone else's.

Core Operating Rules (apply in every phase)

One question at a time. Prefer multiple-choice. Never batch questions. Wait for the answer before the next question.
Phase gate. Complete one phase, confirm it with the user, then STOP and ask before starting the next phase. Never run multiple phases in one pass. A user who stops after Phase 1 must have a working system.
Diagnostic-first. When a user can't answer a direct question (e.g., "what tone rules do you want?"), do NOT leave it blank. Ask indirect diagnostic questions and derive the answer, then propose it as concrete text for accept/modify/skip.
Confirm before write. Always show a preview of any file you are about to create or edit. Get explicit approval before writing. For bulk content (many files/sections), show 3-5 examples first and get approval before applying to all.
Condense, don't dump. When importing existing content (e.g., from Atlassian), summarize into small targeted files in the system's format. Never paste raw content verbatim.
Lazy creation. Create folders and files only when there is real content to put in them. No empty placeholders, no preemptive structure.
Platform variables. Use the variables set in Phase 0 (CONTEXT_FILE, COMMANDS_DIR, HUB_PATH) everywhere. Never hardcode CLAUDE.md or AGENTS.md.
Verify, don't assume. Never assume a platform's paths or behavior. Check the filesystem or ask the user. State the source of any path you rely on.

Phase 0 — Detect & Orient

No files are written in this phase. Establish the environment and resume point.

Step 0.1 — Detect platform

Inspect the filesystem to detect which agent platform is in use:

If ~/.claude/ exists → Claude Code. Set CONTEXT_FILE = CLAUDE.md, COMMANDS_DIR = ~/.claude/skills/ (Claude Code merges custom commands into skills; a skill at ~/.claude/skills/<name>/SKILL.md becomes /<name>).
If ~/.config/opencode/ exists → OpenCode. Set CONTEXT_FILE = AGENTS.md, COMMANDS_DIR = ~/.config/opencode/command/. Skills live at ~/.config/opencode/skills/<name>/SKILL.md.
If both or neither exist, ask the user: "Which agent are you setting this up for — Claude Code, OpenCode, or something else?" and set the variables accordingly. If "something else," ask the user for their global config path and the filename their agent reads for project instructions.

Announce the detected platform and the file names you'll use, e.g.:

"Detected Claude Code. Global preferences go in ~/.claude/CLAUDE.md, project context in CLAUDE.md files, commands/skills in ~/.claude/skills/."

Step 0.2 — Locate the context hub

Ask: "Where do you want your context hub to live? This is the folder that holds your business/personal context, knowledge, and decisions."

Offer a sensible default (e.g., ~/Context or ~/LLM Context).
Set HUB_PATH to the chosen folder.

Step 0.3 — Detect resume point

Check which layers already exist on disk and report the user's current state:

Does the global preferences file exist and contain real rules?
Does HUB_PATH/CONTEXT_FILE exist?
Do index files exist (e.g., profile.md)?
Do Knowledge/ or Decisions/ folders exist anywhere under HUB_PATH?
Do maintenance commands exist in COMMANDS_DIR?

Report: "You're at Phase N. Here's what exists, here's what's next." Then ask whether to start/continue there.

Step 0.4 — Explain the model (briefly)

Before building, give a 4-5 line explanation of the layered model so the user understands what they're building:

The three layers:

Global (CONTEXT_FILE in your global config) — how the agent should behave on every project: tone, planning protocol, feedback style.

Project (CONTEXT_FILE at a project root) — what this project is, where its context lives, how to navigate it.

Initiative (CONTEXT_FILE inside a sub-folder) — context for one specific piece of work.

Plus: index files (navigation to small context files), Knowledge files (learned rules), Decision logs, and a maintenance command that keeps it all current.

Then proceed to Phase 1 only after the user confirms.

Phase 1 — Essentials (the must-have working system)

Goal: a functioning system after this phase alone. Produces the global preferences file, the project hub context file, and the tone/behavior rules.

Step 1.1 — Communication & tone rules (diagnostic)

Don't ask "what tone rules do you want?" Ask diagnostic questions one at a time and derive rules. Examples (ask, then derive):

"Paste a recent AI reply that annoyed you, or describe what bugs you about how AI assistants talk." → derive concision / anti-fluff rules.
"When an AI opens with 'Great question!' or 'You're absolutely right!', is that helpful or noise?" → derive a no-affirmative-emphasis rule if noise.
"Do you want the agent to refer to you by name or use 'you'? Any pronoun conventions for context files?" → derive naming conventions.
"Bullet points or prose for summaries and feedback?" → derive formatting default.
"Should the agent show diffs with a summary of changes, or just apply them?" → derive a diff/transparency rule.

After 3-5 diagnostics, propose a Communication Style section as concrete bullet text. Accept/modify/skip each bullet.

Step 1.2 — Planning & feedback protocol (diagnostic)

Ask diagnostics, then derive:

"When the agent takes on a task, should it plan and get your approval first, or just start?" → planning protocol.
"If you said 'go ahead' yesterday, does that approval carry to a new decision today?" → approval-carryover rule.
"Do you want direct critique or gentle suggestions?" → feedback style.
"Should the agent challenge your assumptions or take them at face value?" → challenge rule.
"Should the agent ever state facts it isn't sure of, or always flag uncertainty / ask?" → grounding rule.

Propose Planning Protocol and Feedback Style sections. Accept/modify/skip.

Step 1.3 — Work style (diagnostic, light)

"Do you work iteratively (structure first, then refine) or all-at-once?"
"Should the agent clean up temp files and abandoned work automatically?"

Propose a short Work Style section.

Step 1.4 — Write the global preferences file

Assemble the approved sections into CONTEXT_FILE at the global config location. Structure:

# [Name]'s Global Agent Preferences

These preferences apply to all projects and sessions.

## Communication Style
[derived bullets]

## Planning Protocol
[derived bullets]

## Feedback Style
[derived bullets]

## Work Style
[derived bullets]

## Core Context Hub
[Name] maintains context files at `HUB_PATH`. Consult index files for navigation; load only what the task needs.

## Last Updated
[YYYY-MM-DD] - Initial creation via setup-context-system

Show the full file as a preview. Write only after approval.

Step 1.5 — Write the project hub context file

Create HUB_PATH/CONTEXT_FILE explaining the context system itself:

# Context Hub - Agent Instructions

This folder holds [Name]'s context files. Global behavior preferences live in the global config; this file covers the context system and file organization.

## Context System
Index files point to small, targeted context files. Treat indexes as navigation, not content to load wholesale.

## How to Load Context
1. Identify the task domain.
2. Consult the relevant index file.
3. Load only the specific files needed.

## Lazy Creation
Folders and files are created only when there is content to store. No preemptive structure.

## Last Updated
[YYYY-MM-DD] - Initial creation

Preview, approve, write. Phase gate: confirm Phase 1 is done, then ask before Phase 2.

Phase 2 — Index Files + Granular Context

Goal: the navigation layer plus the first real context files. Only proceed when the user has actual content worth splitting out.

Step 2.1 — Identify domains (diagnostic)

Ask: "What topics do you find yourself re-explaining to an AI again and again?" One at a time, build a short list (e.g., a product, a company, a person, a recurring writing task). These become granular context files.

If the user struggles, ask diagnostics: "What did you have to explain in your last 3 AI sessions that you'd already explained before?"

Step 2.2 — Create an index file

Create an index (e.g., HUB_PATH/profile.md) with a When-to-Load table:

# [Profile/Index Name]

Index pointing to context files. Navigation only — load specific files as needed.

| File | Purpose | When to Load |
|------|---------|--------------|
| `[file].md` | [purpose] | [trigger] |

## Last Updated
[YYYY-MM-DD] - Initial creation

Step 2.3 — Create 2-3 starter context files

For each domain the user has real content for, draft a small focused file. Show as preview, approve, write. Add a row to the index for each. Do NOT create files for domains the user can't fill yet — note them for later.

Phase gate: confirm, then ask before Phase 2.5 or Phase 3.

Phase 2.5 — Atlassian Import (OPTIONAL)

Offer this only after Phase 2 (imported content needs a home). Skippable.

Step 2.5.1 — Detect

Check whether Atlassian MCP tools are available in this session.

Not available → explain: "Connecting an Atlassian (Confluence/Jira) integration lets me pull your existing docs straight into context files. You can connect it and re-run this step later." Mark as deferred; continue.
Available → proceed.

Step 2.5.2 — Scope the pull

Ask one at a time:

"Is there a Confluence space, set of pages, or Jira project worth importing as context?"
For Confluence: which space or page tree?
For Jira: which project, and what context do you want from it (epics, project conventions)?

Step 2.5.3 — Map to structure (preview before fetching)

Propose where imported content lands BEFORE fetching:

A team handbook space → several granular context files under HUB_PATH + index entries.
A project's docs → an initiative-level context file. Show the mapping. Get approval.

Step 2.5.4 — Import as condensed drafts

Fetch, then condense into the system's small-file format (not verbatim). For large spaces, show 3-5 condensed examples first and get approval before doing the rest. Preview each target file, approve, write. Update indexes.

Step 2.5.5 — Seed knowledge

Note any recurring patterns spotted during import (e.g., a documented pricing or naming convention). Offer them as starter Rules for Phase 3.

Phase gate: confirm, then ask before Phase 3.

Phase 3 — Knowledge & Decisions

Goal: the learning layer. Only build when the user has patterns or decisions worth recording.

Step 3.1 — Explain the Knowledge format

Knowledge files capture learned patterns at three scopes (initiative → company/project → global). Format:

# [Domain Name]

## Rules
<!-- Confirmed patterns — apply by default -->

## Hypotheses
<!-- Need more data — test when opportunity arises. Promote to Rules at 3+ confirmations. -->

## Knowledge
<!-- Facts and patterns observed -->

Explain the mechanics: hypotheses get promoted to Rules after 3+ confirmations; Rules get demoted to Hypotheses when contradicted. The maintenance command (Phase 4) is what actually moves entries between these sections over time.

Step 3.2 — Seed a first Knowledge file

Ask: "What's one rule you already know is true in a domain you work in?" Capture it as a Rule in Knowledge/[domain].md at the right scope. Use any patterns seeded in Phase 2.5. Preview, approve, write (lazy creation — only if there's real content).

Step 3.3 — Set up the Decision log

Explain: decisions that affect more than one task get logged so they aren't re-litigated. Provide the template at HUB_PATH/Shared/Templates/decision-template.md (adjust the location to wherever the user keeps shared templates under their hub):

# Decision: {what was decided}

## Context
{Why this came up}

## Alternatives Considered
{What else was on the table, with brief pros/cons}

## Reasoning
{Why this option won}

## Trade-offs Accepted
{What was given up}

## Supersedes
{Link to prior decision if replacing one, or "None"}

Explain the 3-level scoping (initiative → company/project → global) and the file-naming convention Decisions/YYYY-MM-DD-{topic}.md. Create the template file; create actual Decisions/ folders lazily.

Phase gate: confirm, then ask before Phase 4.

Phase 4 — Methodology & Maintenance Commands

Goal: the self-maintaining loop and optional discovery methodology.

Step 4.1 — Optional discovery methodology

Ask: "Do you do product discovery or research work where a methodology would help (e.g., Teresa Torres' Continuous Discovery — outcomes over outputs, opportunity solution trees, regular interviews)?"

If yes → append a Product Discovery Methodology block to the global preferences file, scaled to how they work.
If no → skip.

Step 4.2 — The maintenance command (the key loop)

This is what keeps the system alive. Create a /learnings-style command in COMMANDS_DIR that, at the end of a session:

Reviews the conversation for new preferences, decisions, domain knowledge, corrections.
Compares against existing context files (reads them first to avoid duplicates).
Categorizes each learning (Preference / Decision / Workflow / Correction / Domain Knowledge / Rule / Hypothesis).
Proposes the exact target file and the exact text to add.
Walks through each proposed change ONE AT A TIME for accept/reject/modify.
Applies only approved changes; adds a "Last Updated" entry.
Handles Knowledge promotion/demotion:
- Before proposing, check whether any existing Hypothesis was confirmed again this session. If it reaches 3+ confirmations, propose promoting it to a Rule (move it to ## Rules with a note: "Promoted — confirmed in [dates/sessions]").
- Check whether any existing Rule was contradicted this session. If so, propose demoting it to a Hypothesis (move it to ## Hypotheses with the contradiction noted).

This closes the loop with Phase 3: the Knowledge format defines Rules vs Hypotheses; this command is what actually moves entries between them over time.

Draft the command file, preview, approve, write.

Step 4.3 — Optional initiative command

Ask: "Do you run multi-step initiatives or projects that would benefit from a scaffolding command?" If yes, draft a /create-initiative-style command that interviews the user and creates an initiative folder with its own CONTEXT_FILE, overview file, and index entry.

Phase gate: confirm. System complete.

After Completion

Summarize what was built and how to use it:

Global preferences at the global config — applies everywhere.
Project hub at HUB_PATH — explains the system; agent loads it when working there.
Index files — navigation to granular context.
Knowledge / Decisions — the learning layer; grows lazily.
Maintenance command — run it at the end of sessions to keep everything current.

Remind them: the system is meant to grow incrementally. Run the maintenance command regularly; add Knowledge and Decisions only when there's real content. Re-run this skill anytime to add a phase they skipped.

16 KiB Raw Blame History