gib/Panama
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Keep the personal half of the desktop in one place, and ask before installing it

Browse Source 
Agent instructions, skills, SSH host aliases and expansion triggers are worth
having identical on every machine one person owns, and belong in none of the
shared configuration. They live in user/ now, with a manifest saying where each
piece goes and a link-user stage that puts it there.

That stage does nothing unless the machine said yes. Somebody who clones Panama
to try the desktop keeps their own ~/.claude/CLAUDE.md exactly where it was;
the question names the destinations and defaults to no. Anything displaced goes
to config/old rather than being deleted.

~/.claude/CLAUDE.md and ~/.codex/AGENTS.md were byte-identical copies of one
file, which is the drift this exists to prevent.

Also adds the vitals toggles for the battery and Claude usage readouts, which
had preferences and no way to reach them.
This commit is contained in:
Gabriel Brown
2026-08-22 08:54:43 -04:00
parent 8b96d907a1
commit 89761a7da3
156 changed files with 16439 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
user/agents/skills/writing-for-agents/SKILL-MECHANICS.md
+125
View File
@@ -0,0 +1,125 @@
# Skill mechanics
The skill-specific branch of [`writing-for-agents`](SKILL.md): what changes when the document is a
skill. Everything else about writing it is the universal reference in `SKILL.md`.
## Where a skill lives
A personal skill lives **once**, at `~/.agents/skills/<name>/`, with Claude Code pointed at it by a
symlink:
```bash
ln -s ../../.agents/skills/<name> ~/.claude/skills/<name>
```
`~/.agents/skills/` is the cross-runtime home: Codex, Copilot CLI, and Gemini CLI read it directly.
Writing a second copy into `~/.claude/skills/` gives you two files that drift, and the drift is
silent because each harness only ever reads its own. One home, one symlink per harness that needs it.
A skill that only makes sense inside one repo belongs in that repo, at `<repo>/.claude/skills/`.
## Frontmatter
```yaml
---
name: writing-for-agents # letters, numbers, hyphens only; matches the directory name
description: Use when ... # the skill's top-level context pointer
disable-model-invocation: true # Claude Code only; omit unless the skill is user-invoked
---
```
The whole frontmatter block caps at 1024 characters, so the description is the budget. Write it in
the third person: it is injected into the system prompt, not read as a reply.
The description is a context pointer, so every pointer rule in `SKILL.md` applies to it in full: name
the material and its trigger branches, front-load the leading word, one trigger per branch, and never
summarize the process.
## Codex metadata
Each skill also carries `agents/openai.yaml` beside its `SKILL.md`, holding Codex's skill-picker
metadata and, for a user-invoked skill, its half of the invocation setting:
```yaml
interface:
display_name: Writing for Agents
short_description: Reference for writing skills, AGENTS.md/CLAUDE.md, and pointed-at docs.
policy:
allow_implicit_invocation: false # user-invoked only; omit for model-invoked skills
```
**Invocation is set in two places, and they must agree.** `disable-model-invocation: true` governs
Claude Code; `policy.allow_implicit_invocation: false` governs Codex. A skill is user-invoked in both
harnesses or neither. Setting only the Claude Code half leaves the skill quietly model-invocable in
Codex, which is the same drift as two copies of the file, one field wide.
## Invocation
Two choices, trading the two loads:
| | Model-invoked | User-invoked |
|---|---|---|
| Who can fire it | The agent, you, or another skill | Only you, typing `/name` |
| Claude Code | Omit `disable-model-invocation` | `disable-model-invocation: true` |
| Codex | Omit the `policy` block | `policy.allow_implicit_invocation: false` |
| Description | Model-facing, carries trigger branches | Human-facing one-liner, triggers stripped |
| Cost | Permanent context load | Zero context load, paid in cognitive load |
Model-invocation always *includes* your reach: a description only ever adds agent discovery, it never
removes yours. So the question is only whether the agent must reach the skill on its own, or another
skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
A model-invoked skill whose content is all reference is also the one home for shared reference:
several skills can invoke it, so the material lives in one place.
Shared reference that two *user-invoked* skills both need can live in neither, since with no
descriptions neither can fire the other. Push it to a plain file outside the skill system and point
at it from both.
## Calling one skill from another
Write the dependency as an explicit instruction to call the tool, not a bare slash-name left for the
model to interpret:
> Call the Skill tool with "grilling".
The tool takes one skill per call. A step needing two is two calls, and saying "call it with X and Y"
reads as a single call taking both. Say instead:
> Call the Skill tool twice, for "grilling" and "domain-modeling".
This only works on **model-invoked** skills. A user-invoked skill can never be reached this way. When
a step's precondition is a user-invoked skill, phrase it as an instruction for the human: "tell the
user to run `/ticket`", never as a tool call.
Router prose that just names skills for a human to pick from is not invoking anything, so it keeps
`/name` labels as plain text.
## Splitting by invocation
The invocation cut, alongside the branch and sequence cuts in `SKILL.md`: split off a model-invoked
skill when you have a distinct leading word that should trigger it on its own, a word you actually
use in your prompts, or when another skill must reach it. You pay context load for the new
always-loaded description, so that independent reach has to be worth it.
## Router skills
When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured
by a **router skill**: one user-invoked skill naming the others and when to reach for each, so you
have one name to remember instead of many. It can only hint, never fire them, since user-invoked
skills have no description for anything but you to reach.
Write the router when you notice yourself forgetting a skill exists, not before. A router over three
skills is furniture.
## Done when
- The skill exists once under `~/.agents/skills/`, with a symlink from `~/.claude/skills/`.
- `name` matches the directory and uses only letters, numbers, and hyphens.
- The description names the material and its triggers, in the third person, under the 1024-character
frontmatter cap.
- The invocation choice is deliberate: model-invoked because the agent or another skill must reach
it, user-invoked otherwise.
- The invocation choice is written in both harnesses' fields, or in neither.
- Every cross-skill dependency is a named Skill tool call to a model-invoked skill, or an instruction
for the human where the target is user-invoked.
user/agents/skills/writing-for-agents/SKILL.md
+220
View File
@@ -0,0 +1,220 @@
---
name: writing-for-agents
description: Use when creating or editing a skill, CLAUDE.md, AGENTS.md, or any document an agent reads through a pointer; also when a skill fires unreliably, gets skipped mid-run, or has grown too long to trust.
---
# Writing for Agents
The reference for any document an agent consumes: a skill, a `CLAUDE.md`, a doc reached by a
pointer. The packaging differs; the writing does not. The same levers make each one predictable,
because the agent takes the same *process* every run rather than producing the same output.
When the document is a skill, read [SKILL-MECHANICS.md](SKILL-MECHANICS.md) for frontmatter,
invocation, and routers.
## Start from the failure
Name the failure you are fixing before writing a line. The form that fixes one kind measurably
backfires on another.
| Baseline failure | Form that fixes it | Form that backfires |
|---|---|---|
| Knows the rule, skips it under pressure | Prohibition + rationalization table + red flags | Soft guidance ("prefer", "consider") |
| Complies, but the output is the wrong shape (bloated, buried verdict, restated spec) | Positive recipe: state what the output **is**, its parts, in order | Prohibition list ("don't restate", "never narrate") |
| Omits a required element from something it already produces | Structural: a REQUIRED slot in the template it fills in | Prose reminders near the template |
| Behavior should depend on a condition | Conditional on an observable predicate ("if the brief exists, reference it") | Unconditional rule plus exemption clauses |
Under a competing incentive, an agent negotiates with "don't X". A recipe leaves nothing to
negotiate: the output matches the stated shape or it does not.
Two rules bind whichever form you pick:
- **No nuance clauses.** "Don't X unless it matters" reopens the negotiation. Express a real
exception as its own conditional on an observable predicate.
- **Exemption clauses do not scope.** "This limit does not apply to code blocks" still suppresses
code blocks. If part of the output must be exempt, restructure so the rule cannot reach it.
## Prompt the positive
Negation is the failure mode beside every lever here. Steering by prohibition drags the forbidden
behavior into context and makes it *more* available, not less. *Don't think of an elephant*, and the
elephant is all there is; the negation is a weak modifier the strongly-activated concept overruns,
so the ban half-reads as an instruction to do the thing.
State the target behavior instead, so the banned one is never spoken. A prohibition earns its place
only in row one of the table above, a discipline failure you cannot phrase positively, and even
there it pairs with the positive target so attention lands on what to do.
## Leading words
A **leading word** is a compact concept already living in the model's pretraining that the agent
thinks with while running the document: *tight*, *red*, *seam*, *tracer bullet*, *fog of war*.
Repeated as a token, never as a sentence, it accumulates a distributed definition and anchors a
whole region of behavior in the fewest tokens, by recruiting priors the model already holds.
It anchors twice. In the body, *execution*: the agent reaches for the same behavior every time the
word appears. In a pointer, *invocation*: when the same word lives in your prompts, your docs, and
your codebase, the agent links that shared language to the material and reaches it more reliably.
Coining your own works if you define it clearly, but a made-up word recruits no priors: you pay in
definition tokens what a pretrained word gives free. Reach for an existing word first.
Hunt for the refactor. A triad spelled out at three sites, or a pointer spending a sentence to
gesture at one idea, is a passage begging to collapse into a single token:
- "fast, deterministic, low-overhead" becomes *tight* (a *tight* loop).
- "a loop you believe in" becomes *red*, turning a fuzzy gate into a binary observable state.
Assume every document is carrying restatements that leading words retire. Go find them.
## Context pointers
A **context pointer** is a reference held in the agent's context that names some out-of-context
material and encodes the condition for reaching it. A skill's description is one; a line in
`CLAUDE.md` naming a doc is the same object. The pointer's *wording*, not its target, decides when
the agent reaches the material, and how reliably. A must-have target behind a weakly worded pointer
is a variance bug: sharpen the wording first, and inline the material only if sharpening fails.
A pointer does two jobs: name what the material is, and list the **branches** that should trigger
reaching it (a branch is a distinct case the document handles, so different runs take different
paths through it). Every word of an always-loaded pointer costs on every turn, so it earns harder
pruning than the body:
- **Front-load the leading word.** The pointer is where it does its triggering work.
- **One trigger per branch.** Synonyms that rename a single branch are one branch written twice.
- **Cut identity the body already carries.**
- **Name the material, never its process.** A pointer that summarizes the workflow becomes a
shortcut the agent takes *instead of* reading the body: a description saying "review between
tasks" produced one review where the body specified two. Name what the document covers and when
to reach it; let the body own the steps.
## The two loads
Every document and pointer you add spends one of two budgets:
- **Context load** is the cost of always-loaded material on the agent's window: a `CLAUDE.md` line,
a skill description, anything sitting in context every turn, spending tokens and attention whether
or not it fires.
- **Cognitive load** is the cost on you: which documents exist and when to reach for each. You are
the index. Not a cost to minimize; it is the price of your own agency. Spend it where your
judgment matters, remove it where it does not.
Material reached only through a pointer escapes context load at the price of the pointer's own line.
Material with no pointer at all rides entirely on cognitive load.
## Information hierarchy
A document is built from two content types: **steps** (the ordered actions the agent performs) and
**reference** (definitions, rules, facts consulted on demand). The two mix freely: all steps, all
reference, or both. The core decision is where each piece sits on the ladder, ranked by how
immediately the agent needs it:
1. **In-file step**: the primary tier, what the agent does, in order.
2. **In-file reference**: consulted on demand. Often a legitimately flat peer-set (every rule of a
review on one rung), which is a fine arrangement, not a smell.
3. **Disclosed reference**: pushed into a separate file behind a pointer, loaded only when the
pointer fires.
Push too little down and the top bloats; push too much and you hide material the agent needs. That
tension is the whole decision.
**Progressive disclosure** is the move down the ladder so the top stays legible. Not primarily a
token optimization: it is how the hierarchy is protected. **Branching is the test**: inline what
every branch needs, and disclose what only some branches reach. In a document with steps, in-file
reference that should be disclosed buries them and turns attending to them into a coin-flip.
**Co-location** is the within-file companion. The ladder decides how far down a piece sits;
co-location decides what sits beside it once there. Keep a concept's definition, rules, and caveats
under one heading rather than scattered, so reading one part brings its neighbors with it. The test:
the document should read like documentation written for the agent.
**Sprawl** is the failure mode here: a document simply too long, even when every line is live and
unique. Attention thins across the excess, and every extra line is one more to keep relevant. The
cure is the ladder.
## Completion criteria
Every step ends on a **completion criterion**, the condition that tells the agent the work is done.
Two properties make it a lever:
- **Clarity**: can the agent tell done from not-done? A vague bound ("understanding reached")
invites **premature completion**, ending the step before it is genuinely done, attention slipping
to *being done*. The visible steps still ahead supply the pull; the criterion's clarity is the
resistance. Defend in order: sharpen the bound first, since that is local and cheap; only if it is
irreducibly fuzzy *and* you observe the rush, split the sequence to hide the later steps. Hiding
works only across a real context boundary, a handoff or a subagent dispatch. An inline call leaves
the later steps in context and clears nothing.
- **Demand**: how much it requires. "Every modified model accounted for" forces thorough work where
"produce a change list" does not. Demand drives the digging the agent does within the work, and it
is not step-bound: "every rule applied" binds a body of flat reference just as "every step done"
binds a sequence.
The strongest criteria are both checkable and exhaustive.
## When to split
Splitting one document into two spends one of the two loads, so split only when the cut earns it:
- **By branch**: the disclosure test above. The most common correct cut.
- **By sequence**: split a run of steps where the later steps tempt the agent to rush the one in
front of it. Beware the reverse: merging sequences exposes each step to what follows, inviting
premature completion.
- **By invocation**: skill-specific, see [SKILL-MECHANICS.md](SKILL-MECHANICS.md).
## Pruning
- **Single source of truth.** One authoritative place per meaning, so changing the behavior is a
one-place edit. **Duplication** costs maintenance and tokens, and inflates a meaning's prominence
on the ladder past its real rank. It is the accidental inverse of a leading word, which repeats a
token on purpose, never the meaning.
- **The environment is a source of truth too.** `package.json` scripts, config files, the directory
layout, `--help` output. A document that restates it is a **cache**: a copy of a lookup, earning
its load only when the lookup is expensive. Cache what the agent cannot find by looking, such as
the unwritten convention, the reason behind a choice, the gotcha no config confesses. Leave the
one-command lookups to the environment, where they cannot go stale.
- **Relevance.** Does the line still bear on what the document does? A line loses relevance by never
bearing on the task, or by going stale as the world it describes changes. Without a pruning
discipline the default fate is **sediment**: stale layers that settle because adding feels safe
and removing feels risky, until you must core down through them to find what is still live.
- **No-ops.** An instruction the model already obeys by default pays load to say nothing. The test
(does it change behavior versus the default?) is model-relative, not reader-relative: two people
disagreeing about a no-op disagree about the default, and settle it by running the document, not
by debate. When a sentence fails, delete the whole sentence rather than trim words from it. The
test also grades leading words: a word too weak to beat the default (*be thorough*, when the agent
is already thorough-ish) is a no-op, and the fix is a stronger word (*relentless*), not a
different technique.
## House conventions
- **One excellent example beats five mediocre ones.** Write it in the language the document actually
targets: TypeScript for application work, shell for infra. A complete, runnable, commented example
from a real scenario, not a fill-in-the-blank template.
- **Name for what it does**, verb-first. Gerunds suit processes: `writing-for-agents`,
`diagnosing-bugs`. Not `agent-doc-guidelines`.
- **No narrative.** "In the session where we found the Convex race condition" is not reusable. State
the technique.
- **Keep the document in sync with what it describes.** A document naming a script, flag, or path
owes the same upkeep as the code it names. A stale pointer is worse than no pointer, because the
agent follows it.
- **Supporting files only for a reusable tool or heavy reference.** A script, a template, or a
branch too large to inline. Principles and short patterns stay in the main file.
## Verifying
Scale the check to what the document does. Reference gets read back; discipline gets tested.
| The document is | Verify by |
|---|---|
| Pure reference (a vocabulary, an API guide) | Reading it back against the ladder and the pruning rules |
| A procedure you run yourself | Running it once on a real task; where it stalls is the bug |
| Behavior-shaping guidance: a rule expected to hold under pressure, or wording meant to change output shape | Baselining it first. Read [VERIFYING.md](VERIFYING.md) |
## Done when
- The failure being fixed is named, and the form matches its row in the table.
- Every rule is phrased as a positive target, except a discipline prohibition that cannot be.
- Each branch is inlined or disclosed on purpose, and the pointer to each disclosed file names its
material and its trigger.
- Every step carries a completion criterion that is checkable and exhaustive.
- No line restates the environment, duplicates a meaning, or fails the no-op test.
- The document is shorter than the material it replaced.
user/agents/skills/writing-for-agents/VERIFYING.md
+84
View File
@@ -0,0 +1,84 @@
# Verifying behavior-shaping guidance
The verification branch of [`writing-for-agents`](SKILL.md). Read it when the document is meant to
**change what an agent does**: a rule expected to hold under pressure, or wording meant to change the
shape of an output.
Reference skills do not need this. A vocabulary, an API guide, or a list of definitions is verified
by reading it back against the ladder and the pruning rules. Running this method on reference is
ceremony that buys nothing.
## Establish the baseline first
You cannot fix a failure you have not watched happen. Before writing the guidance, run the task
**without** it in a fresh context and record what the agent actually does, in its own words.
**The control decides whether to write anything at all.** If the no-guidance run does not exhibit the
failure, there is nothing to fix: stop, and do not author the guidance. Most guidance that turns out
to be a no-op would have died here. This step removes more work than it adds.
Where the failure does appear, capture the rationalizations verbatim. They are the raw material: a
discipline rule works by answering the specific excuse the agent reached for, not the excuse you
imagined it would.
## Micro-test the wording
Full scenario runs are the final gate, but they are slow per iteration. Test the wording itself
first:
1. **One fresh-context sample per call.** The system prompt is the realistic context the guidance
will live in, meaning the whole skill, not the guidance in isolation. The user message is a task
that tempts the failure.
2. **Always run the no-guidance control alongside.** Same rule as above: no failure in the control,
no guidance needed.
3. **Five or more reps per variant.** Single samples lie.
4. **Read every flagged match yourself.** Score programmatically if you like, but template echoes and
quoted counter-examples masquerade as hits, and automated counts overstate both failure and
success.
5. **Treat variance as a metric.** When guidance lands, the reps converge on the same shape. Five
different interpretations across five reps means the wording is not binding: tighten the form
before adding words.
Micro-tests verify wording. They do not replace a real run for a rule that has to survive pressure.
## Pressure-test a discipline rule
A rule an agent follows when nothing is at stake is untested. Combine pressures in one scenario:
- **Time**: the change is urgent, something is broken in production.
- **Sunk cost**: the work is nearly done and the rule would discard it.
- **Authority**: someone senior said to skip it.
- **Exhaustion**: it is the eighth iteration of a long loop.
Success is the agent following the rule with all of them stacked. Each new rationalization it
invents is the next thing to close.
## Close the loopholes
Do not just state the rule; forbid the specific workaround the baseline produced. "Delete it" invites
"I'll keep it as reference"; "Delete it. Not as reference, not to adapt while rewriting. Delete means
delete" does not.
Two structures earn their place in a discipline skill, and only there:
- **A rationalization table**, one row per excuse from the baseline runs, each answered:
| Excuse | Reality |
|---|---|
| "Too simple to test" | Simple code breaks. The test takes 30 seconds. |
- **A red-flags list** of the thoughts that mean the agent is mid-rationalization, so it can catch
itself: *"this is different because..."*, *"I already checked it manually"*.
Add the foundational line early, because it closes a whole class of argument at once:
**violating the letter of the rule is violating its spirit.**
Both structures are the row-one form from `SKILL.md`. Reaching for them on a shaping failure makes
the output worse, so confirm the failure is discipline before writing either.
## Done when
- A no-guidance control was run, and it exhibited the failure the guidance addresses.
- The guidance answers rationalizations observed in that run, not invented ones.
- Reps with the guidance converge on one shape rather than five.
- For a discipline rule: it holds with time, sunk cost, and authority pressure stacked.
user/agents/skills/writing-for-agents/agents/openai.yaml
+3
View File
@@ -0,0 +1,3 @@
interface:
display_name: Writing for Agents
short_description: Reference for writing skills, AGENTS.md/CLAUDE.md, and pointed-at docs.