JasonColapietro/suede-creator-skills / skills/suede-copy
suede-copy
VerifiedUse when asked "rewrite this landing page" or to write, sharpen or retune conversion copy, public explainers and agent-facing docs across surfaces. Suede applies voice, frameworks, labeled variants, answer-first SEO/AEO, evidence boundaries and a 70-point ship score. NOT FOR: a standalone anti-slop pass (use suede-deslop), high-stakes research orchestration (use suede-ship-copy), visual design (use suede-design), or scored SEO audits (use suede-seo-audit).
| File | Kind | Size |
|---|---|---|
| CARD.md | markdown | 4.3 KB |
| SKILL.md | skill md | 16.3 KB |
| agents/openai.yaml | config | 422 B |
| references/edit-passes.md | markdown | 3.1 KB |
| references/email-and-social-formats.md | markdown | 4.9 KB |
| references/frameworks-and-personas.md | markdown | 2.8 KB |
| references/headline-and-cta-formulas.md | markdown | 3.5 KB |
| references/usage-contract.md | markdown | 864 B |
| references/writing-for-agents.md | markdown | 6.4 KB |
references/writing-for-agents.md
View on GitHub# Suede Agent-Doc Method
Read this when the document's reader is a model: a `SKILL.md`, a `CLAUDE.md`,
an `AGENTS.md`, or a reference file a skill points to. Human copy competes for
attention. Agent docs spend it: every always-loaded line costs tokens on every
turn, used or not. The target is a repeatable route through the document, so
run 12 behaves like run 1.
## 1. Trigger lines
A trigger line is any text resident in the agent's context that names material
outside it and says when to go get it. A skill `description` is one. So is an
`AGENTS.md` line that names a doc.
The wording of the trigger line, more than the material behind it, decides
whether the agent reaches that material. Must-reach content behind a vague
trigger gets found on some runs and missed on others. Sharpen the trigger
before you inline the content.
A good trigger line does two jobs: names what the material is, and lists each
distinct case that should fire it.
| Problem | Repair |
|---|---|
| The deciding word sits mid-sentence | Move it to the front |
| Two phrases name the same case | Keep one |
| The trigger repeats what the body already says about itself | Cut it from the trigger |
Weak: "Can be used for a variety of documentation tasks."
Strong: "Use when authoring a skill, fixing a trigger that misfires, or
splitting a long agent doc."
## 2. Two budgets
Every addition spends one of two budgets. Name which before you add it.
- **Resident cost:** tokens loaded every turn (descriptions, `AGENTS.md`
lines, anything always in context).
- **Recall cost:** what the human must remember (which docs exist, when to
reach for each).
Recall cost is not waste. It is where human judgment lives. Spend it where a
person should decide; remove it where nobody needs to.
## 3. Three shelves
Each piece of a document sits on one of three shelves:
1. **Steps in the file:** what the agent does, in order.
2. **Reference in the file:** facts consulted on demand. A flat list of peers
is fine here.
3. **Reference behind a pointer:** a separate file loaded only when the trigger
fires.
The branching test decides the shelf: keep in the file what every path needs;
move out what only some paths use. Keep a concept's definition, rules, and
exceptions under one heading so reading one part brings the rest.
Suede thresholds: reference over about 100 lines moves to `references/` with a
contents list; under about 50 stays inline; in between, stay inline unless it
pushes `SKILL.md` past 500 lines. A document can be too long even when every
line is live. The fix is moving reference down a shelf, not trimming words.
## 4. Done tests
Every step ends on a test the agent can check.
**Make it checkable.** "Once the code is understood" lets the agent stop early
because the next step is already pulling at it. "Every exported function has a
one-line note naming its callers" does not. Sharpen the test first. Split the
sequence across a real handoff (a subagent or a new session) only when the test
cannot be sharpened and you have watched the agent rush it. An inline call does
not hide later steps; they are still in context.
**Make it demanding.** "Every modified model accounted for" drives the digging
that "list the changes" never triggers. A rule list works the same way:
"every rule applied" binds as hard as "every step done".
## 5. When to split a document
A split spends a budget, so it has to pay for itself.
- **Split a sequence** when later steps tempt the agent to rush the current
one. Merging two sequences invites the same rush.
- **Split off a new skill** when a distinct phrase should fire it on its own,
or another skill must reach it. The price is one more resident description.
## 6. Anchor words
An anchor word is a short concept the model already knows that it can think
with while it works: *tight*, *red*, *tracer*, *ledger*. Repeat the word; do
not keep re-explaining it. Each repetition pulls the same behavior.
- "fast, deterministic, low overhead" → a *tight* loop
- "a check you actually trust" → the test goes *red* on the bug, or it does not
A coined word works only after you define it, and you pay for that definition
in tokens. A familiar word arrives with its meaning already loaded. When the
same word appears in prompts, docs, and code, it also helps the agent connect
a request to the right material.
## 7. Write the target, not the ban
Telling a model what not to do puts the unwanted behavior into context. State
the behavior you want.
Weak: "Don't write long rambling comments."
Strong: "Write one-line comments."
Keep a prohibition only for a hard guardrail with no positive phrasing, and
put the positive target next to it.
## 8. Pruning
- **One meaning, one place.** Duplicates cost tokens, drift apart, and make a
minor rule look major.
- **Let the environment speak.** `package.json`, config, directory layout, and
`--help` already answer many questions. Restate them only when the lookup is
expensive. Write down what no file reveals: the unwritten convention, the
reason for a choice, the trap.
- **Clear stale layers.** Lines that no longer bear on the task pile up because
adding feels safe and deleting feels risky. Delete them.
- **Cut sentences the model already obeys.** Test each line against the
model's default behavior. If removing it changes nothing, remove the whole
sentence. A weak instruction ("be thorough") fails this test too; replace it
with a stronger, more specific demand.
## 9. Who can fire the skill
| | Model-invoked | User-invoked only |
|---|---|---|
| Claude Code frontmatter | no `disable-model-invocation` | `disable-model-invocation: true` |
| Codex `agents/openai.yaml` | `allow_implicit_invocation: true` | `allow_implicit_invocation: false` |
| `description` | written for the model, lists trigger cases | a one-line label for humans |
| Resident cost | every turn | none |
| Recall cost | none | the human must remember it |
Model-invoked skills stay reachable by name, too. Choose user-invoked when a
skill should only ever run on request (a code grade, a destructive cleanup).
Shared reference that two user-invoked skills both need belongs in a plain
file outside either skill, because neither can fire the other. When
user-invoked skills grow past what a person can remember, add a router skill
that names them and when to use each.
## Deliverable
Return the revised document, then counts: trigger lines sharpened, duplicate
cases merged, done tests sharpened, restatements collapsed into anchor words,
no-op sentences cut. Then the Ship Gate score.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |