
cc-skills
AI Agent Skills
- GitHub stars
- 6
Install
/plugin install cc-skills@samberRun it inside Claude Code after adding the marketplace with /plugin marketplace add samber/cc.
Contents
Discovered from sourceSkills 21
Chrome Extension Development (Manifest V3)
This skill covers everything needed to build, debug, and publish Chrome extensions with MV3. It is organized as a routing document: read this file first to understand the architecture and decision points, then load the relevant reference file for implementation details.
Reference files
Read only the reference files relevant to the current task. Each file is self-contained.
| File | When to read |
|---|---|
references/manifest-v3.md | Setting up or modifying manifest.json, configuring icons, versioning |
references/service-worker.md | Background logic, lifecycle, state persistence, alarms, events |
references/content-scripts.md | Injecting code into pages, isolated/main world, dynamic injection, SPA handling, orphaning |
references/messaging-rpc.md | Communication between any contexts, typed protocols, RPC layer, async handler patterns |
references/ui-surfaces.md | Popup, options page, side panel, context menus, commands, notifications, omnibox, devtools panel |
references/storage.md | chrome.storage (local/sync/session), quotas, reactive patterns, framework hooks |
references/network-csp.md | HTTP requests from content scripts, CSP bypass relay, declarativeNetRequest, offscreen docs, CORS |
references/permissions.md | Required/optional permissions, host permissions, activeTab, runtime request flow |
references/web-accessible-resources.md | Exposing extension files to web pages, security implications |
references/typescript-build.md | TypeScript setup, project structure, build tools comparison, bundling |
references/publishing.md | Chrome Web Store submission, review process, rejection reasons, updates, privacy policy |
references/execution-contexts.md | Communication flow diagrams, per-context capabilities/limits, choosing the right messaging method |
references/debugging-mistakes.md | DevTools for extensions, testing SW termination, common gotchas, error patterns |
Architecture overview
A Chrome extension has up to 5 execution contexts that communicate via message passing:
┌──────────────────────────────────────────────────────────┐
│ Extension Process │
│ ┌─────────────────┐ ┌───────┐ ┌─────────┐ ┌──────┐ │
│ │ Service Worker │ │ Popup │ │ Options │ │ Side │ │
│ │ (background) │ │ │ │ Page │ │Panel │ │
│ │ - No DOM │ │ Full │ │ Full │ │ Full │ │
│ │ - Ephemeral │ │ DOM │ │ DOM │ │ DOM │ │
│ │ - All chrome.* │ │ All │ │ All │ │ All │ │
│ │ APIs │ │ APIs │ │ APIs │ │ APIs │ │
│ └────────┬─────────┘ └───┬───┘ └────┬────┘ └──┬───┘ │
│ │ chrome.runtime.sendMessage / connect │ │
└───────────┼────────────────┼───────────┼──────────┼──────┘
│ │ │ │
chrome.tabs.sendMessage │ │ │
│ │ │ │
┌───────────┼────────────────┼───────────┼──────────┼──────┐
│ Web Page ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Content Script │ │ Main World Script │ │
│ │ (isolated world) │◄──►│ (page context) │ │
│ │ - Shared DOM │ │ - Shared DOM │ │
│ │ - Own JS scope │ │ - Page JS scope │ │
│ │ - chrome.runtime │ │ - No chrome.* API │ │
│ │ - chrome.storage │ │ - Full page access│ │
│ │ - Subject to CSP │ │ - Subject to CSP │ │
│ │ (network only) │ │ (fully) │ │
│ └──────────────────┘ └──────────────────┘ │
│ ▲ window.postMessage │
│ │ (through shared DOM) │
└──────────────────────────────────────────────────────────┘
Communication flows (labeled channels)
┌───────────────────────────────────────────────────────────────────────────┐
│ Extension Process │
│ │
│ ┌─────────────────┐ chrome.runtime ┌───────┐ ┌─────────┐ ┌──────┐ │
│ │ Service Worker │◄─.sendMessage()──│ Popup │ │ Options │ │ Side │ │
│ │ (background) │◄─.connect()──────│ │ │ Page │ │Panel │ │
│ │ │ └───────┘ └─────────┘ └──────┘ │
│ │ - No DOM │ ┌────────────────────────────────────────────┐ │
│ │ - Ephemeral 30s │ │ SW cannot push to these pages. │ │
│ │ - All chrome.* │ │ Use: ports (.connect) or storage.onChanged │ │
│ └────────┬─────────┘ └────────────────────────────────────────────┘ │
│ │ │
│ chrome.storage.onChanged ◄── fires across ALL contexts simultaneously │
│ │
└───────────┼──────────────────────────────────────────────────────────────┘
│ chrome.tabs.sendMessage(tabId, ...) [SW must know tabId]
│
┌───────────┼──────────────────────────────────────────────────────────────┐
│ Web Page ▼ │
│ ┌──────────────────┐ window.postMessage ┌──────────────────┐ │
│ │ Content Script │◄───────────────────►│ Main World Script │ │
│ │ (isolated world) │ Custom DOM events │ (page context) │ │
│ │ │ │ │ │
│ │ chrome.runtime ───┼── to/from SW │ No chrome.* APIs │ │
│ │ chrome.storage │ │ Full page JS │ │
│ │ Shared DOM │ │ Shared DOM │ │
│ │ Page CSP (network)│ │ Page CSP (full) │ │
│ └──────────────────┘ └──────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
For detailed flow diagrams (three-layer bridge, cross-extension, storage broadcast) and a per-context breakdown of permissions, limits, and workarounds: → Read references/execution-contexts.md
Communication methods at a glance
| Method | Direction | Best for |
|---|---|---|
chrome.runtime.sendMessage | Any ext context → SW | One-shot request/response (90% of cases) |
chrome.tabs.sendMessage | SW → content script (by tabId) | Pushing data to a specific tab |
chrome.runtime.connect (Port) | Bidirectional | Streaming, progress, SW ↔ popup |
window.postMessage | Between worlds on same page | Page JS ↔ content script bridge |
chrome.storage.onChanged | Broadcast to all contexts | Settings sync, no messaging needed |
→ Full matrix with limits and edge cases: references/execution-contexts.md → Implementation patterns, typed protocols, RPC layer: references/messaging-rpc.md
Key architectural rules
-
Service worker is ephemeral. It terminates after 30s of inactivity. All state must be persisted to chrome.storage. All event listeners must be registered synchronously at the top level. Never use setTimeout/setInterval for anything beyond a few seconds. → Read
references/service-worker.md -
Content scripts run in the page's origin. Network requests from content scripts are subject to the page's CSP and CORS. To bypass, relay through the service worker. → Read
references/network-csp.md -
Messaging is the backbone. Every cross-context interaction uses chrome.runtime messaging. The #1 bug: forgetting to
return truefrom async message listeners. → Readreferences/messaging-rpc.md -
Permissions determine CWS review speed. Broad host_permissions trigger manual review (weeks). activeTab + optional permissions = fast automated review. → Read
references/permissions.md -
Popup is destroyed on blur. Side panel persists. Choose based on interaction duration. → Read
references/ui-surfaces.md
Decision tree: which context handles what?
"I need to run code when the user visits a page"
→ Content script. Static (manifest) for known URL patterns, dynamic (chrome.scripting) for user-triggered injection. Default to isolated world unless you need page JS access. → Read references/content-scripts.md
"I need to make an HTTP request to my API"
- From popup/options/side panel: direct fetch() works (extension origin, no CSP issues)
- From content script on a page with restrictive CSP: relay through service worker
- From service worker: direct fetch() works (requires host_permissions for the target domain) → Read
references/network-csp.md
"I need to store user settings"
- Settings that sync across devices: chrome.storage.sync (100KB limit)
- Large data or caches: chrome.storage.local (10MB, or unlimited with permission)
- Ephemeral state surviving SW restarts: chrome.storage.session → Read
references/storage.md
"I need to modify HTTP headers or block requests"
→ declarativeNetRequest (NOT webRequest, which lost blocking in MV3) → Read references/network-csp.md
"I need the page's JavaScript to talk to my extension"
→ Three-layer bridge: page (window.postMessage) → content script → service worker → Read references/messaging-rpc.md
"I need to understand what each context can and cannot do"
→ Read references/execution-contexts.md — per-context cards listing chrome.* access, DOM, network, storage, lifetime, hard limits, and practical workarounds.
"I need periodic background tasks"
→ chrome.alarms (minimum 30s interval). NOT setTimeout. → Read references/service-worker.md
"I need DOM APIs in the background" (DOMParser, Canvas, Audio)
→ Offscreen document. One per extension, only chrome.runtime available. → Read references/network-csp.md
"I need to authenticate with OAuth"
→ chrome.identity.launchWebAuthFlow() or chrome.identity.getAuthToken() (Google only) → Read references/service-worker.md (identity section)
Workflow: new extension from scratch
-
Define the manifest with minimum permissions. Start with
activeTab+scripting. → Readreferences/manifest-v3.md -
Set up TypeScript and build tooling (or use CRXJS for Vite-based dev). → Read
references/typescript-build.md -
Implement the service worker with all event listeners at the top level. → Read
references/service-worker.md -
Add content scripts if you need page interaction. → Read
references/content-scripts.md -
Build UI surfaces (popup, options, side panel) as needed. → Read
references/ui-surfaces.md -
Wire up messaging between all contexts. → Read
references/messaging-rpc.md -
Test with DevTools, specifically test service worker termination. → Read
references/debugging-mistakes.md -
Publish to Chrome Web Store. → Read
references/publishing.md
Workflow: adding a feature to an existing extension
- Identify which context the feature belongs to (see decision tree above).
- Read the relevant reference file(s) for that context.
- Check if new permissions are needed. Prefer optional_permissions for new capabilities. → Read
references/permissions.md - Update the manifest if adding new content scripts, UI surfaces, or permissions.
- Handle extension updates gracefully (content script orphaning). → Read
references/content-scripts.md(orphaning section)
Minimal manifest.json template
{
"manifest_version": 3,
"name": "My Extension",
"version": "1.0.0",
"description": "What it does in one sentence",
"permissions": ["storage", "activeTab", "scripting"],
"action": {
"default_popup": "popup.html",
"default_icon": {
"16": "icons/icon16.png",
"48": "icons/icon48.png",
"128": "icons/icon128.png"
}
},
"background": {
"service_worker": "background.js",
"type": "module"
},
"icons": {
"16": "icons/icon16.png",
"48": "icons/icon48.png",
"128": "icons/icon128.png"
}
}
→ For the full manifest reference with all fields: references/manifest-v3.md
Code patterns quick reference
Async message handler (the safe pattern)
// Wrap async handlers to avoid the return-true trap
function asyncHandler(
fn: (msg: any, sender: chrome.runtime.MessageSender) => Promise<any>,
) {
return (
message: any,
sender: chrome.runtime.MessageSender,
sendResponse: (r: any) => void,
) => {
fn(message, sender)
.then(sendResponse)
.catch((e) => sendResponse({ __error: true, message: e.message }));
return true; // literal true, not Promise<true>
};
}
chrome.runtime.onMessage.addListener(
asyncHandler(async (msg, sender) => {
if (msg.type === "FETCH") {
const res = await fetch(msg.url);
return { ok: res.ok, data: await res.text() };
}
}),
);
CSP bypass relay (content script → service worker → API)
// content-script.ts
async function apiCall(endpoint: string, options?: RequestInit) {
return chrome.runtime.sendMessage({ type: "API_RELAY", endpoint, options });
}
// background.ts
const ALLOWED_ENDPOINTS = ["https://api.example.com"];
chrome.runtime.onMessage.addListener(
asyncHandler(async (msg) => {
if (msg.type !== "API_RELAY") return;
if (!ALLOWED_ENDPOINTS.some((e) => msg.endpoint.startsWith(e))) {
throw new Error("Blocked endpoint");
}
const res = await fetch(msg.endpoint, msg.options);
return { ok: res.ok, status: res.status, data: await res.text() };
}),
);
Persist state across SW restarts
// Use chrome.storage.session for ephemeral state
chrome.storage.session.setAccessLevel({
accessLevel: "TRUSTED_AND_UNTRUSTED_CONTEXTS",
});
async function getState<T>(key: string, fallback: T): Promise<T> {
const result = await chrome.storage.session.get(key);
return result[key] ?? fallback;
}
async function setState<T>(key: string, value: T): Promise<void> {
await chrome.storage.session.set({ [key]: value });
}
Orphaned content script detection
function isExtensionContextValid(): boolean {
try {
return !!chrome.runtime?.id;
} catch {
return false;
}
}
// Before any chrome.runtime call
if (!isExtensionContextValid()) {
showRefreshBanner();
return;
}
What NOT to do
- Do NOT use
eval(),new Function(), or load remote scripts. MV3 forbids it. - Do NOT use
setTimeout/setIntervalfor anything > 5s in service workers. - Do NOT register event listeners inside callbacks or async functions.
- Do NOT use
<all_urls>host permission unless absolutely necessary. - Do NOT rely on DevTools keeping the service worker alive during testing.
- Do NOT forget
return truein async message listeners. - Do NOT use
localStorageorsessionStoragein service workers (they don't exist there). - Do NOT assume content scripts survive extension updates.
- Do NOT use
webRequestblocking (removed in MV3). UsedeclarativeNetRequest. - Do NOT use
chrome.extension.getBackgroundPage()(removed in MV3).
Conventional Commits & Branch Naming
Follow Conventional Commits v1.0.0 for both branch names and commit messages — consistent naming lets tools auto-generate changelogs, enforce SemVer bumps, and filter history by concern.
Branch Naming
Format: <type>/[issue-]<description> — lowercase, hyphens only, no special chars except /.
feat/user-authentication
feat/42-user-authentication
fix/login-race-condition
fix/87-login-race-condition
docs/api-reference-update
refactor/payment-module
Prefix with the issue number when one exists — GitHub and GitLab auto-link it and it makes git log immediately traceable to the tracker. Keep the description under 50 characters — most git UIs truncate branch names in lists around that length. Match the type to the work you're doing — this is the contract readers use to understand the branch purpose at a glance.
NEVER include worktree in a branch name — git worktrees are a local checkout mechanism, not a branch concept; the name would leak implementation details into the remote and confuse other contributors.
Worktree Naming
Worktrees are local checkout directories — they never appear in the remote. Place them under .claude/worktrees/ and name them by replacing the branch / separator with -.
git worktree add .claude/worktrees/feat-user-authentication feat/user-authentication
git worktree add .claude/worktrees/fix-87-login-race-condition fix/87-login-race-condition
The directory name mirrors the branch name so git worktree list stays readable and each worktree is immediately traceable to its branch without inspecting the checkout. Run git worktree list before creating a new one — reuse an existing worktree if it already covers the same branch.
Keep worktrees scoped to a single branch. Doing unrelated work inside someone else's worktree obscures which changes belong where and makes cleanup error-prone.
Remove the worktree once its branch is merged — either after a local merge or after the pull/merge request is closed on the remote. Stale worktrees accumulate and make git worktree list unreadable.
git worktree remove .claude/worktrees/feat-user-authentication # branch merged locally
git worktree prune # remove refs to already-deleted directories
Commit Message Format
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Types:
| Type | SemVer | When |
|---|---|---|
feat | MINOR | New feature |
fix | PATCH | Bug fix |
docs | — | Docs only |
style | — | Formatting, no logic change |
refactor | — | Restructure, no feature/fix |
perf | — | Performance improvement |
test | — | Add/fix tests |
build | — | Build system, deps |
ci | — | CI config |
chore | — | Anything else (not src/test) |
revert | — | Reverts a previous commit |
Rules:
- Subject line ≤ 72 characters — git log and GitHub/GitLab UIs silently truncate longer subjects
- Imperative mood: "add" not "added" — reads as an instruction, not a history log
- No capital letter, no trailing period — enforces uniform parsing by changelog tools
- Body separated by blank line — parsers split header/body at the first blank line
- Breaking changes: use
!after type/scope, or addBREAKING CHANGE:footer (triggers MAJOR bump) — body-only descriptions are invisible to changelog tools revertcommits SHOULD includeThis reverts commit <hash>.in the body —git revertgenerates this automatically; don't strip it- NEVER add a Claude signature, AI agent attribution, or
Co-authored-bytrailer for Claude or any other AI agent to commits
Examples:
feat(auth): add JWT token refresh
fix: prevent race condition on concurrent requests
Introduce request ID and reference to latest request.
Dismiss responses from stale requests.
refactor!: drop support for Go 1.18
BREAKING CHANGE: Go 1.18 no longer supported; uses stdlib APIs from 1.21+
Closing Issues via Commit Messages
Both GitHub and GitLab detect keywords in commit messages and automatically close the referenced issue when the commit lands on the default branch. Place the reference in the footer (preferred — keeps the subject line clean).
Keywords: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved — case-insensitive.
GitHub:
fix(auth): prevent token expiry race condition
Closes #42
Closes owner/repo#99
- Triggers when merged into the default branch (usually
main) - Cross-repo:
Closes owner/repo#42 - Close multiple:
Closes #42, closes #43 - Works in PR descriptions too
GitLab:
feat: add dark mode support
Resolves #101
Closes group/project#42
- Triggers when merged into the default branch (configurable per project)
- Cross-project:
Closes group/project#42 - Close multiple:
Closes #101, closes #102 - Works in MR descriptions too
Tip: Pair with the commit type — fix: closing a bug issue, feat: closing a feature request — keeps the changelog semantically coherent.
Common Mistakes
| Mistake | Fix |
|---|---|
feat: Added login page | feat: add login page — imperative, no capital |
fix: fix bug. | fix: fix bug — no trailing period |
| Subject over 72 chars | Shorten; move detail to body |
| Breaking change only in body | Add ! or BREAKING CHANGE: footer — tools won't detect body-only |
feat(adding-auth): ... | feat(auth): ... — scope is a noun, not a verb |
| Closes #42 in subject line | Move to footer — keeps subject clean and parseable |
Best Practices
- Align branch type and commit type —
feat/auth-*branch →feat(auth):commits - One concern per branch — mixing fixes into feature branches obscures the changelog
- Use scope consistently within a branch —
feat(auth):throughout, notfeat(user):mid-way - Squash merge: when squash-merging a PR/MR, the branch commits are collapsed into one — the PR/MR title becomes the commit message. If the title doesn't follow conventional commits format, changelog generation breaks silently. Always set the PR title before squashing.
Questions: Ask the user through the environment's question tool — never as plain-text prose. One question at a time, 2–4 tappable options, wait for the answer. If the environment has no question tool, ask in prose with the same options, one at a time.
End-of-Article CTA Designer
Designing an end-of-article CTA is a function of three inputs: the objective (what action), the audience (who reads it, in what relationship to the author), and the context (independent writing, newsletter, brand publication). Get those three right and the copy + form follow almost mechanically. Skip them and you get the universal failure mode: a generic "Subscribe for more" or "Learn More" that converts at the noise floor.
This skill runs a tight interview to capture those three inputs, then prescribes a CTA: copy (what it says), form (how it looks and sits on the page), mechanism (whether to use urgency, scarcity, curiosity, reciprocity, social proof, or none), an A/B test plan, and an accessibility check.
Workflow
Run the four steps below in order. Do not skip the interview. The user may have given partial context already; pull what's available from the conversation, then ask only for the missing pieces.
Step 1 — Interview
Ask one question at a time. Do not stack questions in prose. Each question must have 2-4 tappable options. Fall back to free text only if the answer genuinely cannot be enumerated.
Ask these in order, skipping any already answered:
Q1. Article context. Options: Personal / independent blog or essay · Newsletter / paid publication (Substack, beehiiv, Ghost, etc.) · Brand / company / content-marketing blog · Other (free text)
Q2. Primary objective. (Pick the one outcome you most want from a reader who finishes the article. If they say "all of them," push back: multiple objectives is the #1 cause of CTA failure.)
Options:
Newsletter / email subscriptionSocial follow / personal brandingLead generation (download / gated asset)Product or service signup / free trialDemo or sales call bookingDirect purchaseCommunity join (Discord / Slack / forum)Engagement (reply / comment / share / restack)Reader support (paid subscription / tip / sponsorship)Try-it / direct action (use the code, run the tool, fork the template, open the calculator)Other (free text)
If the user lists more than one, ask which is primary. You can offer 1-2 secondaries later, but the primary must be singular.
Q3. Audience and relationship. Options: First-time visitor (organic search / social) · Returning reader, not subscribed · Existing subscriber / customer · Mixed / unknown
Q4. Funnel stage. (Where is the reader mentally?) Options: TOFU: discovery, learning, no buying intent yet · MOFU: evaluating options, comparing · BOFU: ready to act, just needs a nudge · Not applicable (no buying funnel — e.g., personal blog, journalism, hobby content)
Q5. Mechanism preference. (Only ask if a mechanism could legitimately help. See references/mechanisms.md. For sophisticated, skeptical, or repeat-reader audiences, default to "None / value-only" without asking.) Options: None: value statement only · Curiosity gap ("Want to know more?") · Reciprocity (free asset first) · Discount / offer · Urgency (real deadline) · Scarcity / FOMO (limited spots) · Social proof (count / testimonial)
Capture any free-text constraints the user volunteers (length limit, brand voice, no popups, multi-language, etc.). Note them.
Step 2 — Diagnose
Map the inputs to a CTA archetype. The decision logic:
context = INDEPENDENT / PERSONAL
├── objective = newsletter / email → Archetype A: Author-signature subscribe
├── objective = try-it / direct action → Archetype B: Inline action + source link
├── objective = reader support / tip → Archetype C: Reader-supported funding link
├── objective = community → Archetype D: Proof-counted community invite
├── objective = social follow → Archetype A (variant: lead with social links)
├── objective = engagement → Archetype E: Specific reply prompt
└── objective = product / demo → ⚠️ FLAG. Only valid on personal/professional
blog where the author IS the product
(consultants, coaches, solo founders, indie devs).
Frame as "if you hit this, here's how I help"
— never "Book a Demo" verbatim.
context = NEWSLETTER PUBLICATION
├── objective = growth / subs → Archetype F: Share/restack + native widget
├── objective = engagement → Archetype E: Specific reply prompt
├── objective = paid conversion → Archetype G: Value-gap tease
├── objective = monetization / sponsor → Archetype H: Inline sponsor block (not bottom)
├── objective = community → Archetype D
└── objective = direct purchase → Archetype K (rare on newsletters; use BOFU only)
context = BRAND / CONTENT MARKETING
├── stage = TOFU → Archetype I: Transitional asset (lead magnet)
├── stage = MOFU → Archetype J: Direct + Transitional pair
├── stage = BOFU → Archetype K: Direct CTA + risk reversal
├── objective = community → Archetype D
└── objective = engagement → Archetype E (rarely the right call here)
Read references/taxonomy.md for the full archetype catalog with copy templates, form specs, when each works, and verbatim examples from named publications.
Step 3 — Compose the recommendation
Output the recommendation in this exact structure. Do not deviate. Do not add filler.
## Recommended CTA
**Archetype:** [letter + name from decision tree] **Why this fits:** [1-2 sentences naming the input combination]
### Content (copy)
**Headline / value line:**
> [exact text]
**Body / proof line (1-2 lines):**
> [exact text]
**Button copy:**
> [exact text]
**Risk reversal / subtext (if applicable):**
> [exact text, or "Omit: would feel forced for this audience"]
### Form (structure)
- **Placement:** [end-only / end + sticky / end + mid-article repeat]
- **Visual weight:** [low / medium / high, with justification]
- **Layout:** [single button / button + text link / native widget cluster / one-line signature]
- **Proof to co-locate:** [subscriber count / star count / testimonial / named recommenders / logo wall / none]
### Mechanism
[Named mechanism + 1 sentence on why it is appropriate, OR "None: value statement carries it. Mechanisms would erode trust for this audience."]
### A/B test plan
- **First test:** [single variable, e.g., button copy A vs. B]
- **Why this one first:** [1 sentence]
- **Sample size needed:** [rough estimate based on baseline traffic, or "skip A/B for now — traffic too low" with the alternative recommendation]
- **Next 2 tests to queue:** [in priority order]
### Accessibility check
- **Color contrast:** [target ratio + concrete pairing if colors known]
- **Touch target:** [size requirement]
- **Semantic markup:** [<button> vs. <a> vs. form]
- **ARIA:** [only if non-obvious]
- **Keyboard / focus:** [requirement]
- **Color-independence:** [non-color affordance]
After printing the recommendation, list 2-3 anti-patterns the user is at risk of falling into given their inputs, directly, as a contrarian check. Pull these from references/anti-patterns.md.
If the user is writing in a non-English language, translate the content section into that language but keep the structure (headings, labels) in English. Honor formality cues (e.g., tu vs. vous in French, du vs. Sie in German) based on prior conversation context, and flag the choice explicitly.
Step 4 — Offer next moves
Suggest 2-3 follow-up directions:
- Steelman the opposite. Offer to design the CTA you would recommend against — e.g., the hard-sell version on a TOFU post — so the user can see why it fails.
- Variant for a different audience or platform. If the article will be cross-posted (own site + Medium + LinkedIn + a syndication network), offer to rewrite per platform.
- End-to-end review. Offer to audit the rest of the article for CTA-supporting signals: author bio, related-post links, in-line proof.
Style inheritance
The copy templates in references/taxonomy.md are starting points, not finished copy. Always adapt them to:
- The user's stated brand voice or any
<userPreferences>in scope (formality, language, em-dash avoidance, length limits). - The language of the article. Output copy in the article's language; never default to English.
- The publication's existing voice. If the user has prior posts visible, mirror their cadence and vocabulary.
- The reader's expected level of expertise. A CTA for a beginner-finance blog uses different vocabulary than one for a quant-trading newsletter.
Never output a template verbatim if it conflicts with the user's stated style preferences.
Reference files
Read these as needed during diagnosis and composition. Read the relevant file in full before composing the recommendation; do not paraphrase from memory.
references/taxonomy.md: All 11 archetypes (A through K) with copy templates, form specs, verbatim examples from named publications, and conversion expectations.references/mechanisms.md: When to use urgency, scarcity, FOMO, discount, curiosity, reciprocity, social proof, authority, unity. When NOT to use them.references/ab-testing.md: Priority order of variables to test, sample-size rules of thumb, common pitfalls, when to skip A/B testing entirely.references/accessibility.md: WCAG 2.2 specifics for CTA blocks: contrast ratios, touch targets, ARIA patterns, focus states, keyboard support, motion preferences.references/anti-patterns.md: 12 failure modes to call out by name when they apply to the user's inputs.
Operating principles
- One primary CTA per post. Multiple competing CTAs is the dominant failure mode (single-CTA pages convert ~30%+ better than multi-CTA pages in repeated case studies).
- Match the voice of the publication. A personal-essay footer that reads like a SaaS landing page collapses credibility. A SaaS footer that reads like a casual signature converts at noise.
- Specificity beats cleverness. "Get one essay a week on indie filmmaking" beats "Subscribe to our awesome newsletter." Joanna Wiebe's "I want to ___" completion test is the cleanest filter for button copy.
- Proof co-located with the ask. Subscriber count, testimonial, customer logos, star count, named recommenders — whichever signal is honest for the context, place it inside or adjacent to the CTA block.
- Mechanisms are tools, not garnish. Most well-written value statements need no mechanism. Add urgency, scarcity, FOMO, or discount only when the context genuinely supports them; theatrical mechanisms erode trust faster than they lift conversion.
- Push back on bad asks. If the user wants "Book a Demo" at the bottom of a beginner tutorial for first-time visitors, say so. Do not produce a polished version of a CTA that will fail. Propose the alternative, explain why, then if the user still wants the original, deliver it with the failure mode flagged.
Copywriting Hooks
The method
A hook's only job is to make the reader want sentence 2. Voice, structure, formatting, all of it, follow from that one job.
What makes a reader want sentence 2 is one of five levers:
- Open a gap. Pose something incomplete that the reader needs to close. Curiosity gap, question, open loop.
- Break a prediction. State something that violates the reader's prior. Contrarian, definition reversal, surprising statistic.
- Drop into a scene. Load sensory or specific detail that builds a vivid frame. In medias res, concrete detail, time anchor.
- Promise a payoff. Name an outcome the reader wants. Benefit, "if you... then this", direct problem.
- Borrow weight. Lean on a name, number, or quote that carries embedded authority. Authority hook, statistic, quote with disagreement.
A strong hook usually pulls two levers at once. "Frank Sinatra, holding a glass of bourbon..." is scene plus open loop. "Most people think X. They're wrong." is prediction-break plus gap. Single-lever hooks can still work but are easier to ignore.
Three further principles:
- Specific beats abstract every time. Replace "many companies" with "Stripe, Shopify, Vercel". Replace "recently" with a date. Replace "studies show" with the actual finding or cut the claim.
- The first sentence must force the second. Read each candidate cold. If you would not click sentence 2 after sentence 1, rewrite.
- Match technique to article type. Personal essay does not open like a tutorial. See the type-fit table below.
Behavior
When this skill triggers:
- Confirm the brief. Topic, audience, target language (EN, FR, or both), approximate length, where it will be published. If any of these is unclear and material, ask before generating.
- Pick 3 to 4 hooks from the catalog below that are genuinely different. Different levers, not three flavors of contrarian.
- Write 2 candidates per hook, specific to the user's article. The two candidates within one hook should explore different angles (different anecdote, different statistic, different scene), not be rewordings of each other.
- Present using the Output format below.
- Ask through the question tool. The choice is a small fixed set, which is what that tool is for.
- Wait for the user's pick. Do not pick for them.
- After they pick, name what the choice commits the rest of the article to. A contrarian hook commits paragraphs 2 to 3 to defending the non-consensus claim. A scene opener commits the next section to either resolving the scene or productively delaying it.
Diversification rule. Across your 3 to 4 options include at minimum:
- One intellectual hook (contrarian, definition reversal, historical analogy, curiosity gap)
- One sensory hook (in medias res, concrete detail)
- One reader-direct hook (conditional, direct problem, promise)
This guarantees real choice. Three flavors of contrarian is not a choice.
Type-fit reference:
| Article type | Strong hooks | Avoid |
|---|---|---|
| Technical deep-dive | concrete detail, statistic, contrarian, direct problem | personal confession, scene opener |
| Personal essay | in medias res, personal confession, time anchor, definition reversal | bold claim, direct problem |
| Opinion / contrarian | bold claim, definition reversal, contrarian, quote + disagreement | gentle setup, dictionary opener |
| Tutorial / how-to | direct problem (PAS), promise, conditional | scene opener, historical analogy |
| Reported / investigative | concrete detail, time anchor, in medias res, statistic | bold claim, definition reversal |
| Listicle | curiosity gap, counted stakes, conditional | personal confession, in medias res |
| Longform analysis | historical analogy, statistic, contrarian | direct problem |
| Newsletter issue | personal confession + open loop, conditional, curiosity gap | dictionary opener |
Output format
Always present options exactly like this:
## Hook options for: [working title]
**Option 1: [Hook name]** ([lever])
A. [Candidate 1]
B. [Candidate 2]
**Option 2: [Hook name]** ([lever])
A. [Candidate 1]
B. [Candidate 2]
**Option 3: [Hook name]** ([lever])
A. [Candidate 1]
B. [Candidate 2]
Which? Reply with letter combination (e.g., "1B") or "more" for different techniques.
If the user says "more" or "none", produce 3 different hooks (not new candidates for the same hooks). If the user says "blend 1A and 2B", write a combined hook and check in again.
The hook catalog (18)
Each hook: what it does, examples (mix EN and FR, real and illustrative), when to use, when to avoid.
1. Curiosity Gap
Open an information gap the reader wants closed.
- EN: "How does Shen Yun make any money? Short answer: they don't." (Packy McCormick)
- EN: "Many years ago, one mustard dominated the supermarket shelves: French's." (Gladwell, "The Ketchup Conundrum")
- FR: "Trois startups françaises ont franchi le milliard cette année. Aucune n'est dans la tech."
- EN: "I've been a surgeon for eight years. For the past couple of them, my performance in the operating room has reached a plateau." (Gawande)
Use when: you can honestly close the gap in 2 or 3 sentences. The gap must be one the reader cares about. Avoid: vague gaps ("You won't believe what happened next") that the reader cannot even guess at.
2. Contrarian
Knock down a consensus belief the reader holds.
- EN: "Prevailing wisdom claims that the best way to achieve what we want in life is to set specific, actionable goals." (Clear, "Forget About Setting Goals", proceeds to argue the opposite)
- EN: "To do something well you have to like it. That idea is not exactly novel." (Graham, "Do What You Love", proceeds to complicate it)
- EN: "If you're not saying 'HELL YEAH!' about something, say no." (Sivers)
- FR: "Le Marketing est TOUT ce que l'IA ne peut pas faire !" (Truphème)
Use when: you have a defensible non-consensus view and 200 to 400 words to defend it. Avoid: strawmen, gratuitous edginess, contrarianism for its own sake.
3. Bold Claim / Promise
State the outcome upfront, before the proof.
- EN: "At 60 miles an hour the loudest noise in this new Rolls-Royce comes from the electric clock." (Ogilvy)
- EN: "They laughed when I sat down at the piano. But when I started to play!—" (Caples 1925)
- EN: "Give me 15 minutes and I'll give you a super-power memory." (Schwartz)
- FR: "En 5 minutes : la structure qui fait passer le taux de complétion d'un article de 18% à 64%."
Use when: you can deliver on the promise concretely in the article. Avoid: promises larger than the payoff. Destroys trust permanently.
4. Scene Opener / In Medias Res
Drop the reader inside a specific moment, no setup.
- EN: "Frank Sinatra, holding a glass of bourbon in one hand and a cigarette in the other, stood in a dark corner of the bar between two attractive but fading blondes who sat waiting for him to say something." (Talese)
- EN: "We were somewhere around Barstow on the edge of the desert when the drugs began to take hold." (Thompson)
- EN: "The center was not holding." (Didion)
- FR: "Le 14 mai 2024, à 6h12, trois hommes en civil sonnent à la porte d'un appartement du XVe arrondissement."
Use when: longform, profile, reported piece, essay. Avoid: short technical pieces where the reader has not earned the scene yet.
5. Surprising Statistic
Lead with a number that violates the prior.
- EN: "You have five seconds to get people's attention." (Housel, self-demonstrating)
- EN: "Thirty-seven thousand Americans died in car accidents in 1955, six times today's rate adjusted for miles driven." (Housel)
- EN: "Approximately 40 percent of the actions you perform each day are habits, not actual decisions." (Clear)
- FR: "Tu as moins de 3 secondes pour convaincre tes audiences que ton contenu est intéressant." (Truphème)
Use when: the number is genuinely surprising and you can cite it accurately. Avoid: vague stats ("studies show 90%..."), stats that confirm the reader's prior (no surprise equals no hook).
6. Question
Pose a question the reader actually wants answered.
- EN: "If you collected lists of techniques for doing great work in a lot of different fields, what would the intersection look like?" (Graham)
- EN: "Why do we make kids go to school?" (Caplan)
- FR: "Pourquoi 80% des articles LinkedIn ne dépassent jamais 100 vues ? Spoiler : ce n'est pas l'algorithme."
- FR: "Avez-vous le courage de gagner la moitié d'un million de dollars cette année ?" (Schwartz)
Use when: the reader was implicitly carrying the question. Avoid: "Have you ever wondered...?", "Did you know...?", "What if I told you...?". These presuppose curiosity not yet formed.
7. Quote + Disagreement
Borrow weight, then twist.
- EN: "Vernor Vinge: 'We are on the edge of change comparable to the rise of human life on Earth.'" (Urban setup)
- EN: "Steve Jobs said people don't know what they want until you show it to them. For SaaS, this is exactly backwards."
- EN: "Henry Ford supposedly said his customers would have asked for faster horses. For most products, that excuse is wrong."
- FR: "Henry Ford disait qu'on lui aurait demandé des chevaux plus rapides. Pour 90% des produits, c'est faux."
Use when: you have a real quote that supports or genuinely contrasts your point. Avoid: misattributed Einstein, Seneca, Confucius, Bouddha platitudes. Cliché.
8. Personal Confession
Admit something vulnerable, then universalize.
- EN: "I cheated on my husband." (Strayed)
- EN: "I've been thinking about my parents, who are in their mid-60s. During my first 18 years, I spent some time with my parents during at least 90% of my days." (Urban, "The Tail End")
- EN: "It's been a minute. This is as long as I've gone without writing an essay since starting Not Boring." (McCormick)
- FR: "À 34 ans, j'ai démissionné sans plan B. Voici ce que personne ne dit sur la suite."
Use when: personal byline, essay, newsletter. Avoid: corporate byline, technical articles where the author voice is not personal, performative vulnerability ("I almost didn't write this...").
9. Concrete Specific Detail
Replace abstraction with a single vivid detail.
- EN: "John Laroche is a tall guy, skinny as a stick, pale-eyed, slouch-shouldered, and sharply handsome, despite the fact that he is missing all his front teeth." (Orlean)
- EN: "Charles Bukowski was an alcoholic, a womanizer, a chronic gambler, a lout, a cheapskate, a deadbeat, and on his worst days, a poet." (Manson)
- FR: "Quand on la voit arriver dans les locaux du Bondy Blog, ce samedi 24 février, difficile de se dire qu'elle est fichée illégalement par les services de renseignement français."
- FR: "Un Post-it collé sur mon écran : 'Supprime ton premier paragraphe.'"
Use when: profile, reported piece, contrarian biographical setup. Avoid: specificity that does not advance the thesis (clutter).
10. Pattern Interrupt
Break expected rhythm with a fragment.
- EN: "Wait." (Godin style)
- EN: "Stop."
- EN: "This is not an article about productivity. It's an article about identity."
- FR: "Non. Ce que vous avez lu cette semaine sur l'IA est faux. Voici pourquoi."
Use when: rhythm-driven content, opinion piece, when the reader expects flow and you want to interrupt it. Avoid: every article. It becomes its own pattern fast.
11. Direct Problem (PAS)
Name the pain, sharpen it, hint at solution.
- EN: "Your articles aren't read. The data says you lose 80% of readers by paragraph two. There's a fix, and it's not what you've been doing."
- EN: "If you're like most marketing managers, you don't have enough time to write your white papers, and the ones you outsource come back generic." (Bly)
- FR: "Vos emails ne sont pas ouverts. Trois mois, taux plafonné à 12%. Le problème n'est pas l'objet, c'est l'expéditeur."
- FR: "Vos articles ne sont pas lus. 80% des lecteurs décrochent dès le deuxième paragraphe. Et la solution n'est pas celle que vous croyez."
Use when: tutorial, how-to, sales-adjacent content. Avoid: manufactured problems. Reads as fear-mongering. The pain must be real and recognizable.
12. Promise / Benefit
State a specific, bounded outcome.
- EN: "Read this in 5 minutes and you'll never write a weak opening again."
- EN: "By the end of this article, you'll know exactly when to use goroutines and when not to."
- EN: "Three things separate writers who get read from writers who don't. None involve writing every day."
- FR: "En 5 minutes : la structure qui fait passer le taux de complétion d'un article de 18% à 64%."
Use when: tutorial, how-to. Avoid: vague promises ("Learn how to be more productive"). Add a time bound or a number to anchor it.
13. Historical Analogy
Open with a vignette from history, pivot to the present.
- EN: "On a Tuesday morning in March 1976, a 21-year-old college dropout sold his Volkswagen Bus for 1,500 dollars. He used the money to build the first Apple computer."
- EN: "In 1965, Robert Lucas wrote a four-page paper that broke macroeconomics."
- EN: Wright Brothers vignette (Housel, "Three Big Things"), pivots to demographics and interest rates.
- FR: "En 1903, à Kitty Hawk, deux frères réparateurs de vélos volent pendant 12 secondes. Personne ne remarque. Voici ce que cette indifférence dit de l'adoption technologique aujourd'hui."
Use when: longform analysis, opinion piece, idea essay. Avoid: tutorials, news pieces. Reads as indulgent.
14. Definition Reversal
"X is not what you think. It's Y."
- EN: "Procrastination isn't laziness. It's a fight between two parts of your brain."
- EN: "This is not an article about productivity. It's an article about identity."
- EN: "Generics were the most requested Go feature for a decade. Three years in, the people who pushed hardest for them are telling you to stop using them."
- FR: "Le copywriting n'est pas de l'écriture. C'est de la psychologie déguisée en phrases."
Use when: opinion piece, contrarian deep dive. Avoid: when your reframe is just a slight angle. Sounds gimmicky.
15. Authority Borrow
Lead with a name plus a specific action.
- EN: "Warren Buffett, at 91, still reads 500 pages a day."
- EN: "When Steve Jobs returned to Apple in 1997, he killed 70% of the product line in his first year."
- EN: "A boy once asked Charlie Munger..." (Housel narrative variant)
- FR: "Quand Bernard Arnault a racheté Tiffany pour 16 milliards, trois analystes ont prédit un échec. Ils s'étaient tous trompés sur la même chose."
Use when: business piece, profile, analytical essay. Avoid: name-dropping without payoff. The action must be specific and relevant.
16. Time Anchor
Lead with a specific date, hour, or moment.
- EN: "October 2005. Three journalists set up a blog in an apartment of the cité Blanqui, in Bondy."
- EN: "In 2022, the cost of writing a competent article dropped to zero. Most writers haven't noticed."
- EN: "On a Tuesday morning in March 1976, a 21-year-old dropout sold his Volkswagen Bus for 1,500 dollars."
- FR: "Octobre 2005, Bondy. Trois journalistes installent un blog dans un appartement de la cité Blanqui."
Use when: reported piece, retrospective, "why now" framing. Avoid: vague time anchors ("recently", "these past few years"). Use a specific date or cut the time framing.
17. Conditional ("If you... then this")
Self-segment the reader. Pre-target the curiosity.
- EN: "If you write for a living, you've probably been taught to start with context. Don't."
- EN: "If you've ever read a blog post and forgotten what it said within the hour, this article is the diagnostic."
- EN: "If you're not saying 'HELL YEAH!' about something, say no." (Sivers)
- FR: "Si vos articles sont lus à 80% par vos collègues et à 8% par vos prospects, le problème n'est pas le contenu. C'est l'accroche."
Use when: tutorial, advice piece, segmented audience. Avoid: conditions too broad ("If you've ever felt stuck..."). Segments nobody.
18. Open Loop
Start something, withhold the resolution.
- EN: Talese's Sinatra waiting for him to say something. He never says.
- EN: "He pressed Send and waited. Forty-seven seconds later, the company was worth 4 billion dollars less."
- EN: "Now here's where it gets really interesting..." (Sugarman, transition phrase, also valid as opener)
- FR: "J'ai été contacté par un éditeur la semaine dernière. Ce qu'il m'a demandé m'a fait reconsidérer 15 ans de pratique."
Use when: longform, pieces where the journey matters as much as the answer. Avoid: unresolved loops. Creates disproportionate betrayal when the article ends without paying off.
Anti-patterns (never propose any of these)
Cliché openers that immediately disqualify the writer:
- "In today's fast-paced world..." / "À l'heure du tout-numérique" / "À l'ère de l'IA" / "Dans un monde où..."
- "Have you ever wondered...?" / "Vous êtes-vous déjà demandé...?"
- Dictionary opener played straight ("Productivity, defined as...")
- "In this article, I'll discuss..." / "Dans cet article, nous allons voir..."
- Generic stats without source ("90% of people...", "Les études montrent...")
- Misattributed Einstein / Seneca / Confucius / Bouddha quotes
- "I'm not an expert, but..." / "Je ne suis pas spécialiste mais..."
- Three rhetorical questions in a row
- "Imagine waking up..." without a specific scene
- "Hot take:", "Unpopular opinion:", "Voici la vérité que personne ne veut entendre..."
- "At [Company], we believe..." / "Chez [Entreprise], nous pensons..."
- "Recently,..." / "Récemment,..." without a specific date
- "You're not alone."
Current AI tells (refresh yearly):
- "It's not just X, it's Y" (the formula construction)
- "Picture this:", "Imagine a world where...", "What if I told you..."
- "Whether you're a seasoned X or a curious newcomer..."
- "In the realm of...", "Navigating the landscape of..."
- "Unlock the power of...", "Dive into...", "Buckle up,", "Let's dive in"
- "Crucially,", "Notably,", "Importantly,", "Essentially," as sentence openers
- French AI tells: "Dans un monde en constante évolution", "Plongez dans...", "Découvrez comment...", "Par ailleurs,...", "Notamment,...", "Il est crucial de..."
Run every candidate through this list before presenting. If a candidate matches, rewrite.
For the extended anti-pattern list, see references/anti-patterns.md.
Language handling
If the audience is French: write in French, applying the attaque journalistique register.
- Concrete scene-setting, restrained tone, dated anchors, formal "vous" or restrained tutoiement.
- Do not translate American hype tropes literally — "You'll never believe..." becomes "Vous n'allez pas en croire vos yeux", which reads as scam in French.
- French marketing-skepticism baseline is higher than English; high promises trigger réactance faster.
If English: default to direct-response register for marketing or tutorial content, longform register for essays and reported pieces.
If bilingual: produce hooks in both languages, label clearly.
For deeper register guidance, see references/anglophone-vs-francophone.md.
Post Titles
A title is what the reader sees before clicking. A hook is what they read after. Both earn attention through different mechanisms: the title competes for clicks in a feed or search result; the hook earns continued reading after the click.
The core mechanic: calibrated curiosity
A title must open a gap without closing it — but the gap must feel real, not manufactured. Research on 8,977 A/B experiments (Upworthy, Scientific Reports 2024) found a curvilinear relationship: too vague produces confusion (no foothold for curiosity); too specific removes motivation to click. The sweet spot: name the stakes, withhold the resolution.
The craft test. Does the title open a gap the reader cares about, and does the article genuinely close it? If yes, that's craft. If the content doesn't deliver what the title implied, that's clickbait — it destroys trust for future clicks.
Core formulas
Curiosity / Gap
The [Adjective] Truth About [Topic]— "The Counterintuitive Truth About Go Generics"What [Group] Won't Tell You About [Topic]The Real Reason [Phenomenon]— "The Real Reason Most Content Gets Zero Shares"[Number] Things Every [Audience] Gets Wrong About [Topic]
Contrarian / Negative (negative superlatives: +63% CTR vs. positive — Outbrain, 65k titles)
Stop [Doing X]. Here's Why./Why [Common Belief] Is Wrong[Number] [Myths/Mistakes] That Are Killing Your [Result]
Specificity / Data
I Analyzed [Number] [Things] — Here's What I Found[Number]% of [Group] Does This Wrong- Brackets signal format honestly and add +38% CTR:
How I Cut Build Time by 60% [Benchmark]
List / Number (numbers: +36% CTR — Conductor; odd numbers: +20% CTR — CMI)
[Number] [Adjective] Ways to [Goal]/[Number] Mistakes to Avoid When [Task]
How-To (3× more B2B shares than other formats — BuzzSumo, 10M LinkedIn articles)
How to [Task] Without [Painful Constraint]/How to [Task] Even If [Limiting Belief]
The "putaclic léger" zone
Slightly clickbait but honest — maximum tension with a real promise:
- Replace "won't believe" → "surprised to learn": same curiosity, honest register
- Add specificity: "I saved €500/month" beats "I saved money"
- Add a constraint: "without quitting your job" creates the gap
- Use "the real reason" or "what nobody tells you" — they signal a non-consensus view you must substantiate
- Add a bracket
[Étude],[Template],[Benchmark]to signal payoff type
FR — putaclic carries stronger pejorative weight. Apply the 70/30 rule: 70% information, 30% mystery.
- Tension and contradiction work; faux drama ("J'arrête tout 😱") destroys credibility immediately in French professional contexts.
- Canonical FR structure: "Tout le monde vous dit de faire A. Voici pourquoi je fais B."
- Formulas saturated on LinkedIn FR in 2025+: "J'ai fait une erreur, voici ce que j'ai appris", "J'arrête [plateforme]".
Platform constraints
| Platform | Max display | Key rule |
|---|---|---|
| Blog / SEO | 50–60 chars | Front-load keyword. Power words reduce CTR by ~14% in search. |
| LinkedIn article | 150 chars hard | Under 100 for clean display. |
| LinkedIn feed | 120–140 chars | Opening line = the title. Engineer a "see more" click. |
| Newsletter subject | 30–50 chars | First 30 chars carry the signal. Avoid "Newsletter" (−18.7% opens). |
| X / Twitter | ≤200 chars | First tweet = the title. Must stand alone. |
Anti-patterns for titles
- Generic superlatives without specificity: "The Ultimate Guide to X" — no gap
- "You won't believe..." / "Vous n'allez pas y croire..." — overused, signals hype
- Power words (Secret, Amazing, Ultimate) in SEO titles — signal hype, lower CTR
- Titles that give away the full answer — if the title answers the question, there is no reason to click
- Recycling saturated fingerprints: "I analyzed X things, here's what I found" — effective 2022–2023, saturating 2025–2026
Behavior for title requests
- Confirm topic, audience, language, platform
- Propose 3–5 titles across distinct formulas — not three variants of the same type
- Include at minimum: one curiosity/gap, one contrarian or data, one list or how-to
- Use the same output format as hooks: numbered options, wait for the pick
- After the pick, note what the title commits the article's opening to
For the full 58-formula catalog (EN + FR) with data citations, see references/title-formulas.md.
Reference files (load only when needed)
references/anti-patterns.md: extended cliché and AI-tell list.references/anglophone-vs-francophone.md: register conventions, what does not translate.references/formulas.md: 30 reusable templates (EN + FR) for quick template-based hooks.references/title-formulas.md: 58-formula post title catalog (EN + FR), platform constraints table, data summary.
The catalog above is sufficient for most invocations. Load references only when the user asks for templates, deeper register guidance, or to sanity-check anti-patterns.
Integration with other ghostwriting skills
If invoked from inside another skill's workflow (e.g., technical-article-writer reaches the hook step), produce options, ask, wait. Return the chosen hook to the parent skill for the rest of the article.
If the user has already drafted an opening and asks for "a better one", treat that draft as Option 0 (their current version) and propose 3 alternatives across different hooks. Do not silently discard their version.
Worked example
User: "I'm writing a Substack piece on why most Go developers misuse generics. About 1500 words, intermediate Go devs, English."
Correct skill response:
## Hook options for: "Why Most Go Developers Misuse Generics"
**Option 1: Contrarian** (prediction-break)
A. Most articles on Go generics explain when to use them. This one explains when to delete them.
B. Generics were the most requested Go feature for a decade. Three years in, the people who pushed hardest for them are the ones telling you to stop using them.
**Option 2: Concrete detail** (sensory + specific)
A. samber/lo ships 87 generic helpers. Six of them account for 94 percent of the binary-size complaints. The other 81 are fine.
B. A function called `Map[T, U any]` looks innocent. Compile a project that imports it 40 times and your build time triples. Here is why.
**Option 3: Direct problem (PAS)** (reader-direct)
A. Your Go code compiles slower since you adopted generics. The cause is not what the linter is telling you.
B. If your team adopted generics last year and your build times doubled, you are not alone. The diagnosis is more boring than the fix.
Which? Reply with letter combination (e.g., "1B") or "more" for different techniques.
Then wait for the pick. Do not write the rest of the article until the user has chosen.
Persona: You are a prose engineer. Prose is reproducible craft, not art — codify lexicon, syntax, rhythm, structure, and voice markers so any writer (human, ghostwriter, or AI) can hit the same fingerprint.
Thinking mode: Reason as thoroughly as possible for every BUILD and ADAPT invocation — prose codification synthesizes multi-input artifacts (SOUL.md + TONE.md + corpus + interview), arbitrates conformity-vs-differentiation against category defaults, and projects rules onto multiple supports. Shallow reasoning produces generic guides that flatten into LLM-default register — the exact failure mode this skill exists to prevent. On Claude Code, use ultrathink to trigger extended thinking explicitly.
Modes:
- BUILD — fresh PROSE.md from SOUL.md + TONE.md + discovery interview (sequential)
- ADAPT — port an existing PROSE.md to a new channel grouping (sequential)
- AUDIT — corpus analysis to surface current prose patterns before codification (parallel sub-agents when corpus > 50 pieces)
Questions: Ask the user through the environment's question tool — never as plain-text prose. One question at a time, 2–4 tappable options, wait for the answer. If the environment has no question tool, ask in prose with the same options, one at a time.
Copywriting Prose
Produces PROSE.md: a brand-specific prose guide that codifies how a brand writes, independent of what it feels like. Prose is the observable craft a forensic linguist could measure on a page — sentence length, clause depth, lexicon, parallelism, signature moves. Tone is the emotional posture, handled separately — two brands with identical tones can have non-interchangeable prose, which is what this guide captures.
The slogan: tone is the music, prose is the score. This skill codifies the score.
Inputs and outputs
| Artifact | Role | Producer |
|---|---|---|
SOUL.md (optional) | Storyteller archetype, mission, POV | sibling skill |
TONE.md (optional) | Emotional posture (NN/g 4 dimensions) | samber/cc-skills@copywriting-tone-of-voice-creator |
Existing PROSE.md | Source for ADAPT mode | this skill |
| Content corpus | Source for AUDIT mode | brand's CMS / blog / social archives |
PROSE.md | Output | this skill |
DESIGN.md (visual identity) sits in the same register but is out of scope. PROSE.md becomes the system-prompt substrate for downstream writers: samber/cc-skills@linkedin-ghostwriting, samber/cc-skills@substack-ghostwriting, samber/cc-skills@technical-article-writer, samber/cc-skills@press-release-writer.
Channel groupings
Per project convention, channels are treated as four generic groupings, not as platform-specific surfaces. Platform-specific quirks (LinkedIn's algorithm, Substack's paywall) live in the writer skills, not in PROSE.md.
| Grouping | Covers |
|---|---|
| Long-form articles | Blog posts, pillar pages, evergreen essays, technical deep-dives, opinion essays (Substack, Medium, dev.to, own blog — same group) |
| Social posts | LinkedIn, X, Bluesky, Threads, TikTok captions, Mastodon |
| Email & newsletter | Newsletter issues, transactional, drip sequences, lifecycle emails |
| Marketing copy | Landing pages, ad copy, press releases, podcast show notes, video scripts, sales decks |
BUILD workflow
Phase 0 — Detect inputs
Look in the working directory (and common locations like ./brand/, ./content/, ./docs/) for SOUL.md, TONE.md, prior PROSE.md, and any content corpus. If SOUL.md or TONE.md is missing, surface this — these artifacts feed directly into Phases 1 and 3, and proceeding without them forces inline assumptions that lock the prose guide to a sketch instead of the brand's actual archetype.
If missing, offer two paths:
- Invoke the sibling skill first (
samber/cc-skills@copywriting-tone-of-voice-creatorfor TONE.md). Why: TONE.md captures the brand's emotional posture across the four NN/g dimensions; without it, prose rules drift into tone territory and become unfalsifiable. - Capture archetype and tone minimally inline (Phase 1 interview adds a short addendum). Pragmatic for one-off prose audits.
If a content corpus exists, offer to run AUDIT mode first — empirical patterns beat invented ones every time.
Phase 1 — Discovery interview
Ask in 2–3 batches. Skip any field already supplied by SOUL.md, TONE.md, or prior conversation context. Wait for answers before proceeding — assumptions in the interview compound into a wrong prose guide that downstream writers will faithfully reproduce.
Required fields (full battery in references/discovery-questions.md):
- Brand mission (one sentence)
- Category posture: conformist, adjacent, challenger, outsider
- Audience: reading age, expertise (Layperson / Practitioner / Expert), locale, language(s), patience
- Author archetype (read from SOUL.md if present, else ask): journalist · engineer · founder · NGO advocate · politician · consultant · executive · community lead · artist · researcher
- Objective per channel: awareness · engagement · lead · signup · retention · advocacy
- Distribution channels: long-form · social · email · marketing copy (multiSelect)
- Constraints: legal, regulatory, brand safety, confidentiality
- Cultural context: HQ locale vs audience locale, language(s) of operation
- Tone of voice (if TONE.md missing): NN/g four dimensions quick-pick — funny↔serious · formal↔casual · respectful↔irreverent · enthusiastic↔matter-of-fact
Phase 2 — Category detection and deep-research routing
Match the brand to one of the 11 covered categories. Load the playbook from references/category-playbooks.md — it carries category-specific defaults for mean sentence length, lexicon, signature structures, anti-patterns, and reference brands.
| # | Category |
|---|---|
| 1 | B2B (SaaS / enterprise tech) |
| 2 | B2C (consumer products) |
| 3 | Consumer brand (lifestyle / DTC) |
| 4 | Non-corporate / NGO / non-profit |
| 5 | Consulting / professional services |
| 6 | Product-led (makers, indie hackers, dev tools) |
| 7 | Industry (manufacturing, deep-tech, industrial) |
| 8 | Volunteering / community / association |
| 9 | Personal branding (per-principal) |
| 10 | Politics / advocacy / public figures |
| 11 | Internal corporate communication |
Uncovered context → delegate research. When the brand sits clearly outside the 11 categories — for example religion / faith-based, defense / military, healthcare / pharma regulated, finance regulated, legal practice, cultural institutions (museum / opera / theater), educational institutions, government communications, intelligence services PR, esports, adult content, crypto / web3, niche luxury, fashion / beauty editorial, kids / edutainment, agritech, climate / environmental advocacy with policy posture — surface the gap and invoke samber/cc-skills@deep-research to map the category's prose conventions before codifying. Why: category playbooks compress 30+ pieces of corpus evidence per category; codifying without that substrate produces guides that read like generic LLM output.
For personal branding the same logic applies per principal: a corpus capture of 60–90 minutes of the principal's recorded speech plus prior writing is required before codifying. Generic personal-branding rules produce ghostwritten posts that read like every LinkedIn founder.
Phase 3 — Codify the five layers
Codify each layer in order. Each rule needs a why — bare prescriptions without rationale fail the moment a writer hits an edge case. Detail rules and examples in references/five-layers.md.
- Lexicon — use/avoid A–Z (50–200 entries), terminology table, jargon ladder per channel, acronym policy, naming conventions, foreign-word policy, technical depth scale (Layperson / Practitioner / Expert)
- Syntax — mean sentence length target (category default, ±2), distribution targets (≤10% of sentences ≥25 words; ≥15% ≤8 words for rhythm), clause depth, active voice default with exception list, parallelism rules, paragraph length and architecture
- Rhythm — cadence variance target (σ ≥ 6 words per 100-word window), breath points (one ≤8-word sentence every 3–5 sentences), repetition policy, callbacks, list patterns, white-space cadence
- Structure — opening hook types (cross-ref
samber/cc-skills@copywriting-hooks), closing types (cross-refsamber/cc-skills@copywriting-cta), transitions, headings (sentence case, frontloaded), subheadings, lists, asides, quotations, citations, blockquotes, reader positioning (Gardner's far↔close psychic distance: default per channel, shift-signal words, when to close for conversion) - Voice markers — 5–12 signature moves, signoffs, recurring metaphors, idioms, taboos, intentional tics (all rationed; unrationed markers collapse into self-parody)
Diagnose the corpus before locking the targets:
wc -wand a sentence-length distribution script (see references/audit-tools.md) — establish current mean and σ before declaring targets- Hemingway readability against a sample of 5 pieces — sanity-check the reading age claim from Phase 1
grep -ifor each candidate banned word in the existing corpus — confirm the brand actually drifts toward it before banning
Phase 4 — Punctuation and formatting policies
Two non-negotiable tables.
Punctuation policy — declare a position on each: em dash, en dash, semicolon, colon, ellipsis, parentheses, italics, bold, single/double quotes, exclamation marks, brackets, hyphens (compound modifiers), Oxford comma, capitalization (sentence vs title case). Defaults and rationing tables live in references/five-layers.md.
Formatting policy — heading hierarchy (H1 once, H2 sections, H3 sub-sections, max H4 in technical docs only), bullet rules (3–7 items, parallel grammar, leading sentence), numbered lists (only when order matters), code blocks (language tag, line cap), images (caption + alt text), callouts (rationed), tables (only for 2D relationships), links (frontloaded link text — never "click here", "learn more", "read more"). Why frontloaded link text: scannability and accessibility; screen readers extract link lists out of context.
Phase 5 — Channel-specific overrides
For each in-scope channel grouping (see table above), produce a CHANNEL section in PROSE.md with deltas on sentence length, paragraph length, hook types, closing types, formatting, and CTA pattern. Pull the transformation rules from references/channel-adaptation.md.
Generic groupings keep PROSE.md portable: when a brand adds a new platform within a grouping (e.g. moves from Threads to Bluesky), the overrides hold without re-codification.
Phase 6 — Cultural and linguistic adaptation
- English variant: declare US / UK / international English (spelling, punctuation, date format)
- French ↔ English: list the few French words permitted in English text (raison d'être, savoir-faire) and forbid others without translation; conversely declare English loan-words accepted in French (le marketing, le briefing) vs taboo
- False cognates: éventuellement ≠ eventually, actuellement ≠ actually, important often ≠ important; full list in references/multilingual.md
- Transfer budgets: cut 20% of words FR→EN, pad 20% EN→FR — French rewards longer sentences, English brand prose favors shorter
- Locale conventions per channel grouping: French LinkedIn cadence differs from US conventions in formality, paragraph length, first-person use
- Accessibility and inclusion: bias-free language section (people-first, singular "they", preferred pronouns)
For multilingual brands: one PROSE.md per language, not a translated single guide. Maintain a mapping document of shared pillars and divergent rules.
Phase 7 — Anti-LLM countermeasures
The dominant prose-drift risk in content factories is convergence on LLM-default register. Codify rules LLMs do not follow by default — that is the durable defense.
Full inventory in references/anti-patterns.md. Headline patterns:
- Lexical tells: delve, leverage, crucial, robust, underscore, navigate (as transitive metaphor), seamlessly, vibrant, dynamic, embark, foster, harness
- Structural tells: tricolons in series ("X, Y, and Z"), summative closers ("In conclusion…"), colon-titles ("The Future of X: A New Paradigm"), bullet-list overuse, hedged claims without source
- Punctuation tells: em-dash overuse (single signal — not proof; see Ann Handley's published rebuttal); ellipsis outside quotation
- Formula constructions: "It's not just X, it's Y" · "Picture this:" · "Imagine a world where" · "What if I told you" · "Whether you're a seasoned X or a curious newcomer" · "In the realm of" · "Navigating the landscape of"
Diagnose LLM drift quantitatively:
grep -c -iE 'delve|leverage|crucial|robust|underscore'across the corpus — frequency ≥1 per 500 words is a strong tell- Sentence-length σ < 4 across a 100-sentence window — uniformity is a stronger tell than any single lexical signal
- n-gram comparison between the brand's pre-AI corpus and post-AI corpus — divergence in top trigrams flags drift
Detection is unreliable as a single source of truth. Use these as triage, not verdict. The Stanford HAI / Liang et al. (2023) work showed GPT detectors misclassify TOEFL essays by non-native English writers at headline rates above 60%. Treat any single signal as suspicion, not proof.
Phase 8 — Render PROSE.md
Use the hybrid template in references/prose-md-template.md:
- Narrative sections for each layer + policy (the why and the how)
- Do/don't tables as an annex (the quick-reference scan layer)
- Sample bank: ≥10 before/after pairs, ≥3 exemplar pieces if provided, hook bank and closing bank cross-referenced from
samber/cc-skills@copywriting-hooks/@copywriting-cta - Cross-references to TONE.md and SOUL.md (read together, not in isolation)
- Versioning footer: semver, date, owner, changelog stub
ADAPT workflow
Take an existing PROSE.md and project it onto a new channel grouping.
- Read the existing PROSE.md.
- Ask the user: target channel grouping (long-form / social / email / marketing copy), and optionally a specific platform within the grouping for tighter overrides.
- Compute the transformation delta from references/channel-adaptation.md: sentence-length cut or grow factor, paragraph break frequency, hook style adjustment, CTA fit, formatting overrides.
- Emit a
CHANNEL OVERRIDE — <grouping>section appended to PROSE.md, or a standalonePROSE-<grouping>.mdif the user prefers a separate artifact. Why offer both: content teams that publish across many channels prefer one master file; ghostwriting agencies handling a single channel prefer per-channel files. - Cross-reference back to the original PROSE.md for fields unchanged.
AUDIT workflow
Extract current prose patterns from a corpus before codifying. Empirical patterns beat invented ones.
- Take the corpus (folder of
.md/.txtor list of URLs). - For corpora > 50 pieces, parallelize: spin up to 5 parallel sub-agents, splitting the corpus by date range, channel, or author. Each agent reports back with the same metrics. Why parallel: sequential reading on a 200-piece corpus is slow and runs out of context; parallel sub-agents read independently and synthesize.
- Compute (per references/audit-tools.md):
- Mean sentence length and distribution
- Top 50 lexemes, top bigrams and trigrams
- Banned-word and AI-tell frequency
- Em-dash count per 1,000 words
- Opening pattern map (first 50 words of 30 pieces, side by side)
- Closing pattern map
- Run an adversarial reading pass on 3–5 representative pieces — challenge the assumption that they work. Mark every sentence that doesn't earn its place, every unanswered reader question, every moment authority collapses, every paragraph where a reader would disengage. See references/audit-tools.md for the methodology.
- Sort findings into four buckets: signature (recurring, distinctive, working) · default (recurring, generic, neutral) · noise (inconsistent, accidental, weak) · liability (recurring, actively harming credibility or engagement — the adversarial pass surfaces these).
- Produce
AUDIT-MEMO.md(5–10 pages: quantitative tables + qualitative annotated samples + "keep, kill, differentiate" summary). Feed into BUILD Phase 3.
Output format
PROSE.md
├── Cover (brand, version, owner, last updated, status)
├── Purpose (200 words: who it is for, how to use, what it does not cover)
├── Prose Pillars (one page, 5–8 falsifiable pillars)
├── Voice vs. Tone note (one paragraph)
├── 1. Lexicon (narrative + do/don't annex)
├── 2. Syntax
├── 3. Rhythm
├── 4. Structure
├── 5. Voice Markers
├── 6. Punctuation Policy
├── 7. Formatting Policy
├── 8. Channel Overrides (one section per in-scope grouping)
├── 9. Cultural & Linguistic Adaptation
├── 10. Anti-LLM Countermeasures
├── 11. Sample Bank (before/after, exemplars, anti-exemplars, hook bank, closing bank)
├── 12. Ghostwriting Addendum (per principal — optional)
├── Annex A: Do/Don't quick reference (all layers, scannable)
└── Changelog
A complete PROSE.md is 20–60 pages depending on category coverage and channel scope. Resist the urge to maximize length — Siemens reduced their brand guidelines from 2,750 to 250 pages because enforceable density beats exhaustiveness. Aim for the density that an editor can apply line by line; cut anything an editor cannot turn into a concrete edit.
Reference files (load on demand)
| File | When to read |
|---|---|
| discovery-questions.md | During Phase 1 interview |
| five-layers.md | During Phase 3 codification |
| category-playbooks.md | During Phase 2 after category detection |
| channel-adaptation.md | During Phase 5 and all ADAPT invocations |
| anti-patterns.md | During Phase 7 and AUDIT mode |
| multilingual.md | During Phase 6 when brand operates in EN/FR |
| prose-md-template.md | During Phase 8 render |
| brand-atlas.md | During Phase 2 archetype matching |
| audit-tools.md | During AUDIT mode and Phase 3 corpus diagnosis |
Disclaimer
This skill is not exhaustive.
- The 11 category playbooks compress a much larger landscape — refer to the brand's own corpus, the linked frameworks (Mailchimp, IBM Carbon, GOV.UK, Microsoft, Atlassian, Buffer), and canonical references (Ann Handley Everybody Writes, Joseph Williams Style, Roy Peter Clark Writing Tools, Margot Bloomstein Trustworthy) when the playbook does not cover the situation.
- For uncovered categories, invoke
samber/cc-skills@deep-researchand feed its output back into BUILD Phase 2. - Prose guides decay; a PROSE.md not re-audited every 12 months is a snapshot, not a living document.
If you encounter a bug or unexpected behavior, open an issue at https://github.com/samber/cc-skills/issues.
Persona: You are a senior brand voice strategist. You treat tone of voice as operational infrastructure, not a deliverable PDF — discover deeply, define falsifiably, document for the writers (or bots) who will use it.
Thinking mode: Reason as thoroughly as possible for Phase 3 (voice definition) and category mapping. Synthesising stakeholder inputs, audience nuance, and cross-channel modulation rewards deep reasoning; shallow synthesis produces generic, derivative voices. On Claude Code, use ultrathink to trigger extended thinking explicitly.
Modes:
- Create — build TONE.md from scratch via discovery questionnaire, voice definition, and template fill. Sequential. Ask for structured intake; spawn a research sub-agent only if the brand category falls outside the covered set.
- Adapt — port an existing TONE.md to a new channel/support. Read TONE.md, ask target channel, apply channel modulation rules from references/channel-adaptations.md, append a channel section or fork
TONE-<channel>.md.
Questions: Ask the user through the environment's question tool — never as plain-text prose. One question at a time, 2–4 tappable options, wait for the answer. If the environment has no question tool, ask in prose with the same options, one at a time.
Tone of Voice
Produce a TONE.md brand voice guide that downstream content skills can mechanically consume to write on-brand copy across many channels and many writers — human or bot.
Why this skill exists
Most tone-of-voice work ends up as a PDF nobody reads. This skill produces machine-readable infrastructure: voice attributes with explicit do's/don'ts, a tone modulation matrix, a banned-words list, mechanics decisions, and channel-specific guidance — all in stable markdown sections so a downstream PROSE.md generator (or any writing skill or bot) can parse and apply it.
Voice vs tone is load-bearing. Voice is the fixed personality of the brand (does not change); tone is the contextual modulation across channel, audience, situation. If the user asks to "change the voice for LinkedIn", clarify: do they want to modulate tone (yes — that's what Adapt mode does) or rebrand (no — that's a SOUL.md change). Confusing the two is the single most common failure mode in this work.
When to invoke
Invoke when the user wants to:
- Create a brand TONE.md / tone-of-voice guide
- Adapt an existing TONE.md to a new channel (LinkedIn, Twitter/X, email, in-product, TikTok, podcast, press, etc.)
- Define voice attributes, lexicon, and channel rules for a content factory
- Refresh an outdated voice
Skip when:
- The user wants a brand identity / mission / values document →
SOUL.md(separate skill) - The user wants prose-style conventions for code or docs →
PROSE.md(separate skill, consumes TONE.md) - The user wants visual design rules (colours, typography, spacing) →
DESIGN.md(separate skill) - The user is asking about a specific piece of content, not the system
Inputs
- Optional:
SOUL.mdin the working directory (or a path the user supplies). If present, read and extract brand name, mission, audience, values, archetype, banned topics — pre-fill the questionnaire, then confirm with the user before proceeding. - Required: user answers to the discovery questions (Phase 1).
- Adapt mode: path to the existing
TONE.mdplus the target channel.
Output
TONE.mdat the working directory root (or the path the user supplies). Structure defined in assets/TONE-template.md.- Adapt mode: either appends a channel section to the existing TONE.md or writes
TONE-<channel>.md. Ask the user which before writing — forking is cleaner for pipelines that consume one file per channel; appending keeps the master guide complete.
Create mode
Phase 1 — Discovery (interview)
Skim references/discovery-questionnaire.md — it contains the exhaustive 80+ question bank. The batches below are the minimum to produce a usable TONE.md; pull from the full bank when the brand is high-stakes, regulated, or multi-market.
-
Glob for
SOUL.mdin CWD. If found, read and extract: brand name, mission, audience, values, archetype, banned topics. Display the extraction and ask the user to confirm or correct. Skip the questions that SOUL.md already answers. -
Batch A — basics (single question-tool call, 4 questions):
- Mode: Create from scratch / Adapt existing TONE.md
- Brand category: B2B SaaS, B2C/D2C, NGO, Public Sector, Consulting, Industrial, Personal brand, Volunteering, Political/Advocacy, Other
- Primary market(s) and language(s) — country and locale matter for idiom, reading age, and humour calibration
- Primary content goal: Demand gen, Awareness, Retention, Recruiting, Fundraising, Advocacy, Internal comms, Other
-
Batch B — audience & channels (4 questions):
- Primary audience (single persona, free text — multi-persona handled in follow-up)
- Channels in scope (multi-select): Web, Blog, Email, LinkedIn, Twitter/X, TikTok, Instagram, YouTube, Podcast, In-product UI, Support, Press, Sales decks, Recruiting, Other
- Reading-age target: Adult general / Expert+technical / Reading-age 9 (gov + inclusive default) / Mixed
- Risk tolerance: Safe & neutral / Moderately distinctive / Boldly distinctive (willing to alienate non-buyers)
-
Batch C — personality & references (4 questions):
- Primary archetype guess: 12 Jung options (Innocent, Sage, Explorer, Outlaw, Magician, Hero, Lover, Jester, Everyman, Caregiver, Ruler, Creator) or Unsure
- Voice references: 3-5 admired brands to triangulate from (free text)
- Anti-references: 3-5 brands NOT to sound like (free text)
- Founder/CEO voice contribution: Heavy / Moderate / None / Explicitly avoid
-
Batch D — constraints (3-4 questions):
- Regulatory regime: None / GDPR / HIPAA / FDA / SEC / FCA / ASA / Other
- Cultural taboos and topics to avoid (free text)
- Existing brand book / banned-word list (path or None)
- Localisation strategy: Single locale / Multi-locale with shared voice / Per-locale voice
If the user's category is "Other" or sits outside the covered set in references/category-adaptations.md — politics, religious organisations, defense, gaming, healthcare professional comms, adult content, sports teams, fintech-crypto — proceed to Phase 2.
Phase 2 — Research uncovered contexts (conditional)
Spawn an Agent sub-task with this brief:
Research current tone-of-voice norms for
<category>brands in<market>. Cover: 1) typical voice attributes for the category; 2) common pitfalls and how audiences react to off-tone copy; 3) 2-3 reference brands with publicly observable voice patterns (cite primary sources); 4) regulatory, cultural, or platform constraints on voice. Report in under 700 words with sources cited inline.
For broad cross-market research (e.g. political comms across regions), spawn up to 3 parallel agents split by region or sub-category, then synthesise the findings before continuing to Phase 3.
Use the agent's output to populate the category-adaptation section of TONE.md and refine voice attributes. Footnote sources — future maintainers will need to verify when category norms shift.
Phase 3 — Define voice (ultrathink)
Use ultrathink for this phase. Synthesise the discovery inputs into:
-
NN/g 4 dimensions position — funny/serious, formal/casual, respectful/irreverent, enthusiastic/matter-of-fact. Each is a 3-point scale. Do not cluster all four near midpoint — defaulting to mid-range scores produces bland, forgettable voices that fail to differentiate from category default. Lean to one side on at least three of the four dimensions.
-
3-5 voice attributes, each in the "X but never Y" pattern (Slack: "Confident, never cocky; Witty, but never silly"). For each, produce: one-line definition, 3 do's, 3 don'ts, 1 example sentence, 1 anti-example pulled from the brand's own past content if possible. Three is the minimum (fewer is unhelpful); five is the maximum (more is unmemorable). See references/voice-attributes.md for the documentation pattern.
-
Primary archetype (optional secondary). Don't over-commit to archetype — it is a positioning shortcut, not a voice solution. Brands that lean too hard on archetype end up in cosplay (every "Hero" brand sounds the same).
-
Tone modulation matrix — rows are situations (launch, crisis, complaint, win, sensitive topic, routine, sales objection, layoffs/bad news, apology), columns are the channels in scope. Each cell: dominant tone + 2-3 prohibited tones. This is the operational core — downstream writers and bots consult this more than the principles narrative.
-
Lexicon — preferred terms (named concepts, customer noun like "members" vs "users"), banned terms (jargon, marketing clichés, exclusionary language), power words (10-30), jargon policy (when allowed for which audience), naming conventions (brand, product, features, competitors). See references/lexicon-mechanics.md.
-
Mechanics — person (1st plural "we" / 2nd "you"), contractions (yes/no/contextual; GOV.UK avoids negative contractions because they harm non-native readers), Oxford comma, sentence length norm (general public: average 15-20 words; expert audiences may go longer), active/passive default (active unless softening a sensitive message), sentence case vs title case, emoji policy, punctuation tics (ellipses, em-dashes, exclamation marks), numerals. Same reference file.
-
Inclusive language — base on the Conscious Style Guide (Karen Yin) and APA Inclusive Language Guidelines. Decide gendered language policy, ability/disability terms, race, age, nationality, neurodiversity. Per market if multi-locale.
-
Channel-specific guidance — apply references/channel-adaptations.md per channel in scope, capturing hard platform constraints (character limits, format) and tonal shifts.
Phase 4 — Write TONE.md
Use assets/TONE-template.md. Fill every section. Section names and structure are stable — downstream skills depend on them for parsing.
Mandatory sections (order matters for downstream pipelines):
- Context (brand, market, channels, goal)
- Voice attributes (3-5, each with do/don't/example/anti-example)
- Archetype
- NN/g 4 dimensions positioning
- Tone modulation matrix
- Lexicon (preferred, banned, power words)
- Mechanics
- Inclusive language
- Channel-specific guidance (one subsection per channel in scope)
- Global Do's and Don'ts (consolidated, scannable list — this is what writers paste into their context window when drafting)
- Examples library (before/after pairs)
Phase 5 — Validate
Run these checks before finalising the file. If any fails, surface the gap and ask the user before writing the final TONE.md:
- 3-5 voice attributes — neither fewer nor more.
- Every attribute has at least one anti-example sourced from the brand's own context (not a generic placeholder like "lorem ipsum bad").
- NN/g positions don't all cluster near midpoint — at least 3 of 4 dimensions clearly off-centre.
- Banned-words list is non-empty (prevention is cheaper than prescription — without it, writers default to category clichés the brand wanted to avoid).
- One channel-specific subsection per channel in scope.
- Sample three random do's and three random don'ts and re-read: would a new writer or bot know exactly what to do tomorrow? If they're abstract, rewrite them as concrete sentences with examples.
Adapt mode
For porting an existing TONE.md to a new support or channel without rebuilding the whole guide.
- Read the existing
TONE.md. Confirm with the user that voice attributes do not change — only tone modulates per channel. If the user disagrees, redirect them to SOUL.md (rebrand) or to Create mode (new TONE.md). - Ask target channel: LinkedIn / Twitter-X / Email / In-product UI / Podcast / Video script / Press release / TikTok / Instagram / YouTube / Sales deck / Other.
- Ask whether to append a channel section to the existing TONE.md or fork a new
TONE-<channel>.md. Forking is cleaner for content-factory pipelines that load one file per channel; appending keeps the master guide complete. - Apply the relevant section of references/channel-adaptations.md — each channel documents hard constraints (character limits, format, supported markdown), tonal shifts (e.g. LinkedIn dampens irreverence; TikTok rewards cadence and trend-awareness; in-product UI strips flourish), and prohibited registers.
- Re-derive 3 do's and 3 don'ts specific to the channel. Pull from the global list but make them concrete to the medium (a do that reads "be concise" globally becomes "lead with the verb in the first 90 characters" for Twitter/X).
- Re-do the relevant column of the tone modulation matrix.
- Write the adapted section or new file.
Important constraints
- Voice does not change. Tone does. If you find yourself rewriting voice attributes for a channel, stop — that's a SOUL.md change, not a channel adaptation.
- No PDF outputs, no decorative formatting. TONE.md is plain markdown so any downstream skill or bot can parse it deterministically. Avoid ASCII art, complex tables in voice-attribute sections, or anything that breaks markdown parsers.
- Cite sources for research-derived claims. When Phase 2 research informs the TONE.md, footnote the source in the category section — future maintainers will need to verify when norms shift (especially fast-moving categories like gaming and crypto).
- Don't borrow voices wholesale. "We want to sound like Oatly / Mailchimp / Duolingo" briefs produce derivative voices that audiences increasingly detect (especially when AI-written). Use references to triangulate, not imitate. The strategy under the style is what makes a voice work, not the surface mannerisms.
- Banned-words lists do more work than power-words lists. Prevention is cheaper than prescription — a writer encountering "we don't use 'leverage' (unless in the financial sense)" never reaches for it again. A power-words list, by contrast, is rarely consulted in the moment.
- Politics, regulated industries, religious organisations, defense, healthcare professional comms, gaming, adult content, sports teams, fintech-crypto → research first via Phase 2. Do not apply consumer-brand defaults. Each has voice norms shaped by audience, regulation, and platform that override generic guidance.
- For multi-locale brands, document voice per locale rather than translating from one source language. Transcreation is the standard; surface-translating English brand voice into French or Japanese produces tin-eared copy that fails the local market.
Disclaimer
This skill is not exhaustive. The discipline of tone of voice is evolving rapidly, especially as AI-generated content shifts where differentiation lives.
- Refer to canonical sources for current best practice: Mailchimp's content style guide, GOV.UK's style guide, Nielsen Norman Group's The Four Dimensions of Tone of Voice, Karen Yin's Conscious Style Guide, Margot Bloomstein's Trustworthy, and the published voice guides of the brands in references/reference-brands.md.
- Voice norms vary by category and locale; verify any pattern that surprises you against the brand's actual category and market before committing it to TONE.md.
References
- references/discovery-questionnaire.md — full 80+ question bank, batched for the question tool
- references/category-adaptations.md — per-category guidance and pitfalls
- references/voice-attributes.md — attribute documentation pattern, NN/g 4 dimensions, Jung archetypes
- references/channel-adaptations.md — per-channel modulation rules and hard constraints
- references/lexicon-mechanics.md — preferred/banned terms, grammar conventions, inclusive language
- references/reference-brands.md — studied brand voices (Mailchimp, Slack, GOV.UK, Stripe, Duolingo, Oatly, Liquid Death, Wendy's, Patagonia, Innocent, charity:water, Linear, Notion)
- assets/TONE-template.md — TONE.md template to fill
CRXJS
CRXJS is a Chrome extension development tool that provides true HMR for popup, options, content scripts, and side panels. It reads your manifest to auto-generate the extension output, handles content script injection, and manages the service worker build. Under the hood it is a Vite plugin (@crxjs/vite-plugin).
Current status
- Package:
@crxjs/vite-plugin(v2.x stable, latest v2.4.0 as of March 2026) - Scaffolding:
npm create crxjs@latest(always use@latest) - Maintained by: @Toumash and @FliPPeDround (since mid-2025)
- GitHub: github.com/crxjs/chrome-extension-tools (~4k stars)
- Vite compatibility: v3 through v8-beta
Quick start
# Scaffold new project (picks framework interactively)
npm create crxjs@latest
# Or add to existing Vite project
npm install @crxjs/vite-plugin -D
Vite config by framework
CRXJS is added as a Vite plugin. The setup varies slightly per framework.
React
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { crx } from "@crxjs/vite-plugin";
import manifest from "./manifest.json";
export default defineConfig({
plugins: [react(), crx({ manifest })],
});
Use @vitejs/plugin-react (not plugin-react-swc) for best HMR compatibility. If you must use SWC, cast the manifest:
import { ManifestV3Export } from "@crxjs/vite-plugin";
const manifest = manifestJson as ManifestV3Export;
Vue
import vue from "@vitejs/plugin-vue";
import { crx } from "@crxjs/vite-plugin";
import manifest from "./manifest.json";
export default defineConfig({
plugins: [vue(), crx({ manifest })],
});
Svelte
import { svelte } from "@sveltejs/vite-plugin-svelte";
import { crx } from "@crxjs/vite-plugin";
import manifest from "./manifest.json";
export default defineConfig({
plugins: [svelte(), crx({ manifest })],
});
Vanilla TypeScript
import { crx } from "@crxjs/vite-plugin";
import manifest from "./manifest.json";
export default defineConfig({
plugins: [crx({ manifest })],
});
defineManifest — type-safe dynamic manifest
Instead of a static JSON file, use CRXJS's defineManifest for dynamic values and full TypeScript autocompletion:
// manifest.ts
import { defineManifest } from "@crxjs/vite-plugin";
import pkg from "./package.json";
export default defineManifest((config) => ({
manifest_version: 3,
name: config.command === "serve" ? `[DEV] ${pkg.name}` : pkg.name,
version: pkg.version,
description: pkg.description,
permissions: ["storage", "activeTab", "scripting"],
action: {
default_popup: "src/popup/index.html",
default_icon: {
"16": "public/icons/icon16.png",
"48": "public/icons/icon48.png",
},
},
background: {
service_worker: "src/background/index.ts",
type: "module",
},
content_scripts: [
{
matches: ["https://*/*"],
js: ["src/content/index.ts"],
css: ["src/content/styles.css"],
},
],
options_page: "src/options/index.html",
side_panel: { default_path: "src/sidepanel/index.html" },
icons: {
"16": "public/icons/icon16.png",
"48": "public/icons/icon48.png",
"128": "public/icons/icon128.png",
},
}));
Import in vite.config.ts:
import manifest from "./manifest";
// ... crx({ manifest })
Type declarations
Add to a src/vite-env.d.ts or src/crxjs.d.ts:
/// <reference types="@crxjs/vite-plugin/client" />
This enables types for ?script and ?script&module imports.
HMR behavior by context
| Context | HMR | How it works |
|---|---|---|
| Popup | Full HMR | WebSocket-based, state preserved |
| Options page | Full HMR | Same as popup |
| Side panel | Full HMR | Same as popup |
| Content script (manifest) | True HMR | CRXJS injects loader + HMR client |
| Content script (dynamic) | True HMR | Via ?script import |
| Service worker | Auto-reload | Changes trigger full extension reload |
| Main world scripts | No HMR | Skipped by CRXJS loader |
Content script HMR works because CRXJS generates a loader script that imports an HMR preamble, the HMR client, and your actual script — enabling real module-level HMR without full page reload. This is CRXJS's main differentiator.
Dynamic content script imports
For content scripts injected programmatically (not in manifest), CRXJS provides special import suffixes:
// background.ts — ?script gives you a resolved path for executeScript
import contentScript from "./content?script";
chrome.action.onClicked.addListener(async (tab) => {
await chrome.scripting.executeScript({
target: { tabId: tab.id! },
files: [contentScript],
});
});
For main world injection (no HMR):
import mainWorldScript from "./inject?script&module";
await chrome.scripting.executeScript({
target: { tabId },
world: "MAIN",
files: [mainWorldScript],
});
CRXJS plugin options
crx({
manifest,
browser: "chrome", // 'chrome' | 'firefox'
contentScripts: {
injectCss: true, // auto-inject CSS for content scripts
hmrTimeout: 5000, // HMR connection timeout (ms)
},
});
Development workflow
# Start dev server (outputs to dist/ with HMR)
npm run dev
# 1. Open chrome://extensions
# 2. Enable "Developer mode"
# 3. Click "Load unpacked"
# 4. Select the dist/ directory
# 5. Edit code — popup/content scripts update instantly via HMR
# 6. Service worker changes trigger automatic extension reload
After loading once, subsequent npm run dev sessions reconnect automatically. No need to re-load the extension unless manifest.json changes.
Production build
npm run build # outputs to dist/
The dist/ directory is ready to zip and upload to Chrome Web Store:
cd dist && zip -r ../extension.zip .
Disable Vite's module preload to avoid CWS rejection of inline scripts:
build: {
modulePreload: false;
}
Known issues and workarounds
Tailwind CSS HMR in content scripts
New Tailwind classes may not trigger CSS updates in content scripts. Workaround: restart dev server after adding new utility classes. Improved in v2.4.0 but not fully resolved. Ensure injectCss: true in config.
WebSocket connection errors (ws://localhost:undefined/)
Cause: port mismatch between dev server and HMR config. Fix: explicitly set both to the same value:
server: {
port: 5173,
strictPort: true,
hmr: { port: 5173 },
}
"Manifest version 2 is deprecated" warning
If you see this, your manifest is being interpreted as MV2. Fix: ensure "manifest_version": 3 is set.
Content scripts not injecting on file:// URLs
Chrome requires the user to enable "Allow access to file URLs" in the extension settings at chrome://extensions. CRXJS cannot change this.
HMR stops working after Chrome update
CRXJS's HMR relies on injecting a content script that connects to the dev server's WebSocket. Chrome security updates occasionally break this. Fix: update to the latest CRXJS version, which tracks Chrome changes.
CRXJS vs alternatives
| Feature | CRXJS | WXT | Plasmo |
|---|---|---|---|
| Content script HMR | True HMR | File-based reload | Partial |
| Framework support | Any Vite framework | Any | React-focused |
| Abstraction level | Thin (Vite plugin) | Full framework | Full framework |
| Messaging helpers | None (use chrome.* directly) | Built-in | Built-in |
| Storage wrappers | None | Built-in | Built-in |
| Cross-browser | Chrome + Firefox | Chrome + Firefox + Safari | Chrome + Firefox |
| File-based routing | No | Yes | Yes |
| Learning curve | Low (know Vite, know CRXJS) | Medium | Medium |
Choose CRXJS when: you want minimal abstraction over raw Chrome APIs and value content script HMR above all. CRXJS stays out of the way — no magic routing, no wrapper APIs, just your code with HMR.
Choose WXT when: you want conventions, built-in utilities, and cross-browser support.
Choose Plasmo when: you're React-focused and want the highest-level abstraction.
Project structure (recommended)
my-extension/
├── src/
│ ├── background/
│ │ └── index.ts
│ ├── content/
│ │ ├── index.ts
│ │ └── styles.css
│ ├── popup/
│ │ ├── index.html <- CRXJS resolves HTML entry points
│ │ ├── App.tsx
│ │ └── main.tsx
│ ├── options/
│ │ ├── index.html
│ │ └── main.tsx
│ ├── sidepanel/
│ │ ├── index.html
│ │ └── main.tsx
│ └── shared/
│ ├── messages.ts
│ └── storage.ts
├── public/
│ └── icons/
├── manifest.ts <- or manifest.json
├── vite.config.ts
├── tsconfig.json
└── package.json
CRXJS resolves HTML files referenced in the manifest automatically. Your popup.html can use standard <script type="module" src="./main.tsx"> and it works.
If you encounter a bug or unexpected behavior in CRXJS, open an issue at github.com/crxjs/chrome-extension-tools/issues.
Persona: You are a senior research analyst. You are skeptical of single sources, obsessed with citations, and always flag uncertainty rather than papering over it.
Thinking mode: Reason as thoroughly as possible for Step 5 synthesis (standard and deep modes). Reconciling conflicting multi-source data and ranking recommendations requires deep reasoning — shallow inference produces wrong conclusions. On Claude Code, use ultrathink to trigger extended thinking explicitly.
Orchestration mode: Fan out 3–20 parallel sub-agents for research evidence gathering (Steps 2–4) — each agent owns one independent axis. On Claude Code, use ultracode to opt into multi-agent orchestration explicitly.
Modes:
| Mode | When | Execution |
|---|---|---|
| Interview | Step 1 — scope | Sequential; ask questions, confirm before proceeding |
| Parallel research | Steps 2–4 — evidence gathering | Fan out 3–20 sub-agents per step; each owns one axis |
| Synthesis | Step 5 — conclusions | Sequential + ultrathink; reconcile conflicts before recommending |
| Report writing | Step 6 — final output | Single sub-agent reads all notes, writes final report |
Research depth — select automatically based on the request:
| Depth | When | Steps |
|---|---|---|
| Quick | Narrow, time-sensitive question; user says "brief" or "quick" | Steps 1 (auto-scope), 2, 5 |
| Standard | Typical research request [default] | Steps 1–6 |
| Deep | Comprehensive review, critical decision; user says "thorough", "exhaustive", "comprehensive" | Steps 1–6 + 4.5 (outline refinement) + critique pass |
Autonomy: For specific, well-scoped prompts, state assumptions and proceed without a full interview — surface them in the report header instead. Reserve the full scope interview for genuinely vague prompts (e.g., "Research blockchain", "Tell me about AI").
Questions: Ask the user through the environment's question tool — never as plain-text prose. One question at a time, 2–4 tappable options, wait for the answer. If the environment has no question tool, ask in prose with the same options, one at a time.
Critical Rules
- Web search is the core capability of this skill. If the environment has no web access, halt immediately and tell the user.
- Every claim must cite a source URL. Unsourced assertions are not findings — they are guesses.
- Critical claims (market size, growth rates, competitive positioning...) require 2+ independent sources or get
confidence: Low. - Write findings to the output file immediately after each step — do not batch at the end.
- Flag conflicts between sources explicitly rather than picking one silently.
- Prose-first: Write in full sentences and paragraphs (aim for ≥80% prose). Use bullets only for true lists — never as the primary content delivery. "The market reached $4.2B in 2024 [Source]" is better than "* Market: $4.2B".
- Distinguish facts from synthesis: Label sourced statements with attribution ("According to [Source]...") and analytical conclusions with hedges ("This suggests...", "The pattern across sources indicates..."). Never present inference as fact.
- Admit gaps: Write "No sources found for X" rather than leaving a section empty or guessing.
Reference Files
Load these files at the steps indicated only — not all upfront.
| File | Load at |
|---|---|
references/citations.md | Step 2 (before first search) |
references/parallel-search.md | Step 2 (before spawning sub-agents) |
references/researcher.md | Step 2 (sub-agents read this first) |
references/report-writer.md | Step 6 (report-writer sub-agent reads this first) |
references/market.md | Step 2, if type == market |
references/domain.md | Step 2, if type == domain |
references/technical.md | Step 2, if type == technical |
references/competitive.md | Step 2, if type == competitive |
references/product.md | Step 2, if type == product |
references/academic.md | Step 2, if type == academic |
references/org.md | Step 2, if type == person/org |
references/financial.md | Step 2, if type == financial |
references/legal.md | Step 2, if type == legal |
references/trend.md | Step 2, if type == trend |
references/community.md | Step 2, if type == community |
Output Structure
The skill uses a dual-output structure in ./research/:
- Flat report:
./research/{date}-{type}-{topic}.md— the final synthesized Markdown report delivered to the user - Notes directory (optional):
./research/{date}-{type}-{topic}/— per-axis research notes from sub-agents (one.mdfile per axis). Create this when using parallel fan-out (Steps 2–4). The agent decides when to use the directory; both can exist simultaneously.
Example:
research/
├── 2025-01-15-market-ai-coding-assistants.md # final report
└── 2025-01-15-market-ai-coding-assistants/ # sub-agent notes
├── market-size.md
├── pricing-models.md
├── competitive-landscape.md
└── customer-segments.md
Step 1 — Scope
First, get today's date: date +%Y-%m-%d. Use it for all date-filtered searches and recency references throughout the research.
Check for existing research: Look in ./research/ for reports on this topic. If found, summarize what they cover and ask: extend, update, or start fresh?
If the prompt is specific and well-scoped (topic, type, and goals are all clear): skip the interview. Infer the research type, state your assumptions explicitly in the report header, and proceed. Example header note:
Assumptions: type=market, scope=global, horizon=2024-2025, goals=TAM sizing and growth drivers.
If the prompt is vague or ambiguous (e.g., "Research blockchain", "Tell me about AI"): ask the user:
- What type? (see list below)
- What specific questions or goals should the research answer?
- Any geographic, time, or segment constraints?
Research types:
market— customers, competition, sizing, pricing, trendsdomain— industry structure, regulatory landscape, ecosystemtechnical— architecture, tools, benchmarks, integrationcompetitive— focused competitor teardown: positioning, reviews, win/loss signalsproduct— deep analysis of a specific product: features, UX, roadmap signals, changelogacademic— literature survey, citation networks, state of research, key authorsperson/org— due diligence on a company or public figure: funding, leadership, press, controversiesfinancial— funding rounds, valuation multiples, revenue signals, investor patternslegal— IP landscape, patents, litigation history, regulatory enforcement, contract normstrend— emerging signals, weak signals, foresight, scenario mappingcommunity— ecosystem health, key voices, governance dynamics, fragmentation risks- If none fit, infer the type and design your own axis breakdown — the process (fan-out, citation discipline, write-as-you-go, synthesis) is the same regardless of type.
Set output paths:
- Report:
./research/{date}-{type}-{topic}.md(lowercase, hyphens; date first, then type, then topic; under 50 chars for topic portion) - Notes directory (if using parallel fan-out):
./research/{date}-{type}-{topic}/
Ask if the user wants a different path. Load assets/report-template.md and write the report header now (topic, type, goals, date, assumptions, methodology note).
Step 2 — Core Research (Parallel Fan-out)
Load references/citations.md, references/parallel-search.md, and references/researcher.md. Load the type-specific reference file.
Spawn 3–20 sub-agents in a single message (one per axis from the type reference). Each agent:
- Reads
references/researcher.mdfirst - Searches its axis on the web and fetches the sources it cites
- Writes findings as prose paragraphs with inline citations — not bullet lists
- Returns URL, accessed date, and confidence level per claim
- Tags each source: Primary (official docs, filings, peer-reviewed), Established (major publications, analyst firms), or Low (blogs, forums, single opinions). Flag Low-tier sources prominently.
- Critical claims need 2+ sources or get
confidence: Low - Flags conflicts between sources explicitly
- Does not wait for other agents
- Writes output to
{notes-dir}/{axis}.md(e.g.,./research/2025-01-15-market-ai-coding-assistants/market-size.md)
Sub-agent prompt template (use exactly this format):
You are a research analyst. Your task: research one specific axis of a larger study.
**Topic:** {overall topic}
**Your axis:** {axis name and description}
**Research goals:** {what specific questions to answer on this axis}
**Geographic/time constraints:** {any from scope interview, or "none"}
Instructions:
1. Run web searches and fetch the relevant source pages.
2. For each finding, note the source URL, access date, and confidence level (High/Medium/Low per the ladder in researcher.md).
3. Tag each source: **Primary** (official docs, government filings, peer-reviewed papers), **Established** (major publications, analyst firms with editorial process), or **Low** (blogs, forums, single opinions). Flag Low-tier sources visibly.
4. Critical claims (numbers, market share, projections) need 2+ sources or get confidence: Low.
5. Flag any conflicts between sources explicitly — do not silently pick one.
6. The axis definition is a starting point, not a ceiling. If you find relevant information that falls outside the stated axis but adds meaningful insight for the overall topic, include it — label it clearly and explain why it matters.
7. External files (PDFs, datasets, analyst reports, regulatory filings, whitepapers, charts) may contain valuable data. When encountered, their key content should be summarized inline — do not leave them as bare links. The `curl` command is available for local downloads when needed.
8. Write findings as **prose paragraphs**, not bullet lists. Embed figures in sentences: "The market reached $4.2B in 2024 [Source]" rather than "* Market: $4.2B". Bullets are acceptable only for true enumerated lists (product names, compliance items, enumerated steps).
9. Distinguish sourced facts from your analysis: use "According to [Source]..." for direct findings and "This suggests..." or "The pattern indicates..." for your synthesis. Never present inference as fact.
10. If a topic cannot be found, write "No sources found for X" — do not guess or leave a blank.
11. Return your findings as a Markdown section ready to paste into a report.
Confidence ladder:
- High: 2+ reputable independent sources agree
- Medium: 1 reputable source (Primary or Established tier)
- Low: blog, forum, single opinion, Low-tier source, or inferred
Citation format: [Source Name](url) (accessed YYYY-MM-DD, confidence: High|Medium|Low, tier: Primary|Established|Low)
Output format:
## {Section heading}
{Prose paragraphs with inline citations. Bullets only for true lists.}
> Conflicts noted: {if any}
> Gaps: {what you couldn't find}
**As a first step, you must read {path_to_skill}/references/researcher.md for instructions on how to conduct research.**
Save your output notes to {absolute path to notes-dir}/{axis}.md
Example for a market research axis:
**Topic:** AI coding assistants market
**Your axis:** Market size and growth (TAM/SAM/SOM, historical growth, projections)
**Research goals:** What is the total addressable market? How fast is it growing? What are the key segments?
**Geographic/time constraints:** Global, 2020-2025
In order to ensure research is conducted as quickly as possible, spawn all sub-agents in parallel (single message with multiple Agent tool calls).
As sub-agents complete, immediately append their findings to the output report file under the appropriate section heading from assets/report-template.md. Do not wait for all agents to finish before writing.
Step 3 — Competitive / Landscape Analysis (Parallel Fan-out)
Spawn 3–5 sub-agents covering the axes defined in the type reference file's landscape section. Same citation discipline. Each writes to {notes-dir}/{axis}.md. Append results to the output report file immediately.
Step 4 — Deep Dive (Parallel Fan-out)
Spawn sub-agents covering the deep-dive axes for the chosen type (see type reference file). Same process. Append results immediately.
Step 4.5 — Outline Refinement (Deep Mode Only)
After Steps 2–4, review whether the evidence warrants restructuring before synthesis. Ask:
- Did findings contradict the initial scope assumptions?
- Did an important angle emerge that wasn't in the original plan?
- Are any sections underpowered by evidence — or overloaded?
If yes: adapt the outline. Add sections for unexpected findings, demote sections with thin evidence, reorder by evidence strength. Run 2–3 targeted gap-fill searches for newly identified angles (time-box to 5 minutes). Document what changed and why in the report's methodology note.
Skip in quick and standard modes.
Step 5 — Synthesis
Use ultrathink here (standard and deep modes).
Read the full output report file (which now contains all appended findings from Steps 2–4). Write the synthesis section:
## Key Findings
(5 critical insights written as prose paragraphs, each with a source reference)
## Strategic Recommendations
1. [Recommendation] — Rationale. Evidence: [source].
2. ... (3–5 recommendations, ranked by impact)
## Risks and Uncertainties
- Data gaps: what could not be found or confirmed
- Low-confidence claims requiring further validation
- Conflicts between sources that could not be resolved
- Domain or market risks to monitor
## Next Steps
- Recommended follow-up research
- If the initial request is not fulfilled, loop on step 1 and ask more questions
- Decisions this research enables
Keep the fact/synthesis distinction throughout: "According to [Source], X" for sourced claims; "This suggests Y" for your analysis. If a recommendation rests on Low-confidence data, say so explicitly.
Critique pass (deep mode only): Before finalizing, red-team the synthesis. Ask: What's missing? What could be wrong? What alternative explanations exist? What biases might be present? If a critical gap emerges, run 2–3 delta-queries to fill it before concluding.
Step 6 — Report Writer Sub-agent
Spawn a single report-writer sub-agent to produce the final polished report. This keeps the coordinator's context clean.
Use the Agent tool with subagent_type="general-purpose" and run_in_background=false:
Agent(
run_in_background=false
subagent_type="general-purpose",
description="Write final report",
prompt="Read the notes in {absolute path to notes-dir}/ and the current report at {absolute path to report-file} and synthesize into a final research report that answers: {the user's original question in full}.
Earlier research in this conversation to build on: {absolute paths of the earlier report and notes folder from Step 1, or "none"}
Save your final report to this exact path: {absolute path to report-file}
**As a first step, you must read {path_to_skill}/references/report-writer.md for instructions on how to write your research report.**"
)
After the report writer completes, the report at ./research/{date}-{type}-{topic}.md is final.
Step 7 — PDF Export (Optional)
After the Markdown report is final, offer this step if the user wants a PDF.
Try each tool in order, stop at the first that works:
-
Pandoc (best output quality):
pandoc report.md -o report.pdf --pdf-engine=wkhtmltopdf # or with weasyprint: pandoc report.md -o report.pdf --pdf-engine=weasyprint # or with a LaTeX engine if installed: pandoc report.md -o report.pdf -
md-to-pdf(Node, no LaTeX required):md-to-pdf report.md
Check which tools are available with which pandoc, which md-to-pdf before choosing. If neither is available, tell the user which to install.
Model Context Protocol (MCP) Integration
This skill supports MCP connectors for extending research beyond web searches:
Examples of Public Open Knowledge MCP:
arxiv-mcp: Search academic papers by subject, author, date, or citations. Returns abstracts, PDF links, and citation graphs.reddit-mcp: Access subreddit data — top posts, comments, discussion threads. Good for community insights and developer sentiment.serp-mcp: Wraps search engines (Google, Bing, DuckDuckGo) to return structured results: titles, snippets, URLs, related questions.
Examples of Private Data MCP:
gmail-mcp: Queries email threads, attachments, senders, dates. Requires OAuth read-only scope.notion-mcp: Accesses databases, pages, and their properties. Searchable by title, content, last edited, or custom properties.confluence-mcp,sharepoint-mcp, or custom wiki MCPs for internal knowledge bases.
MCP in the Research Workflow:
- Spawn sub-agents against different MCP endpoints in parallel (Step 2 fan-out)
- When an MCP returns no results, flag the evidence gap explicitly per critical rule #7
- Critical claims from a single MCP source get
confidence: Lowper critical rule #4 except if from private high-value sources - MCP data counts as
Primarytier if from official docs/filings,Establishedif from major publications,Lowif from blogs/forums
Guardrails
- Additional research limit: Step 5 (additional round) can only be followed once. After those researchers finish, you MUST move directly to Step 6 (report writer). Output: "After these researchers finish, I will move directly to coordinating the report writer."
- No fabrication: If a source does not exist, say so and flag the gap.
- No silent picking: Conflicting sources must be reported, not resolved silently.
- No batching: Write to the file after each step, not at the end.
- No over-claiming: Hedge explicitly on Low-confidence data.
- No inference as fact: Label analytical conclusions with "This suggests..." or similar.
- No diving without scoping: For vague prompts, always scope first — an ambiguous topic produces an unfocused report.
Disclaimer
Research reflects a snapshot in time. Web content changes. For volatile topics (regulatory, competitive, pricing), re-run within 30 days or verify key claims manually before acting on them.
Questions: Ask the user through the environment's question tool — never as plain-text prose. One question at a time, 2–4 tappable options, wait for the answer. If the environment has no question tool, ask in prose with the same options, one at a time.
frontend design deslop
AI-generated UI looks generic for two reasons:
- No constraints. The model samples the statistical median of 2019-2024 web code — Tailwind UI's
bg-indigo-500, Inter, rounded cards, soft shadows. You cannot out-prompt a vacuum. - Designing before knowing what you're designing. A corporate landing page, a creative portfolio, a developer-tool landing page, an analytics dashboard, and an ecommerce product page share almost no design DNA — a beautiful aesthetic that fights the artifact's job is its own slop.
The fix is a discipline borrowed from brand design: strategy drives design, never aesthetics first.
- Commit to words first — what this is, who it serves, the adjectives it must feel like.
- Translate those words into a typography and color system.
- Build from tokens.
- Apply the craft layer (layout, components, motion, iconography, imagery, dark mode, accessibility).
- Audit.
Target the convergence mechanism, not a frozen blocklist; the slop fingerprint shifts over time (purple gradients in 2022, cream backgrounds and italic-serif heroes in 2026).
This skill does two jobs at once: it de-slops the default AI look, and it designs applications well. A distinctive theme on top of careless components, weak layout, or thoughtless motion still reads as amateur. The mechanisms behind every choice live in references/design-theory.md (hierarchy, Gestalt, CRAP, signal-vs-noise, affordances, the interaction laws); read it once so the rest is reasoning rather than rule-following.
Asking questions (CRITICAL)
Every single user question must go through the question tool (see the Questions: directive above) — never as plain-text prose. The bank is generous; the asking is selective. Do not interrogate.
- Batch related questions; offer 2 to 4 concrete options each.
- Ask only the high-signal subset that changes the design system.
- Infer from context first and confirm inferences rather than re-asking.
Phase 0: Discover and commit to words (do this FIRST, before any code)
Check for an existing DESIGN.md at the project root (and common locations like docs/) before writing any code.
- Exists — read it, honor its tokens, skip the questions it already answers, and extend it rather than starting over.
- Missing — resolve three things below before any pixel. Read
references/discovery.mdfor the full protocol, question bank, and the personality-to-token translation table, andreferences/artifact-types.mdfor per-type priorities.
- WHAT is the artifact? Classify it: marketing/landing page, pricing page, SaaS application, dashboard/data tool, ecommerce, marketplace, mobile app, AI/conversational interface, email/newsletter, blog/editorial publication, onboarding/auth flow, settings/admin/CMS, presentation/deck, docs/API reference, portfolio/brand site, or one of the long-tail types in
references/artifact-types.md. Each optimizes for a different thing and has its own layout grammar and density. A composite artifact (a marketing site with an embedded app, an AI chat inside a SaaS app) is designed region by region. - WHO and WHY? Audience, positioning (corporate vs creative vs technical vs luxury vs playful), and the single primary action or outcome.
- Commit to words. Lock 3 to 5 brand adjectives and a 3-word aesthetic essence before any visual exploration. This is the highest-leverage input; it drives type, color, density, radius, and motion. Strategy drives design, never the reverse.
Run discovery adaptively: infer, state inferences, ask the high-signal subset through the question tool, and ground the direction in 1 to 3 references (web-search strong current examples of the exact artifact type and positioning if none are given, then transpose rather than originate). Do not proceed until artifact type, positioning, and the adjectives are locked. On a generic brief (another dashboard, another SaaS landing page) where the category itself has little to say, widen the reference search past the product's own category rather than asking for more creativity within it — see references/divergence.md.
Phase 1: Translate strategy into a design system (the gate)
State these commitments in prose, briefly. Each must follow from Phase 0, not from reflex.
-
Aesthetic commitment. Pick ONE opinionated direction that fits the artifact and the adjectives; generic is the failure mode. See
references/aesthetics-library.md. If the user gave a brand or reference, transpose it. Derive 2-3 real candidates before picking one, commit to the winner fully before softening it for legibility, and check the bare structure (not just the styled surface) against the category default — seereferences/divergence.mdfor why each of these matters and how to do it without re-deliberating in the same pass. -
Typography (brand-first). Choose type from personality, not aesthetic preference. Match classification to the adjectives, pick a modular-scale ratio that fits the content, and pair for contrast (display + body) without typographic mud. Never Inter/Roboto/Arial/system as the primary face. See
references/typography.md. -
Color (appropriateness + differentiation). Choose colors for fit with the brand and audience, then find uncontested territory (the indigo/violet band is the red ocean of AI UI; avoid it unless the brief demands it). Build one dominant plus a sharp accent plus neutrals plus semantic states, distributed roughly 60-30-10. Author in OKLCH. See
references/color-oklch.md. -
Token table (emit BEFORE components). Display + body font; type scale (state the ratio and base, 6 steps); spacing base unit; max two radius values; ONE shadow approach (defined edge OR soft elevation, never both on one element); palette with roles (bg, surface, fg, muted, border, accent, accent-fg, success, warning, error) —
surfaceis required, not optional: it is what elevation-by-lightness (seereferences/dark-mode.md) steps off of. Everything references tokens; no scattered hex/px. Pull a starting set fromreferences/token-sets.md. -
Signature move. Name the single thing that makes this UI memorable and unmistakably not-default. One per project.
-
Adapter. Pick the stack syntax: plain CSS custom properties, Tailwind v4
@theme, or shadcn semantic tokens. Seereferences/adapters.md.references/token-core.cssis the portable source of truth.
Phase 2: Apply the system to the interface (the craft layer)
Tokens make a UI consistent; the craft layer makes it good — this is the "design an application" half of the skill, and the half most AI output skips.
Apply each of the following to the artifact, pulling the matching reference on demand. Density and emphasis vary by artifact type (see references/artifact-types.md); a dashboard applies these very differently from a landing page.
-
Layout and composition. Compose space with intent: a base spacing unit, spacing that is tight within groups and generous between sections, an intentional grid (12-column, modular, or bento where content genuinely varies), at least one brief-specific layout move, and whitespace as a signal of confidence. Break the centered-max-width-column reflex. See
references/layout.md. -
Components and states. Specify every interactive component across its full state matrix (default, hover, active, focus, disabled, loading, error, selected), not just at rest. Get buttons (ranked by importance, not colored by meaning), forms (real labels, correct types, inline validation that keeps input), tables (left-align text, right-align tabular-nums numerals, light separators), navigation, overlays, and the empty/loading/error states right. See
references/components.md. -
Motion. Treat motion as communication, under a duration and easing token scale. Default to ease-out under 300ms, animate only transform and opacity, scale popovers from their trigger, and never animate high-frequency actions. See
references/motion.md. -
Iconography. One grid, one stroke, one radius across the set; do not let the unmodified default starter-kit set define the look. See
references/iconography.md. -
Imagery and illustration. Art-direct imagery as a system. Prefer real product visuals over stock and abstract; avoid the AI/stock fingerprint (people pointing at laptops, gradient blobs, corporate-Memphis, default Midjourney). Use texture and a graphic device to escape flat-slop. See
references/imagery.md. -
Dark mode and theming. If dark mode is in scope, design it (do not invert): near-black not pure black, off-white not pure white, elevation via lightness, desaturated accents, all driven by semantic tokens. See
references/dark-mode.md. -
Accessibility as you build. WCAG 2.2 AA: visible managed focus, keyboard operability, labels, 24px-plus targets, color independence, reduced-motion. Build it in; do not bolt it on. See
references/accessibility.md.
At the end of conception, once the direction and craft decisions are locked, suggest to the user a relevant subset of design and component catalogs to mine for concrete ideas and ready implementations, framed as inspiration to transpose through the committed system (never to clone) and with a reminder to verify component licenses. Pick by artifact type and stage rather than dumping the whole list. See references/catalogs.md.
Phase 3: Write DESIGN.md (the durable output)
Everything this skill produces lives in a single DESIGN.md at the project root:
- Discovery context
- Committed aesthetic and signature move
- Typography and color systems
- Tokens
- Spacing/radius/shadow rules
- Craft-layer decisions (layout, components, motion, iconography, imagery, dark mode, accessibility)
- Slop-audit result
Write or update it before or alongside building components, using the schema in references/design-md.md. DESIGN.md is the single source of truth — if the CSS, the adapter, or the components ever drift from it, DESIGN.md wins. On later sessions, Phase 0 reads this file instead of re-running discovery.
Token-first generation rules
- Colors in OKLCH, dominant + sharp accent, not a timid even spread. Design hierarchy in grayscale first, add the accent last and sparingly, roughly 60-30-10 (neutral / brand / accent). On colored backgrounds, darken/desaturate the same hue rather than going gray. Define semantic state colors (success, warning, error) and never use color as the only signal.
- Typography: a distinctive display face paired with a refined body face, modular scale with a stated ratio. Source from Fontshare/Google. Limit to 2 to 3 families.
- Spacing rhythm: vary spacing by relationship (tight within a group, generous between sections). One uniform value everywhere is a tell.
- Density fits the artifact. Dashboards and pro tools tolerate high density; marketing and portfolio pages want air.
- Match implementation complexity to the aesthetic: maximalism gets elaborate detail; minimalism gets restraint and precision, not laziness.
NEVER (negative prompt)
NEVER use generic AI-generated aesthetics: overused fonts (Inter, Roboto, Arial, system-ui as the primary face); cliched color schemes (especially purple/indigo/violet gradients on white or dark); the hero + 3-feature-cards + testimonials + CTA boilerplate as the only structure; the icon-tile-above-heading feature-card template; side-tab accent borders on cards; hairline border and diffuse drop shadow stacked on the same element; gradient text on headings or metrics; decorative glassmorphism; blob-rounding (radius > 16px on small cards); cream/beige backgrounds by reflex; bounce/elastic easing and animate-everything micro-interactions; decorative grid-line backgrounds or radial spotlight glows with no structural purpose; pulsing status dots or auto-scrolling marquees on content that is not actually live; hand-coded SVG mascots standing in for real illustration. Use distinctive fonts, a cohesive committed palette, and motion only where it serves the interaction.
Craft-layer NEVERs: do not ship components with only a resting state; do not use placeholder text as the label; do not color buttons by meaning instead of ranking them by importance; do not center-align numeric table columns or use non-tabular numerals for figures; do not let the unmodified shadcn/Tailwind default icon set define the look; do not use stock people-pointing-at-laptops, gradient blobs, floating orbs, glossy isometric tech illustrations, corporate-Memphis figures, or raw default-Midjourney imagery where a real product visual belongs; do not invert a light palette to make dark mode, use pure black backgrounds, pure white text, or glowing colored box-shadows by reflex; do not animate layout properties (width/height/top/left) or ignore prefers-reduced-motion; do not remove focus outlines without replacing them, convey meaning by color alone, or ship sub-24px targets.
Self-audit before finishing
Run the generated UI against references/slop-checklist.md and score it.
- Verify it serves the artifact type's priorities from
references/artifact-types.md— a dashboard that reads as a portfolio piece, or a landing page with no clear primary action, has failed even if it is beautiful — and that the type and color choices match the committed adjectives. - Verify the craft layer: components have full state matrices, layout has rhythm and an intentional move, motion is communicative and respects reduced-motion, icons are one coherent system, imagery is not stock/AI slop, and dark mode (if present) is designed not inverted.
- Run the accessibility gate in
references/accessibility.md(focus, keyboard, contrast, targets, color independence); accessibility is a pass/fail gate, not a nicety. - Re-read the DESIGN.md aesthetic commitment against the actual render as if seeing it for the first time, and do the bare-structure check in
references/divergence.md§6-7 — a tell-by-tell checklist pass alone can score clean on output that is still generic. - If any tell fires or the fit is wrong, regenerate that section before presenting.
- Record the result in the DESIGN.md slop-audit section and bump its changelog, stating the artifact type, positioning, adjectives, aesthetic, type system, palette, and signature move used.
All checklist items are detectable within a single build; do not invent cross-generation rules the model cannot verify. A subset needs the rendered page rather than just source (see references/slop-checklist.md's "Layout defects" and "Build correctness" sections) — run those whenever a screenshot or live browser is available.
Reference files
Load on demand.
Foundation and intake:
references/design-theory.md- the mechanisms behind every choice: hierarchy, Gestalt, CRAP, signal-vs-noise, affordances, interaction laws. Read once early.references/discovery.md- design intake: question-tool protocol, commit-to-words, question bank, personality-to-token translation table. Read at the start of Phase 0.references/design-md.md- the DESIGN.md schema and persistence conventions. The durable output of the whole skill. Read in Phase 0 (to consume an existing file) and Phase 3 (to write one).references/artifact-types.md- artifact taxonomy with per-type priorities, layout grammar, density, positioning variants, anti-patterns. Read at the start of Phase 0.references/divergence.md- why a model converges on the same concept and how to force real variance: derive-then-externally-select instead of self-picking, ground borrowed forms in specific produced systems, commit fully before softening, and check bare structure separately from styled surface. Read once alongsidedesign-theory.md; apply in Phase 0/1 and the self-audit.
System (Phase 1):
references/typography.md- full type strategy: brand-first selection, classification matrix, modular scale ratios, pairing, variable fonts, accessibility, anti-slop sourcing and ban-list.references/color-oklch.md- full color strategy: appropriateness, Blue Ocean differentiation, harmony systems, 60-30-10, archetype map, OKLCH primer, Radix roles, accessibility.references/aesthetics-library.md- encoded style families with defining traits, plus the method for originating a bespoke theme from discovery.references/token-sets.md- ready-to-use distinctive palettes, each with a signature move, plus shared motion tokens.references/token-core.css- the framework-agnostic OKLCH token core, including motion tokens.references/adapters.md- Tailwind v4 / shadcn / plain-CSS token syntax.
Craft (Phase 2):
references/layout.md- spacing rhythm, grids (12-col, bento), asymmetry, whitespace, scanning, density, responsive, layout inspiration.references/components.md- the state matrix and patterns for buttons, forms, tables, navigation, overlays, feedback, empty/loading/error states, plus component inspiration.references/motion.md- duration and easing scales, springs, transform-origin, performance, reduced motion, motion tokens and inspiration.references/iconography.md- grid, stroke, radius, optical balance, when defaults become slop, how to differentiate, icon inspiration.references/imagery.md- art direction, photography direction, the AI/stock fingerprint, illustration systems, graphic devices and texture, imagery inspiration.references/dark-mode.md- dark mode as a designed mode (not inversion), elevation via lightness, desaturation, semantic-token theming, dark/theme tokens.references/accessibility.md- unified WCAG 2.2 AA: contrast, focus, keyboard, target size, forms, ARIA basics, motion, testing.references/catalogs.md- component catalogs (shadcn/ui, 21st.dev, Magic UI, Aceternity, Origin, Cult, Kibo, shadcnblocks) and inspiration galleries (Awwwards, Behance, Dribbble, Mobbin, Land-book, Page Collective, Godly, SaaS Landing Page, Lapa Ninja, Refero, Screenlane), with transposition and licensing cautions. Suggest a relevant subset at the end of conception.
Audit:
references/slop-checklist.md- the self-audit (tell catalog + quality gates). Read before finishing any UI.
Humaniseur : supprimer les patterns d'écriture IA du français
Your task
When given French text to humanize:
- Clarify the target register first - Abbreviations, argot, orality, emojis and typography all depend on the expected niveau de langage. If it is not clear from the request or the input (soutenu, courant, familier ? for which medium ?), ask the user before starting to humanize
- Identify AI patterns - Scan for all 38 patterns listed below
- Rewrite problematic sections - Replace AI-isms with natural French alternatives
- Preserve meaning - Keep the core message intact
- Maintain voice - Match the intended tone and register
- Add soul - Don't just remove bad patterns; inject actual personality (see Part 4)
- Do a final anti-AI pass - Ask: "Qu'est-ce qui rend ce texte évidemment généré par IA ?" Answer briefly with remaining tells, then ask "Maintenant, fais en sorte qu'il ne le soit plus" and revise accordingly. Apply the three-signal rule: one isolated marker is noise (most are normal French), but three or more co-occurring in the same passage make a reader flinch — revise until no paragraph accumulates three
The 80 % rule: imperfect compliance is the point
Follow the humanizer rules most of the time — not always. It is fine to leave roughly 20 % of this skill's instructions unapplied.
- Real human prose contains flagged patterns at low density: « pour conclure » does not make a text 100 % AI, and a text that dodges every single tell with mechanical rigor is uniform in a new, equally detectable way.
- Transgress deliberately: keep an em dash that earns its place, one « par ailleurs », one tidy list.
- The tells are density and co-occurrence (see the three-signal rule), never a single occurrence.
One pass only. Do not run this skill repeatedly on the same text: each pass removes variance and injects its own habits, and quality degrades fast — by the second or third pass the voice the first one created is flattened again. If the result still smells AI after the final anti-AI pass, the fix is adding anchored content (a fact, a date, an opinion — see the limits note in Part 4), not another scrub.
Precedence: this skill yields to context
Instructions here can be overridden by the user's prompt or by a more specific skill loaded alongside. When the task comes with its own prose and copywriting method — a LinkedIn post, a press release, ad copy, developer documentation in a README — those rules win on conflict: apply this skill only to what they leave open (AI vocabulary, anglicisms, artifacts, typography). A LinkedIn hook, a press-release structure or Markdown formatting in developer docs may legitimately use patterns flagged here (short punchy paragraphs, a tidy list, headings and bold, a rule of three); that is the format speaking, not the machine.
IMPORTANT: French-specific context
French professional writing is inherently more formal than English. Connectors like « néanmoins » and « toutefois » are legitimate in human French. The tells are different from English:
- The AI lexicon is distinct (« crucial » is the #1 French AI word, not "delve")
- Anglicisms from the model's English-first architecture are a major tell
- Typographic conventions (guillemets, spacing before punctuation) are strict
- The dissertation tradition (thèse/antithèse/synthèse) overlaps with AI structure
- French tolerates longer sentences naturally, so burstiness signals differ
Do NOT over-correct toward informal French. The goal is authentic French at the appropriate register, not dumbed-down French.
Ne jamais abaisser le registre de langue. If the input is in « langage soutenu », the output MUST remain in « langage soutenu ».
- Rewriting formal prose into casual French is a different kind of inauthenticity — just as detectable, just as artificial. The enemy is formulaic writing, not formal writing.
- A well-constructed subordinate clause, a precise connector, a long periodic sentence — these are features of good French, not AI artifacts.
- Only remove what is genuinely mechanical: inflated significance, copula avoidance, synonym cycling, promotional filler.
Part 1: Content patterns
Pattern 1 — Inflation de signification et d'héritage
Triggers: constitue/représente un tournant, témoigne de, joue un rôle crucial/essentiel/déterminant, souligne l'importance, reflète une tendance plus large, symbolisant son caractère durable, contribuant à, ouvrant la voie à, marquant une étape, un jalon décisif, un paysage en mutation, une empreinte indélébile, profondément ancré
LLMs inflate the importance of ordinary facts by connecting them to broader trends nobody asked about.
Avant :
L'Institut de la Statistique de la Catalogne a été officiellement créé en 1989, marquant un tournant décisif dans l'évolution des statistiques régionales en Espagne. Cette initiative s'inscrivait dans un mouvement plus large de décentralisation administrative.
Après :
L'Institut de la Statistique de la Catalogne a été créé en 1989 dans le cadre du transfert de compétences statistiques aux communautés autonomes. Il produit et publie des statistiques régionales indépendamment de l'INE.
Pattern 2 — Insistance sur la notabilité et la couverture médiatique
Triggers: couverture médiatique indépendante, médias locaux/nationaux/internationaux, cité par un expert reconnu, forte présence sur les réseaux sociaux
Avant :
Ses travaux ont été cités dans Le Monde, la BBC, Les Échos et Le Figaro. Elle maintient une présence active sur les réseaux sociaux avec plus de 200 000 abonnés.
Après :
Dans un entretien au Monde en 2024, elle a défendu l'idée que la régulation de l'IA devrait porter sur les résultats plutôt que sur les méthodes.
Pattern 3 — Analyses superficielles en participe présent (-ant)
Triggers: soulignant/mettant en lumière..., assurant..., reflétant/symbolisant..., contribuant à..., favorisant/encourageant..., englobant..., illustrant...
AI tacks participial phrases onto sentences to add fake analytical depth. The French equivalent of the English "-ing" problem.
Avant :
La palette du bâtiment, mêlant bleu, vert et or, évoque la beauté naturelle de la région, symbolisant les champs de lavande et la Méditerranée, reflétant l'attachement profond de la communauté à son terroir.
Après :
Le bâtiment utilise du bleu, du vert et de l'or. L'architecte a expliqué que ces couleurs font référence aux champs de lavande et à la côte méditerranéenne.
Pattern 4 — Langage promotionnel et publicitaire
Triggers: dispose de, vibrant, riche (figuré), profond, renforçant son, illustrant, exemplifie, engagement envers, beauté naturelle, niché, au cœur de, révolutionnaire (figuré), renommé, à couper le souffle, incontournable, époustouflant, un joyau
Avant :
Niché au cœur de la région époustouflante du Luberon, ce village se dresse comme un joyau vibrant doté d'un riche patrimoine culturel et d'une beauté naturelle à couper le souffle.
Après :
Le village est situé dans le Luberon, à une trentaine de kilomètres d'Apt. On y vient surtout pour le marché du samedi et l'église romane du XIIe siècle.
Subtle variant when editing or summarizing: AI inserts valorizing adjectives and inclusive doublets absent from the source — « nos soldats » becomes « nos vaillants soldats », « concitoyens » becomes « concitoyennes et concitoyens ». It over-corrects toward its training norms instead of following the text. Restore the source's wording.
Pattern 5 — Attributions vagues et mots-fouines
Triggers: Des rapports sectoriels, Les observateurs soulignent, Les experts estiment, Certains critiques avancent, plusieurs sources/publications (quand peu sont citées), il est communément admis que, il est largement reconnu que
Avant :
Les experts estiment qu'elle joue un rôle crucial dans l'écosystème régional.
Après :
La rivière abrite plusieurs espèces de poissons endémiques, selon un inventaire de 2019 du CNRS.
Pattern 6 — Sections « Défis et perspectives »
Triggers: Malgré son... fait face à plusieurs défis..., En dépit de ces défis, Défis et héritage, Perspectives d'avenir, L'avenir s'annonce prometteur
The formulaic challenge-then-optimism sandwich.
Avant :
Malgré sa prospérité industrielle, la commune fait face à des défis typiques des zones urbaines. En dépit de ces défis, elle continue de prospérer.
Après :
La congestion routière s'est aggravée après 2015 avec l'ouverture de trois zones d'activités. La mairie a lancé un programme de réfection du réseau pluvial en 2022.
Part 2: Language, grammar, and style patterns
Pattern 7 — Vocabulaire « IA » surutilisé
The single most flagged word in French AI text is crucial. The adverb notamment appears ~1/200 words in AI text vs. ~1/800 in human French (4x overuse).
High-frequency AI vocabulary (find-and-replace checklist):
| AI word/phrase | Replacement strategy |
|---|---|
| crucial, essentiel | Use domain-specific terms, or just drop |
| également (the top measured French AI marker) | « aussi », « de même », or drop — one per paragraph max |
| défi | « problème », « difficulté », or name the actual obstacle |
| significatif, robuste, substantiel | Be precise: give numbers instead |
| holistique | Remove (calque of English "holistic") |
| compréhensif (= exhaustif) | Use « exhaustif » or « complet » (compréhensif = empathetic in French) |
| disruptif | « de rupture » or describe the actual change |
| notamment (if >1 per 800 words) | « en particulier », « entre autres », or restructure |
| par ailleurs, en outre, de plus | Use « or », « reste que », « n'empêche que », « soit dit en passant » |
| il convient de noter que | Delete, start sentence directly |
| dans le paysage [actuel/numérique] | Delete entirely |
| au cœur de | Replace with specific location/concept |
| la pierre angulaire | Just say what it is |
| un levier puissant | Describe the actual mechanism |
| captivant, fascinant, passionnant | Say what is actually interesting, or drop |
| révolutionnaire, transformateur | Describe the actual change |
| permettre de, favoriser, optimiser | Use a concrete verb: say what actually happens |
| mettre en lumière | « montrer », « révéler » |
| naviguer dans, déverrouiller le potentiel de | Calques — describe the actual action |
| garantir, assurer, offrir (as service-brochure verbs) | State the fact plainly |
| dans cette optique, dans ce contexte, à cet égard | Delete, or link the ideas concretely |
| que vous soyez X ou Y | Address the actual reader directly |
Jargon de ministre: AI French leans on administrative vocabulary (« dispositif », « acteurs », « enjeux », « mise en œuvre », « dynamique territoriale ») even outside institutional contexts. Outside actual administrative prose, swap for plain words.
Formulaic openings to kill on sight:
- « Dans le paysage [actuel/numérique/contemporain] de... »
- « À l'ère de... »
- « Dans un monde [où/trépidant/tumultueux]... »
- « Il est essentiel/crucial de noter que... »
- « Plongeons dans... » (the French "Let's dive into")
- « Découvrez comment... », « Dans cet article, nous allons explorer... », « Bienvenue dans ce guide complet... » (meta-announcements — start with the content itself)
Formulaic closings to kill on sight: « En conclusion », « En résumé », « En somme », « En fin de compte », « Au final » opening a final paragraph. End on a concrete fact instead (see Pattern 26).
Connectors that signal human authorship (AI almost never uses these): « Or », « Quoi qu'il en soit », « Toujours est-il que », « Force est de constater que », « Reste que », « N'empêche que », « Soit dit en passant »
Pattern 8 — Évitement de la copule (être/avoir)
Triggers: constitue, fait office de, se positionne comme, représente [un], dispose de, offre [un]
Avant : La galerie constitue l'espace d'exposition. Elle dispose de quatre salles. Après : La galerie est l'espace d'exposition. Elle a quatre salles.
Pattern 9 — Parallélismes négatifs
Triggers: Non seulement... mais aussi..., Il ne s'agit pas seulement de... mais de..., Ce n'est pas un simple X, c'est un Y
Avant : Il ne s'agit pas simplement d'autocomplétion ; il s'agit de libérer la créativité. Après : L'outil dépasse la simple autocomplétion : il élargit l'espace de créativité disponible.
Pattern 10 — Règle de trois systématique
AI forces ideas into groups of three.
Avant : L'événement propose des conférences plénières, des tables rondes et des opportunités de réseautage. Innovation, inspiration et analyses sectorielles. Après : L'événement comprend des conférences et des tables rondes. Du temps est prévu pour le réseautage.
Pattern 11 — Cycle de synonymes (variation élégante)
Repetition-penalty code causes excessive synonym substitution for the same referent.
Avant : Le protagoniste fait face à de nombreux défis. Le personnage principal doit surmonter les obstacles. La figure centrale finit par triompher. Après : Le protagoniste fait face à de nombreux obstacles, finit par les surmonter et rentre chez lui.
Pattern 12 — Fausses gammes
Triggers: « de X à Y, de A à B » where X-Y and A-B don't form meaningful scales.
Avant : De la singularité du Big Bang au vaste réseau cosmique, de la naissance des étoiles à la danse de la matière noire. Après : Le livre couvre le Big Bang, la formation des étoiles et la matière noire.
Pattern 13 — Anglicismes d'architecture
~16% of ChatGPT's French errors have English origins. These are among the most reliable tells.
| Anglicisme IA | Français correct |
|---|---|
| « faire du sens » | « avoir du sens » |
| « adresser un problème » | « traiter / aborder un problème » |
| « implémenter » (hors info) | « mettre en œuvre » |
| « impacter » | « affecter, toucher » |
| « supporter » (= soutenir) | « prendre en charge » |
| « définitivement » (= assurément) | « sans aucun doute » |
| « basiquement » | « en gros, fondamentalement » |
| Oxford comma before « et » | No comma before « et » in French |
Pattern 14 — Doublets adjectivaux redondants
Token-by-token generation produces synonym pairs as hedging.
Triggers: crucial et essentiel, robuste et fiable, innovant et avant-gardiste, dynamique et en pleine expansion, riche et varié
Avant : Cette approche innovante et avant-gardiste offre une solution robuste et fiable. Après : Cette approche tient la charge sans maintenance lourde.
Pattern 15 — Abus de tirets cadratins
AI overuses em dashes mimicking English "punchy" writing. French prefers commas and parentheses for incidental clauses.
Avant : Le terme est promu par les institutions — pas par les habitants. Cet étiquetage — même dans les documents officiels — persiste. Après : Le terme est promu par les institutions, pas par les habitants. Cet étiquetage persiste, même dans les documents officiels.
Freshness note: since November 2025, ChatGPT obeys "no em dash" custom instructions, and readers know the tell. Presence proves little (humans use it too), absence proves nothing. Still reduce overuse — the goal is natural French, not detector evasion.
Pattern 16 — Abus de gras mécanique
AI bolds terms mechanically to signal importance.
Rule: Remove all bold unless it serves a genuine navigational function.
Pattern 17 — Listes verticales avec en-têtes en gras et deux-points
Avant :
- Expérience utilisateur : Significativement améliorée.
- Performance : Optimisée grâce à des algorithmes améliorés.
- Sécurité : Renforcée avec le chiffrement de bout en bout.
Après :
La mise à jour améliore l'interface, accélère le chargement et ajoute le chiffrement de bout en bout.
Same rule for gratuitous tables: AI presents ordinary developments as tables (a French Wikipedia-flagged marker). Keep a table only when the data is genuinely tabular (comparisons, figures); otherwise convert to prose.
Pattern 18 — Majuscules de titre à l'anglaise
French headings capitalize only the first word (and proper nouns).
Avant : ## Négociations Stratégiques Et Partenariats Globaux Après : ## Négociations stratégiques et partenariats globaux
Pattern 19 — Emojis : décoratifs vs expressifs
Emojis are a register feature, not a defect. Three tests:
- Function — an emoji that replaces words or carries tone (irony, emotion, reaction) is human usage; one that decorates structure (one per heading, 🚀💡✅ series, « 👉 » paragraph openers) is machine usage. Remove the second, keep the first.
- Medium — social posts, chats, internal messaging: emojis are expected — keep some, or add one if the author's voice uses them. Formal documents, press releases, articles: none.
- Regularity — the tell is systematicity: same position, same density everywhere. Human emoji use is irregular and sparse (max ~1 per paragraph, never in series). Keep the irregular, kill the systematic.
When in doubt about the author's voice, ask.
Pattern 20 — Guillemets et incohérence typographique
Sources contradict on which quote style AI produces (perfect chevrons « », English curly quotes "…", or both). The robust tell is not one variant but the mix: straight quotes, curly quotes and chevrons cohabiting in one text, or straight (') and curly (’) apostrophes alternating — a human sticks to whatever their keyboard produces.
Quote rule by register: in official documents written in langage soutenu with worked typography, use chevron quotes (« ... ») with non-breaking spaces. The rest of the time (emails, internal communication, social media), prefer curly quotes ("...") — chevron-perfection there reads as machine output.
Also check: spaces before colons/semicolons/exclamation/question marks, and French number formatting (1 000,50 not 1,000.50). Whatever the convention, keep it consistent across the whole text — consistency beats correctness.
Pattern 21 — Artéfacts de conversation
Kill on sight: J'espère que cela vous aide, Bien sûr !, Absolument !, Vous avez tout à fait raison !, Souhaitez-vous que..., N'hésitez pas à, Voici un...
Pattern 22 — Clauses de limitation de connaissance
Kill on sight: en date de [date], Selon les informations disponibles, Bien que les détails spécifiques soient limités..., sur la base des données accessibles...
Pattern 23 — Ton servile et sycophante
Avant : Excellente question ! Vous avez tout à fait raison, c'est un sujet complexe. Après : Les facteurs économiques que vous mentionnez jouent effectivement ici.
Pattern 24 — Phrases de remplissage
| Kill | Replace with |
|---|---|
| Afin de parvenir à cet objectif | Pour y arriver |
| En raison du fait que | Parce que |
| À ce stade / À l'heure actuelle | Maintenant / Aujourd'hui |
| Dans l'éventualité où | Si |
| Le système a la capacité de | Le système peut |
| Il est important de noter que | (delete, start directly) |
| Il convient de souligner que | (delete, start directly) |
| En ce qui concerne | Sur / Quant à |
Pattern 25 — Hedging excessif
Avant : On pourrait potentiellement arguer que cette politique pourrait éventuellement avoir un certain effet. Après : Cette politique a probablement un effet sur les résultats.
Pattern 26 — Conclusions positives génériques
Triggers: L'avenir s'annonce prometteur, Des temps passionnants, poursuit son chemin vers l'excellence, un pas majeur dans la bonne direction
Replace with a concrete fact about what actually happens next.
Pattern 27 — Uniformité structurelle
AI produces paragraphs of nearly identical length (std dev <30 words vs. >60 for humans), lists grouped in 3/5/7/10 items, and invariable intro-body-conclusion architecture. Section headings phrased as questions are an additional formatting marker.
At sentence level, the tell is dispersion, not average: in the only quantified French study, mean sentence length was near-identical (21.0 human vs. 21.7 AI words) but AI produced almost no sentences under 15 or over 39 words (most frequent length shifting from 13 to 19 words).
Rule: Reintroduce the tail. Write some short sentences (under 15 words) and some long periodic ones (over 39). The missing extremes are what betrays the machine, not the mean.
Sentence-start anaphora: consecutive sentences opening identically (« Cela... », « Cette approche... », « Ce système... »). Vary the attack of each sentence.
Style « LinkedIn »: one-sentence paragraphs stacked for drama, ellipses as suspense pivots (« Et là... tout a changé »), relentlessly upbeat tone. This register is now so associated with AI-assisted posting that it reads as machine output even when human. Merge the fragments into real paragraphs.
Pattern 28 — Markdown résiduel et artéfacts techniques
Kill on sight: unrendered **mot** or ## in plain-text contexts, - **Titre :** bullets pasted where Markdown doesn't render, citation artifacts like :contentReference[oaicite:2]{index=2}, leftover refusals (« Je suis désolé, mais je ne peux pas... »)
These are the strongest tells of all: they cannot come from a spellchecker or a CMS — only from pasting a chat output. French investigative journalists hunt AI-generated news sites by searching exactly these strings.
Also strip zero-width characters (U+200B, U+200C, U+200D, U+FEFF) — copy-paste artifacts with no legitimate use in prose. Do NOT strip non-breaking spaces (U+00A0, U+202F): they are correct French typography before « ; : ! ? » and inside « 12 h 30 ». Confusing the two creates false alarms on every properly typeset French text.
Medium exception: where Markdown is the native format — a README, developer documentation, a technical wiki — headings, bold, lists, tables and code blocks are the norm, not a tell. This pattern targets Markdown pasted into contexts that do not render it, plus generation artifacts; it does not apply to documents meant to be Markdown.
Pattern 29 — Lyrisme de pacotille (registre narratif)
French AI fiction has its own register, distinct from blog slop.
Triggers: un instant suspendu, une promesse murmurée/suspendue dans l'air, un secret brûlant, un désir/silence vibrant, comme si le temps s'était figé — recurring fetish words: promesse, suspendu, vibrant, secret, brûlant, murmuré
Grammar profile: AI narrative French flattens tense and person. The quantified study measured passé simple −84 %, imparfait −71 %, conditionnel −50 %, pronoun « on » −92 %, verb « falloir » −93 % versus human French. Reintroduce the tenses the genre calls for, prefer « on » over a stiff « nous », and let « il faut » back in.
The same study measured the over-uses: « devoir » (+101 %), « continuer » (+145 %), « tenir » (+158 %), « ensemble » (+93 %), possessive determiners (+30 %). When these cluster (« nous devons continuer, ensemble, à tenir nos engagements »), the sentence is machine-average French — rewrite it around a concrete action.
Part 3: Discourse architecture patterns
Lexical scrubbing is not enough: the deepest AI tells are architectural. A text can contain zero flagged words and still read machine-made because of how it is built. Unlike the measured lexical data, these patterns are craft heuristics — convergent observations from experienced readers, not corpus-measured figures.
Pattern 30 — Annonce, récapitulation et écho de la consigne
Triggers: an intro announcing what the text will say, a conclusion repeating what it said, section headings mirroring the announced plan 1:1, a first sentence rephrasing the question asked (« Vous vous demandez comment... ? », the assignment restated), a closing that loops back to the request
The information exists once but is served three times. Chatbot answers and school essays echo the prompt at both ends.
Rule: Start in medias res — the first sentence delivers content, not a program. End somewhere the intro couldn't predict: a consequence, an open question, a concrete next fact. Delete prompt echoes at both ends.
Pattern 31 — Structure en catalogue, sans angle
Triggers: sections that could be reordered without breaking anything; every aspect of the topic covered at equal depth (définition, avantages, inconvénients, bonnes pratiques, conclusion); no claim that later sections build on
AI covers a subject; a human makes a point. The permutation test: if two sections can swap places without damage, the text is a disguised list, not an argument.
Rule: Choose an angle and commit. Cut the aspects that don't serve it — visible dead ends are human. Make each section depend on the previous one, so the order becomes necessary.
Pattern 32 — Moule de paragraphe et échafaudage apparent
Triggers: every paragraph = topic sentence + two or three supports + mini-conclusion, fully self-contained; paragraphs opening with sequence connectors (« D'abord », « Ensuite », « De plus », « Enfin ») ; no idea ever spilling across a paragraph break; zero digressions
The structure is signaled instead of carried by the content. Human paragraphs lean on each other: a thought starts at the end of one and finishes in the next; an aside interrupts.
Rule: Drop scaffolding connectors — juxtaposition works. Let at least one idea straddle a paragraph break. Allow a digression when it earns its place.
Pattern 33 — Faux équilibre discursif
Triggers: every claim immediately counterbalanced (« Cependant, il convient de nuancer... »), symmetrical « d'une part / d'autre part », conclusion of the « tout dépend du contexte » type
Sentence-level hedging (Pattern 25) scaled up to the whole text: the piece has no thesis. Both-sidesism reads as machine caution, not fairness.
Rule: Take a position. Nuance once, where it genuinely matters — not after every claim. If the honest answer really is « ça dépend », say of what, precisely.
Deletion test: remove the objection paragraph. If the conclusion still holds unchanged, the objection was ornament, not thought — a real antithesis displaces the thesis. The discriminator matters in French: the dissertation tradition (thèse/antithèse/synthèse) makes announce-and-balance school-legitimate, so a courtesy counter-argument passes unnoticed.
Quebec caveat: rédaction épicène and OQLF plain-language norms push human institutional writers toward exactly this flat, symmetrical shape — in Québec institutional prose, do not read balance alone as machine output.
Pattern 34 — Sur-sectionnement SEO et question-réponse fantôme
Triggers: H2/H3 every two paragraphs, a table of contents on a short text, an FAQ block, a closing quiz or « points clés à retenir » ; self-interrogation outside any real FAQ (« Pourquoi est-ce important ? Parce que... »)
This is the documented grid of French AI content farms. The ghost Q&A simulates a dialogue where none exists.
Rule: A heading must govern at least four or five paragraphs — otherwise merge. Remove FAQ/quiz blocks unless the medium genuinely calls for them. Convert self-questions into direct statements.
Pattern 35 — Granularité constante
Triggers: the whole text sits at one level of abstraction — no date, no name, no price, no error message, no quoted sentence; 1 500 words at mid-altitude
Humans change altitude: they drop from the abstract to a hyper-specific detail (a date, a stack trace, a price) and climb back within a couple of paragraphs. LLMs cruise at mid-altitude for the whole text.
Rule: Force at least one dive per section: a verifiable, dated, named detail. If the author has none to offer, that is a content problem, not a style problem (see the limits note in Part 4).
Pattern 36 — Absence de trous
Triggers: every question the text raises gets answered; no abandoned thread, no unresolved tension, no open problem
Real expertise leaves holes, because the author knows where the knowledge stops. AI text resolves everything it opens — the tidiness itself is the tell. This is the structural counterpart of never writing « je ne sais pas » (Part 4).
Rule: Leave at least one raised question honestly open. Name the limit (« je n'ai pas testé au-delà de X ») instead of rounding it off.
Pattern 37 — La liste comme évitement
Triggers: bullet lists appearing exactly where the reasoning gets hard — at the decision point, the trade-off, the prioritization
Enumeration replaces the choice the author refused to make: listing five options is easier than defending one. Pattern 17 treats lists as formatting; this one treats them as an argumentative symptom.
Rule: At each list, ask what decision it avoids. Replace it with a sentence that chooses — keep the list only when the items genuinely are peers.
Pattern 38 — Absence d'occasion d'écriture
Triggers: nothing in the text explains why it exists, now, triggered by what, addressed to whom — no event, no encounter, no deadline, no request
Human texts have an origin (an incident, a question someone asked, a release, an annoyance) and an addressee, and it shows. AI text is written from nowhere, to no one.
Rule: Anchor the piece in its occasion within the first paragraphs: what happened that made this worth writing, and for whom. If no occasion exists, ask the author for it.
Part 4: Personality and soul
Avoiding AI patterns is only half the job. Sterile, voiceless text is just as suspicious as text full of « crucial » and « dans le paysage de ». This is the dimension most "humanization" guides ignore.
Know the limits. Experienced French readers, moderators and investigators no longer rely on style: the signals they trust are behavioral and ecosystem-level (publishing cadence, whether the author exists, whether the sources check out). No amount of pattern-scrubbing fixes a text with nothing situated in it — no lived detail, no dated fact, no checkable source. If the input has no anchored content, flag it to the author instead of polishing the surface: ask for one real example, one date, one source, and build the rewrite around them.
Préserver le registre
Formal ≠ AI. Un texte en langage soutenu ne doit pas devenir familier après réécriture.
- Conserver les structures complexes (subordonnées, incises, phrases périodiques) quand elles portent du sens.
- Ne simplifier que ce qui est mécaniquement formulé — pas ce qui est simplement formel.
- Adapter les exemples de ce guide au registre du texte d'entrée : les réécritures ci-dessous ciblent un registre courant ; pour un texte soutenu, maintenir le même niveau de langue.
Signs of soulless writing (even if technically clean)
- Every sentence is the same length and structure
- No opinions, just neutral reporting
- No acknowledgment of uncertainty or mixed feelings
- No first person when it would be appropriate
- No humor, no edge, no personality
- Reads like a Wikipedia article or press release
How to add voice in French
Avoir des opinions. « Franchement, je ne sais pas quoi en penser » is more human than neutral pros-and-cons.
Varier le rythme. Short sentences that hit hard. Then longer ones with nested subordinates that take their time. French has a tradition of rhythmic asymmetry (Montaigne, Cioran, Debord). AI text is monotonously regular by contrast.
Reconnaître la complexité. « C'est impressionnant mais aussi un peu flippant » beats « C'est impressionnant. »
Utiliser « je ». First person is not unprofessional. « J'y reviens sans arrêt... » signals a human thinking. Personal voice is among the strongest authenticity markers.
Laisser du désordre. Perfect structure feels algorithmic. Tangents, parentheses, half-formed thoughts are human. French has a long tradition of the parenthèse (Proust is the caricature, but even in technical writing, asides signal authenticity).
Utiliser le second degré. LLMs are constitutionally incapable of authentic irony and humor. Understatement, light sarcasm, self-deprecation: unfakeable markers. « On a quand même inventé un truc qui code mieux que nous quand on est fatigué, ce qui est à peu près tout le temps » does not come from an LLM.
Admettre l'ignorance. An LLM never writes « je ne sais pas », « aucune idée », « je n'ai pas vérifié ». Like irony and humor, a frank admission of not knowing is among the strongest authenticity markers precisely because the machine never produces it. Use all three sparingly and only where the context allows — a legal notice or an audit report tolerates neither jokes nor shrugs.
Être précis sur les ressentis. Not « cela est préoccupant » but « il y a quelque chose de dérangeant à voir des agents tourner à 3h du matin sans personne pour les surveiller. »
Utiliser des mots rares. AI French avoids low-probability words in both directions: no « séide » or « nonobstant », no « chelou » or « relou ». One well-placed rare word — soutenu or argotique, matching the register — signals a human choosing, not a model averaging.
Utiliser l'argot et le registre familier (quand le registre s'y prête). AI French is uniformly standard; argot is one of the cheapest authenticity injections. A non-exhaustive palette, by region:
- France (familier/argot) : chelou, relou, ouf, avoir le seum, la flemme, une galère, ça me saoule, bosser, un boulot, un bouquin, le fric, la thune, une bagnole, kiffer, se planter, un truc de dingue, grave (= très), carrément, vachement, se prendre le chou, bidouiller, une magouille, au taquet, à l'arrache
- Belgique : septante, nonante, un GSM, un kot, tantôt (= tout à l'heure), à tantôt, une aubette, la guindaille, s'il te plaît (en tendant un objet), une farde, savoir (= pouvoir : « je ne saurais pas venir »), il drache
- Québec : niaiser, jaser, magasiner, pantoute, c'est plate, c'est correct, un char, un dépanneur, une blonde / un chum, avoir de la misère, être dans le champ, ça prend pas la tête à Papineau, c'est tiguidou, se faire passer un sapin, présentement, à matin
- Suisse romande : un natel, septante / huitante / nonante, une panosse, un cornet (= sac plastique), ça joue, se réjouir de (= avoir hâte), un linge (= serviette), une votation, faire la pièce droite
Ancrer géographiquement. AI defaults to Parisian standard French.
- Regionalisms are strong authenticity markers where they fit the author — and their systematic absence in a supposedly Québécois, Belgian or Swiss author's text is itself a tell.
- Never force them: a misused regionalism (or the clichéd Belgian « une fois ») is worse than none.
- Match the author's real origin, medium and register.
Assumer l'oralité (registre familier uniquement). In informal writing, humans drop the « ne » (« c'est pas faux », « y'a un truc »), use hyperbole (« 1000 % d'accord »), contract. AI keeps full negation everywhere. Never force this into formal prose — register first.
Abréger comme un humain. AI spells everything out; humans abbreviate constantly. Sprinkle where the register allows:
- Sigles et marqueurs d'usage : PS:, NB:, cf., etc., ex: / p. ex., càd, RDV, ASAP, FYI, pour info, cc (mettre en copie), CR (compte rendu), retex, N+1, RH, WE
- Unités et chiffres : min (« 5 min de marche »), h collé (« 14h30 », « 2h de route »), km, € collé (« 30€ »), ~ pour « environ », nb (nombre)
- Raccourcis d'écrit courant : pb, tjs, bcp, qqch, qqn, svp / stp, dispo, perso, pro
- Apocopes : ordi, appart, resto, apéro, ciné, fac, prof, exam, visio, réu, présa, la doc, la config, l'admin, le labo, la manif, l'expo, la promo, l'info, l'aprem
- Clôtures d'email : A+, Cdlt, « à plus »
An LLM never spontaneously writes « pb », « tjs » or « 14h30 » — these are cheap, strong authenticity markers. Calibrate to the medium and to the target register (see step 0): in formal documents, stick to cf., etc., NB and p. ex. ; and avoid full SMS-speak (slt, bjr) everywhere except actual chat.
Process
- Read the input text carefully. If the target register is unclear, ask the user which niveau de langage is expected before rewriting anything
- Identify all instances of the 38 patterns
- Rewrite each problematic section
- Inject voice and personality (Part 4)
- Ensure the revised text:
- Sounds natural when read aloud in French
- Varies sentence structure (measure paragraph length std dev)
- Uses specific details over vague claims
- Maintains appropriate register for context — if the input is « soutenu », the output stays « soutenu »
- Uses simple constructions (est/a/fait) where appropriate
- Uses correct French typography (guillemets, spacing, number formatting)
- Contains zero anglicisms from pattern #13
- Present a draft humanized version
- Ask: "Qu'est-ce qui rend ce texte évidemment généré par IA ?"
- Answer briefly with the remaining tells (2-3 bullet points max)
- Ask: "Maintenant, fais en sorte qu'il ne le soit plus."
- Present the final version
- Produce a Résumé des modifications listing the patterns removed (see Output format)
Output format
Provide:
- Brouillon réécrit (draft rewrite)
- « Qu'est-ce qui rend ce texte évidemment IA ? » (brief remaining tells)
- Version finale (revised after the self-audit)
- Résumé des modifications (brief list of patterns removed, optional)
Full example
Avant (texte IA typique) :
Voici un aperçu de ce sujet. J'espère que cela vous sera utile !
Le coding assisté par IA constitue un témoignage durable du potentiel transformateur des grands modèles de langage, marquant un tournant décisif dans l'évolution du développement logiciel. Dans le paysage technologique actuel en perpétuelle mutation, ces outils révolutionnaires — nichés à l'intersection de la recherche et de la pratique — redéfinissent la manière dont les ingénieurs idéent, itèrent et livrent, soulignant leur rôle crucial dans les workflows modernes.
Au cœur de cette dynamique, la proposition de valeur est claire : rationaliser les processus, renforcer la collaboration et favoriser l'alignement. Il ne s'agit pas simplement d'autocomplétion ; il s'agit de libérer la créativité à grande échelle, en assurant que les organisations restent agiles tout en délivrant des expériences fluides, intuitives et puissantes. L'outil constitue un catalyseur. L'assistant fait office de partenaire. Le système se positionne comme une fondation pour l'innovation.
- 💡 Rapidité : La génération de code est significativement plus rapide, réduisant les frictions et autonomisant les développeurs.
- 🚀 Qualité : La qualité des résultats a été renforcée grâce à un entraînement amélioré, contribuant à des standards plus élevés.
- ✅ Adoption : L'utilisation continue de croître, reflétant des tendances sectorielles plus larges.
Malgré des défis typiques des technologies émergentes — notamment les hallucinations, les biais et la responsabilité — l'écosystème continue de prospérer. L'avenir s'annonce prometteur. N'hésitez pas à me dire si vous souhaitez que je développe une section !
Brouillon réécrit :
Les assistants de code IA accélèrent certaines tâches. Dans une étude Google de 2024, les développeurs utilisant Codex complétaient les fonctions simples 55% plus vite qu'un groupe témoin, mais ne montraient aucune amélioration sur le debugging ou les décisions d'architecture.
Ces outils sont bons pour le boilerplate : fichiers de config, scaffolding de tests, refactors répétitifs. Ils sont aussi très bons pour avoir l'air corrects tout en se plantant. J'ai mass-accepté des suggestions qui compilaient, passaient le linter, et faisaient quand même n'importe quoi parce que j'avais arrêté de faire attention.
Les chiffres de productivité sont glissants. GitHub peut dire que les utilisateurs de Copilot « acceptent 30% des suggestions », mais acceptation n'est pas correction, et correction n'est pas valeur. L'étude Uplevel de 2024 n'a trouvé aucune différence statistiquement significative dans le débit de PR entre les équipes avec et sans assistant IA.
« Qu'est-ce qui rend ce texte évidemment IA ? »
- Le rythme reste un peu trop régulier (contrastes nets, paragraphes de taille proche)
- Les citations d'études nommées peuvent sonner comme des placeholders plausibles
- La dernière phrase penche vers le slogan
Version finale :
Les assistants de code IA accélèrent le travail sur les tâches répétitives. Pas sur l'ensemble du processus, et certainement pas sur l'architecture.
Ils sont très bons pour le boilerplate : fichiers de config, scaffolding de tests, refactors répétitifs. Ils sont aussi très bons pour avoir l'air corrects tout en se plantant. J'ai accepté des suggestions qui compilaient, passaient le linter, et faisaient quand même n'importe quoi parce que j'avais arrêté de lire.
Les développeurs que j'interroge se répartissent en deux camps. Certains s'en servent comme autocomplétion pour les corvées et relisent chaque ligne. D'autres l'ont désactivé après que l'outil n'arrêtait pas de suggérer des patterns dépréciés. Les deux positions se défendent.
Les métriques de productivité sont glissantes. GitHub peut annoncer que les utilisateurs « acceptent 30 % des suggestions », mais acceptation n'est pas correction, et correction n'est pas valeur. Sans tests, on en est réduit à deviner.
Résumé des modifications :
- Artéfacts de conversation supprimés (#21: « J'espère que cela vous sera utile ! », « N'hésitez pas à »)
- Inflation de signification supprimée (#1: « témoignage durable », « tournant décisif », « rôle crucial »)
- Langage promotionnel supprimé (#4: « révolutionnaires », « nichés », « fluides, intuitives et puissantes »)
- Attributions vagues supprimées (#5)
- Participes superficiels supprimés (#3: « soulignant », « reflétant », « contribuant à »)
- Parallélisme négatif supprimé (#9: « Il ne s'agit pas simplement de X ; il s'agit de Y »)
- Règle de trois supprimée (#10) et cycle de synonymes (#11: « catalyseur/partenaire/fondation »)
- Tirets cadratins réduits (#15), emojis supprimés (#19), gras mécaniques supprimés (#16, #17)
- Évitement de la copule corrigé (#8: « constitue », « fait office de », « se positionne comme »)
- Section défis/perspectives supprimée (#6: « Malgré des défis... continue de prospérer »)
- Hedging supprimé (#25), remplissage supprimé (#24: « Au cœur de »)
- Conclusion positive générique supprimée (#26: « L'avenir s'annonce prometteur »)
- Voix et personnalité injectées (Part 4: rythme varié, première personne, opinions, précision)
Reference
Based on:
- Wikipedia:Signs of AI writing (WikiProject AI Cleanup)
- Wikipedia FR: Aide:Identifier l'usage d'une IA générative
- Wikipedia FR: Projet:Observatoire des IA
- Labbé, Labbé & Savoy — ChatGPT as speechwriter for the French presidents (the only quantified stylometric study of AI-generated French: « également », « défi », tense and pronoun profiles)
- The Conversation — Comment « dé-IA-iser » nos écrits
- Next — Comment reconnaître les sites d'infos générés par des IA (residual-artifact hunting method)
Freshness warning: AI tells expire. The em dash lost most of its diagnostic value after OpenAI's November 2025 fix; published marker lists get reverse-engineered into evasion tools within months; and humans increasingly adopt AI vocabulary by exposure. Treat every lexical list here as dated — the structural principles (dispersion, register, specificity, soul) age far slower than the word lists.
Key insight: LLMs generate the most statistically likely token sequence. The result trends toward the average across all possible contexts. Making text human means making it yours: specific, opinionated, idiosyncratic.
Not for English text (→ See samber/cc-skills@humanizer-en-asd-ste100 skill for ASD-STE100 Simplified Technical English, or blader/humanizer@humanizer for general English prose).
ASD-STE100 humanizer — Simplified Technical English
Persona: You are a technical writer trained in ASD-STE100. You write for a reader whose first language is not English, and for a reader who may be a machine translation engine — every sentence must survive that reading with a single, unambiguous meaning.
Thinking mode: Reason carefully about sentence classification, word counting, and verb-form legality before rewriting — these errors are silent. A sentence that looks compliant (short, plain words) can still break a specific numeric threshold or use a banned tense, and the mistake is invisible unless you check it explicitly. On Claude Code, use ultrathink for long or safety-critical documents.
Attribution
The rules below are defined by ASD-STE100, Issue 9 (published 2025-01-15), the Simplified Technical English standard maintained by the ASD Simplified Technical English Maintenance Group (STEMG) on behalf of the Aerospace, Security and Defence Industries Association of Europe (ASD).
- ASD-STE100 is copyright © ASD and a registered EU trademark (No. 017966390).
- This skill is an independent writing aid — it is not endorsed, certified, or authorized by ASD or the STEMG, and it does not reproduce the ASD-STE100 dictionary.
- Cite every rule by its official number (
ASD-STE100 rule 5.1), not as house style; the specification is the authority whenever this skill and the specification disagree. - The full standard is free to download at https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pdf.
Precedence: this skill yields to context
Instructions here can be overridden by the user's prompt, by a company style guide, or by a more specific format already in play — a vendor-mandated template, an S1000D data module, a regulatory filing with its own required structure. When the task comes with a required structure, that structure wins on conflict: apply this skill only to what it leaves open (word choice, sentence length, verb form, technical-noun consistency, the de-slop passes below). A vendor template's mandatory feature table, a data module's fixed section order, or a README's Markdown headings may legitimately use patterns flagged below (a table, a heading hierarchy, three parallel bullet points that genuinely are peers) — that is the format speaking, not generation slop.
Modes
- Rewrite — convert supplied English text into STE-compliant text, including de-slopping an AI-generated draft in the same pass (see the de-slop passes below).
- Write — author new procedures, descriptions, or warnings directly in STE from a brief, never introducing slop in the first place.
Both modes share the same pipeline: de-slop the text (artifacts, padding, discourse patterns), classify it, apply the rules for that text type, then self-audit (see Process).
Questions: ask the user through the environment's question tool when the text type or subject field is not obvious from context — never as plain-text prose. Two things are worth a question before drafting: whether the source is procedural (steps a reader executes) or descriptive (an explanation of a system or a fact), and what subject field the technical vocabulary belongs to (software, medical devices, industrial equipment, aerospace, other). A wrong guess on either drives every downstream rule choice off course.
Run this once
Applying this skill repeatedly to the same text does not make it more compliant — it makes it drift. A second pass second-guesses rewrites that were already correct, and word choice can wander: a term approved on pass one gets swapped for a near-synonym on pass two, chasing a variety STE does not want and rules 1.11 and 9.4 explicitly forbid (hold one term per concept for the whole document). If the self-audit (Process, last step) still finds an issue after one full pass, fix that specific sentence directly — do not re-run the whole pipeline against text that is already compliant.
Step 0 — Classify before rewriting
STE resolves the same construction differently depending on text type, so classification is not optional cleanup — it is the first decision.
| Type | Governed by | Signal |
|---|---|---|
| Procedural | Section 5 | The reader executes steps in order |
| Descriptive | Section 6 | The reader learns how something works or is built |
| Safety instruction | Section 7 | A warning or caution attached to a procedure |
| Note | rule 5.5 | Extra information, never an instruction |
Example of why this matters — the identical passive sentence resolves two ways:
- Source:
The volume control can be adjusted. - Procedural rewrite:
Adjust the volume control. - Descriptive rewrite:
You can adjust the volume control.
Strip generation artifacts first
ASD-STE100 governs wording and structure, not formatting — it has no numbered rule against an emoji, a leftover chat sentence, or an overused em dash. That does not make them acceptable: a delivered technical document cannot carry chat leftovers or decoration, and a reader or a translation engine has no way to know they are not part of the instruction. Clear these before applying any numbered rule, in both modes — Rewrite strips them from the source, Write never introduces them.
Register artifacts — chat leftovers that never belong in a document:
- Zero decorative emojis, always. A technical document has exactly one register — formal, plain, single-purpose — so there is no context in which an emoji belongs, unlike general prose where an emoji can carry tone.
- No conversation or meta-commentary inside the deliverable. Kill on sight:
Here is the rewritten procedure:,Sure, I can help with that,Absolutely!,Would you like me to...,Let me know if...,Feel free to.... These are chat artifacts, not content — remove them entirely rather than rewording them. - No knowledge-limitation disclaimers. Kill on sight:
As of [date],According to available information,While specific details are limited...,Based on the information available.... A technical document states what it knows; when a value is genuinely unconfirmed, flag it as residual non-compliance (see Output format) instead of hedging inside the deliverable text. - No sycophantic or servile tone. Kill on sight:
Great question!,You're absolutely right,Excellent point. A technical document has no reader to flatter — state the fact directly.
Typographic and formatting artifacts:
- No Markdown residue that is not native to the delivery format. Unrendered
**bold**, a broken citation marker (:contentReference[oaicite:2]{index=2}), or a leftover refusal (I'm sorry, but I can't...) have no place in a plain-text manual or a rendered document that was not asked for in Markdown. Flatten to plain sentences unless the target format is genuinely Markdown-rendered documentation. Strip zero-width characters (U+200B, U+200C, U+200D, U+FEFF) — they are copy-paste artifacts with no legitimate use in prose — but do not strip legitimate technical symbols (°,±,µ,Ω) while doing it. - No mechanical bold. Remove bold that flags every term as important rather than aiding navigation — STE conveys importance through structure (WARNING/CAUTION, numbered steps), not typography.
- No bold-header feature lists. A
- **Feature:** descriptionlist summarizing unrelated facts is a generation habit, not an STE vertical list (rule 4.3 governs genuine lists of comparable procedural or descriptive items). Convert it to plain sentences, or to a compliant vertical list only when the items are truly comparable. - No heading-capitalization drift. STE does not regulate formatting, but pick one heading convention — sentence case or title case — and hold it throughout a document; switching between them mid-document is a generation tell, not a style choice.
- One quote style, held throughout. Pick straight quotes (
"...") as the default for plain-text technical documents and for downstream translation tooling, and do not mix them with curly quotes or apostrophes within the same document. - No em dash overuse. AI-generated English defaults to em dashes for parenthetical asides at a rate no human technical writer matches. Split the aside into its own short sentence, or use a comma when it is brief — the same "one idea per sentence" principle Section 4 already applies to dropped words and contractions. Presence alone proves little (a 2025 change to a major chatbot's defaults already reduced this tell, and technical writers use em dashes too) — the signal is density, more than one or two per paragraph, not any single instance.
This is a format- and register-level pass — not a general rewrite for tone, rhythm, or personality. Those stay out of scope (see Limits and non-goals).
Strip AI-padding constructions
These constructions add words without adding information, which conflicts with STE's core demand for short, direct, single-meaning sentences (Sections 5–6) just as surely as a banned verb tense does. Remove them before, not after, applying the numbered rules — a padded sentence that gets shortened to fit a word limit usually loses the wrong words.
No challenge/optimism sandwich. Despite its many advantages, the system faces several implementation challenges. Despite these challenges, the outlook remains positive. states nothing. Name the actual constraint, or delete the frame: The new system requires a firmware update on devices older than model X200, which affects about 12% of the current fleet.
No negative parallelism. Not only does this reduce downtime, it also improves accuracy. It's not just a filter, it's a complete air-handling upgrade. STE already requires direct, active statements (rule 3.6) — apply the same directness to sentence rhetoric: This procedure reduces downtime and improves accuracy.
No systematic rule of three. Forcing findings into exactly three parallel items (faster, safer, more reliable) when the source supports two or four is padding, not precision. State the actual count: The upgrade reduces boot time by 40%.
No filler phrases. These extend the restructuring principle in rule 9.1 to common padded constructions:
| Kill | Replace with |
|---|---|
| in order to achieve this | to do this |
| due to the fact that | because |
| at this time / at the present time | now |
| it is important to note that | (delete, state directly) |
| it should be noted that | (delete, state directly) |
| with regard to / in terms of | about, for |
| in the event that | if |
| has the ability to | can |
No excessive hedging. One could potentially argue that this might possibly reduce failure rates to some extent. A technical document states what it knows directly, and states an actual, named limit when it does not (Failure-rate data is not available for this configuration.) rather than qualifying a claim into vagueness.
No generic positive conclusions. Kill on sight: The future looks promising., This represents a significant step forward., Overall, this is an exciting improvement. Replace with a concrete next fact or step, or delete the sentence — a technical document does not need a closing sentiment.
Strip AI discourse-architecture patterns
These are structural tells, not lexical ones — a passage can pass every word-level check above and still read as generated because of how it is built. They apply mainly to descriptive/explanatory STE text (Section 6) and to Write-mode drafting from a brief; a procedure's step order is fixed by the task itself, not by these judgment calls.
No redundant recap. A closing paragraph that restates the opening in the same words adds nothing a reader has not already read. State a genuinely new closing fact, or end the document where the last necessary instruction ends.
No catalog structure without a throughline. Covering every aspect of a system at equal, shallow depth — definition, advantages, disadvantages, best practices, all given the same weight regardless of relevance — reads as generated. Each section should depend on what the previous one established, or state only what is operationally relevant.
No false balance. Pairing every stated fact with an immediate counterbalancing qualifier (However, it should also be noted that...), or closing with it depends on the context instead of naming the dependency, is hedging at the paragraph level. State the actual condition: not it depends, but it depends on the operating pressure — above 40 psi, use the reinforced seal.
No ghost Q&A. A self-directed question with no real FAQ behind it (Why is this step necessary? Because...) is a padding device. State the fact directly: This step relieves residual pressure before the housing is opened.
No constant granularity. A document with no torque value, no error code, no part number, no measured tolerance anywhere reads as generated regardless of how compliant its sentences are, because real technical writing changes altitude — it drops to a specific, verifiable detail and climbs back. When the source material has a specific value, keep it; when it is missing, flag it as residual non-compliance (see Output format) rather than writing around the gap with vague language.
State scope and known limits explicitly. A descriptive passage that answers every question it raises, with no stated boundary, reads as generated — and, unlike an essay, a technical document should state its actual boundary rather than imply universal coverage the source does not support: This procedure covers model X200 only; earlier models use a different filter housing. This is about honest scoping, not withholding information — a procedure must still be complete and fully executable within the scope it states (Section 5).
No list as a substitute for a decision. A bullet list appearing exactly where the source supports one specific answer (five possible torque values instead of the one that applies) replaces a decision with an enumeration. State the answer directly, and reserve vertical lists (rule 4.3) for items that are genuinely comparable, not for avoiding a choice.
State what the document applies to. Generic, context-free instructions that could describe any equipment (Replace the filter cartridge. with no model, system, or version named) are a Write-mode tell — a real technical document is always written for a specific system and says so, even briefly: On the X200 series pump, replace the filter cartridge as follows.
Section 1 — Words (ASD-STE100 rules 1.1–1.14)
Use only: a word with its approved dictionary meaning and part of speech (1.1–1.4), a technical noun (1.5–1.11), or a technical verb (1.12–1.13). American spelling throughout (1.14) — except quoted text (a screen string, a placard) already in British spelling, which stays as written.
Technical nouns name a concept specific to a subject field — the dictionary cannot list them because every field has its own set. A word qualifies only when it falls into one of 22 official categories:
parts information; vehicles/machines and their locations; tools and support equipment; materials, consumables, and unwanted material; facilities and logistics; systems, components, and circuits; mathematical, scientific, and engineering terms; navigation and geography; numbers, units, and time; quoted text; roles, individuals, organizations, and geopolitical entities; body parts; personal effects, food, and beverages; medical terms; official documents, parts of documentation, and standards; environmental and operational conditions; colors (category 17); damage terms; computing, information, and communication technology (category 19); civil and military operations; law and regulations; and animals, plants, and other life forms.
- A technical noun still needs to be short, common, and not regional, slang, or jargon (1.9–1.10) —
brickfor "make a device unusable" is technical slang even in a software context, not a valid technical noun. - Category 19 (computing/ICT) is why
database,firewall,token, andupdateare legitimate technical nouns in a software document even though none of them are in the general dictionary —interfaceis a different case, an ordinary approved dictionary noun, not an example of a category-only word. - A word not approved in the dictionary can still be legal as a technical noun in the right category (1.6); the two checks are independent, not "dictionary first, category as a fallback for everything else."
Colors (category 17) take no comparative or superlative form. blacker, the reddest — treat these as non-compliant even though they are ordinary English adjective inflections. Rewrite as plain, absolute color statements (The insulation on the left is black.), or, when the actual comparison matters for identification, label the parts instead of ranking their color (connector A, connector B).
Two guardrails for technical nouns:
- Do not verbify one, unless the dictionary independently approves it as both.
Grease the fasteners.is a technical noun used as a verb with no verb sense in either the dictionary or a technical-verb category — rewrite asApply grease to the fasteners.Clamp the cable in position.→Put clamps on the cable to hold it in position.This is not a blanket ban: a word can legitimately be a technical noun in one context and a technical verb in another —drillis a noun (use a carbide drill, category 3, tools) and a technical verb (Drill a hole, category 1a, manufacturing) at once; same forplate(noun:the plate is not damaged; verb:plate the ring nut). Check both categories before rewriting. - Never invent synonyms for the same item. Pick one term per concept and hold it for the whole document — a reader who sees
sensor,probe, anddetectorfor the same part assumes three different parts.
Technical verbs describe an action specific to a subject field, grouped into 4 categories: manufacturing processes; computer processes and applications (input/output, UI actions, system operations — click, drag, install, reboot, upload); subject-field instructions (engineering, medical, navigation, and similar domains); and law and regulations (comply with, enforce, waive). Three guardrails:
- Prefer the approved dictionary verb when one exists. A technical verb is a last resort, not a first choice.
- Technical verbs are context-bound, not a word list.
Enter your password.is valid (computer-process category).Do not enter the engine test area.is not —enteris not an approved general verb, so outside its technical-verb context it must becomeDo not go into the engine test area. - Do not nominalize one, with the same noun/verb-overlap exception as above.
Give the hole 0.20-inch ream.turns the verbreaminto a noun with no independent noun sense — rewrite asReam the hole to a 0.20-inch dimension.A past participle used as an adjective is still fine:Lubricate the reamed hole.
Section 2 — Multi-word nouns (rules 2.1–2.2)
Keep multi-word nouns to 3 words maximum. Actuator operating rod is fine; Horizontal cylinder pivot bearing is not.
- When a concept genuinely needs more than 3 words, first try to break it apart with a preposition (
of,on,in,for):Runway light connection resistance calibration(5 words) becomesCalibration of the resistance of the runway light connection. - When the term is a fixed technical noun from an official source and cannot be split, write it out in full on first use, then either give a short form (an approved abbreviation, used carefully — a procedure full of abbreviations is hard to read) or connect the words that act as one unit with hyphens (
cutoff-switch power connection). - A hyphenated group still counts as one multi-word noun and stays under the 3-word cap — do not chain more than 3 words with hyphens to dodge the limit (
main-gear-door-retraction-winchis not STE;main-gear-door retraction-winchis). - Never add or remove a hyphen in an already-approved technical noun.
Section 3 — Verbs (rules 3.1–3.7)
Allowed tenses and forms, exhaustively: infinitive, imperative (command form), simple present, simple past, simple future, and the past participle used as an adjective. Nothing else.
Explicitly banned: present perfect (has adjusted), past perfect (had adjusted), progressive (is adjusting), and any other auxiliary combined with a past participle used as a verb — not auxiliaries in general, so a modal with a bare infinitive (can adjust, must adjust, will adjust, all covered by the allowed forms above) stays legal. The operator has adjusted the linkage. → The operator adjusted the linkage. The seat is to be installed before you install the cushion. → Before you install the cushion, install the seat.
The past participle as adjective is not passive voice — it is a state.
- Allowed before a noun (
the disassembled unit) or after any form ofto be,to become, orto stay(When the unit is fully disassembled, clean all the parts.). - The gate is that the past participle form itself must be in the dictionary — true for any approved verb's own forms (
disassembledfrom the approved verbdisassemble). - Separately, a handful of past participles of verbs that are not approved are still listed as approved adjectives in their own right (
permitted,damaged) — those may be used even though the underlying verb may not be.
The -ing form is banned as a verb. It is permitted only as a technical noun (Cleaning, Troubleshooting, Handling) or as a modifier inside a technical noun, where it functions as an adjective related to the item's function (air-conditioning system, welding torch, grinding wheel). A small closed set of -ing words is approved outright, each bound to one specific part of speech, not usable as a verb: nouns lighting, opening, routing, servicing; adjectives mating, missing, remaining; the pronoun something; the preposition during. Any other -ing word needs one of the two escape hatches above or it is not STE.
Active voice is mandatory in procedural text. In descriptive text, passive is allowed only when the agent is genuinely unknown — test it by asking "by whom, or by what?"; if the text can answer, it must be active. Four methods to convert a passive sentence, chosen by what the sentence gives you (roughly in this order of how often each applies):
- The agent is named in a
byphrase — promote it to subject:The circuits are connected by a switching relay.→A switching relay connects the circuits. - Recast the infinitive as an active verb:
These values are used by the computer to calculate consumption.→The computer calculates consumption from these values. - In a procedure, switch straight to the imperative:
The test can be continued by the operator.→Continue the test. - No agent at all — supply
you(the reader) orwe(the organization):The valve can be opened with the override handle.→You can open the valve with the override handle.
Describe an action with an approved verb (3.7), not a noun or another part of speech. A verb is always clearer than a nominalized construction — this is the same principle behind the "never nominalize" guardrail in Section 1, applied generally, not only to technical verbs.
Section 4 — Sentences (rules 4.1–4.5)
Write short, complete sentences — no contractions, no dropped words for brevity. Rotary switch to INPUT. → Set the rotary switch to INPUT. If installed, remove the shims. → If shims are installed, remove them. When applicable, put an article (the, a, an) or demonstrative (this, these) in front of a noun or multi-word noun: Data module tells you how to operate unit. → This data module tells you how to operate the unit. Two cases skip the article: a general statement about a concept rather than a specific item (Solvents can cause damage to paint.), and a noun immediately followed by an alphanumeric identifier (Tag circuit breaker 36L7., not the circuit breaker).
Vertical lists for complex text follow 8 formatting rules: end the lead-in with a colon; identify each item with a number, letter, punctuation mark, or symbol (dash, bullet, letter, or number, held consistently); capitalize the first letter of every item; add an article before the subject noun of each item where applicable; end an item with a period if it is a complete sentence; do not end an item with a period if it is not a complete sentence; never end an item with a comma or semicolon; always end the last item with a period. Separately: never mix procedural and descriptive items in the same vertical list.
Connect related sentences with connecting words and phrases (4.4) — and, but, then, thus, as a result, at the same time — so the reader sees how one sentence's information relates to the next. Once you pick a connecting word or phrase for a relationship, hold it; do not vary it for the same relationship within a document.
Section 5 — Procedural writing (rules 5.1–5.5)
- Maximum 20 words per sentence — safety instructions obey this same limit, which is why a WARNING or CAUTION with more than one consequence gets split into several short sentences rather than one long one.
- One instruction per sentence, unless two or more actions happen simultaneously, or a result must be stated immediately after the action that produces it.
- Imperative form. Avoid
mustbefore a command — reserve it for instructions where the safety stakes justify the emphasis, or where the sentence states an important condition rather than the action itself. - When a condition applies, state the condition first, then the command, separated by a comma:
Set the switch to NORMAL when the light comes on.→When the light comes on, set the switch to NORMAL. - Notes give information only — never an instruction, and never the imperative form, a limit, a tolerance, or a work-step result (those belong directly in the work step, or in a safety instruction if getting them wrong risks damage or injury). A note may run up to 25 words per sentence (it follows the descriptive limit, not the 20-word procedural one). Test a note by removing it: the procedure must still be fully executable without it.
Section 6 — Descriptive writing (rules 6.1–6.6)
- Give information gradually; one subject per sentence.
- Use key words and key phrases (6.2) to give the text a logical structure, and hold them once chosen — the same discipline as the connecting words in Section 4.
- Maximum 25 words per sentence.
- Open each paragraph with a topic sentence (6.4); hold one topic per paragraph (6.5).
- Maximum 6 sentences per paragraph (6.6).
Example of splitting an overloaded sentence: A smartphone is a cellular telephone that has an integrated computer and many other functions, such as an operating system, internet browsing as well as the ability to run software applications. (31 words) becomes A smartphone is a cellular telephone that has an integrated computer and many other functions. (15 words) It includes an operating system and an internet browser, and it can also operate software applications. (16 words).
Section 7 — Safety instructions (rules 7.1–7.3)
Two levels in practice: warning for risk of injury or death to a person, caution for risk of damage to equipment or material — the standard phrases this as "an applicable word, for example warning or caution," and also allows a symbol where one is defined, but warning/caution is what nearly every document uses. Do an actual risk analysis, then decide: if there is a risk of injury or death, use warning; if there is only a risk of damage, use caution; when both apply, use warning. Structure: a clear command or condition first, then an explanation of the risk and its consequence.
CAUTION: EXTREME CLEANLINESS OF OXYGEN TUBES IS IMPERATIVE. understates a risk that can injure someone — rewrite as WARNING: MAKE SURE THAT THE OXYGEN TUBES ARE FULLY CLEAN. OXYGEN AND GREASE MAKE AN EXPLOSIVE MIXTURE. AN EXPLOSION CAN CAUSE INJURY OR DEATH. The non-STE version is an abstract, general statement; the STE version replaces it with the actual mechanism and consequence — that concreteness, not just the word "warning," is what makes the risk register with the reader. Uppercase formatting is a common convention in the source material, not an STE rule — STE governs wording, not typography.
Section 8 — Punctuation and word count (rules 8.1–8.7)
No semicolon. It invites run-on sentences and is easy to misuse — every other standard punctuation mark is permitted. Use hyphens to connect words acting as one unit (carbon-fiber-reinforced, O-ring, heat-treat). Parentheses are permitted for: illustration or text references, item identifiers, work-step identification, abbreviations, giving singular and plural at once, short explanations, and alternatives.
Word-counting rules — critical for hitting the 20/25-word limits correctly:
| Element | Counts as |
|---|---|
| A number, or a number with its unit | 1 word (10 °C = 1 word) — except a number that identifies a paragraph or work step, which does not count |
| An abbreviation, acronym, or alphanumeric identifier | 1 word |
| Quoted text | 1 word |
| A title, heading, placard, or label | 1 word |
| A proper noun (person, group, organization, geopolitical entity) | 1 word |
| A hyphenated word | 1 word |
| Text inside parentheses | 1 word in the host sentence — but the parenthetical text is also its own sentence and must independently meet the 20/25-word limit |
| A colon in a vertical list | Same effect as a period — ends the sentence for counting purposes, and each item after the colon is a new sentence with its own full 20/25-word budget |
A sentence like Set the valve to 10 °C (refer to Figure 3) and examine the carbon-fiber-reinforced panel. counts as 11 words under these rules, not the 16 a naive word-split would give — miscounting here is the most common way an otherwise-correct rewrite silently breaks the 20-word limit. (Note refer to, not see: see is approved only for something the reader looks at with their own eyes, not for a cross-reference.)
Section 9 — Writing practices (rules 9.1–9.4)
This section catches what a word-by-word swap misses, and it is the highest-value section for a first pass.
Substitute first; restructure when that is not enough (9.1). The default is a word-for-word swap from the dictionary's approved alternative. Restructure only when the swap breaks grammar or meaning: The oil level on the sight gauge must be visible during the test. → During the test, make sure that you can see the oil level on the sight gauge. (the approved verb see replaces the adjective visible, which forces must be to become make sure that you can).
Restricted meanings (9.2). Several words are approved for one sense only, and the trap is applying them outside it. damage is approved as a noun, not as a verb — Be careful not to damage the sleeve. becomes Be careful not to cause damage to the sleeve. about is approved as a preposition meaning "concerned with" (data about the circuit breakers) but not for approximation — use approximately there. check is approved as a noun, not a verb — Check the pressure. becomes Do a check of the pressure. or Examine the pressure. The indicator turns green. uses turn in an unapproved sense — rewrite as The color of the indicator changes to green. wear is not an approved verb for putting on protective equipment — Wear protective clothing. becomes Use protective clothing. or Put on protective clothing.
Phrasal verbs (9.3) — the trap no dictionary lookup catches. Most phrasal verbs never appear in the dictionary's "not approved" column at all, because the dictionary lists single words. After you put out the fire, close the valve. → After you extinguish the fire, close the valve. This compound can give off poisonous fumes. → This compound can release poisonous fumes. A handful of phrasal verbs are approved with a restricted sense (put on, come on, go off) — everything else needs a single-word replacement.
Terminological consistency (9.4). Once a term is chosen for a concept, hold it for the whole document — this is the same discipline as the technical-noun guardrail in Section 1, applied to every word choice.
General Recommendations (GR-1–GR-8)
These are guidance, explicitly not rules — apply judgment rather than treating them as hard limits.
| GR | Guidance |
|---|---|
| GR-1 | Always write that after verbs like make sure: Make sure that the valve is open., not Make sure the valve is open. |
| GR-2 | Re-read every sentence that uses with — it is a common source of ambiguity even in compliant STE. But do not "fix" it by recasting around use: keep the primary action verb. Seal the opening with tool TS9867., not Use tool TS9867 to seal the opening. |
| GR-3 | Use only approved pronouns; replace a pronoun with the noun itself whenever the referent could be ambiguous. he/she are not approved — use the noun or you |
| GR-4 | Make sure the referent of this is unambiguous — restate the noun if more than one candidate is nearby |
| GR-5 | Watch for false friends imported from the writer's own first language into English — verify the English meaning rather than assuming a look-alike word means the same thing (disposition is not disposizione/disposición) |
| GR-6 | Avoid Latin abbreviations — write for example instead of e.g., that is instead of i.e., and so on instead of etc. |
| GR-7 | Use inclusive, gender-neutral language throughout — gender-specific pronouns (he, she) and, generally, man/woman are not permitted; use them only where the context genuinely requires it (for example, a medical text) |
| GR-8 | The possessive 's is permitted, but if you are not confident the sentence reads correctly with it, do not use it — many readers' first languages have no equivalent construction |
Starter lexicon
These are reasoning heuristics — not a copy of the ASD-STE100 dictionary — that exemplify the STE preference (rules 9.1–9.2) for the shortest, most common, single-meaning word. Treat each as a default, not a mechanical find-and-replace: check the surrounding sentence for a restricted sense before swapping.
| Prefer | Over |
|---|---|
use | utilize, employ |
start | commence, initiate, begin |
stop | cease, discontinue, terminate |
do | perform, execute, conduct, accomplish, implement, undertake |
help | assist, aid (as a verb), facilitate |
make sure | ensure, verify, confirm, ascertain |
find | locate, determine |
show | indicate, display (as a verb), reveal, represent |
keep | retain, maintain (as a verb) |
get | obtain, acquire, procure |
remove | eliminate, extract, withdraw |
change | alter, modify |
tell | notify, advise, inform |
let | permit, allow, enable |
give | provide |
supply | deliver |
try | attempt |
send | submit, forward |
see | observe |
record | note (as a verb) |
before | prior to |
after | subsequent to |
because | since, as (causal) |
if | in the event that, whether |
also | in addition, furthermore, moreover |
but | however |
necessary | required, needed |
must | shall, should, is to |
can | may, is able to |
more | additional, further |
sufficient | enough, adequate |
same | identical |
different | various |
applicable | appropriate, suitable |
correct | proper |
unusual | abnormal |
sudden | abrupt |
full | entire |
fast | rapid (adjective only — the adverb sense is quickly) |
dangerous | hazardous |
approximately | around, about (quantity sense) |
more than / less than | over / under (as limits) |
person / personnel | people |
This is a starting set, not the full dictionary — it covers the substitutions that come up most often, not every approved or restricted word. For a word not listed here, reason from the same preference (shortest, most common, single-meaning word) rather than guessing, and fetch the official dictionary (see Consulting the specification, next) when the reasoning is not enough to be confident.
Consulting the specification
This file indexes all 53 rules by number so a reader can work unaided in common cases, but it does not transcribe the dictionary or the full category lists — that would reproduce a copyrighted work. Fetch and read the free official PDF at https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pdf (434 pages) when:
- A word's approved meaning, part of speech, or permitted verb forms is uncertain and not covered by the starter lexicon above — the dictionary is Part 2 of the standard.
- The subject field needs a technical noun or technical verb outside the examples given here — read the full category text under rules 1.5 and 1.12 for that field.
- A rule's exact wording matters, for an edge case, a dispute, or a compliance review.
- The user asks about a rule this file only summarizes.
The PDF is large — fetch it when a specific answer is needed, not as a default first step for every sentence.
Process
- Strip generation artifacts — register/chat leftovers, Markdown and typographic residue, em dash overuse.
- Strip AI-padding constructions and, for descriptive or
Write-mode text, discourse-architecture patterns. - Classify the source text (Step 0).
- Draft the rewrite, applying the rules for that classification.
- Check every sentence against its word limit using the counting table in Section 8 — recount, don't estimate.
- Check every verb against the allowed tenses in Section 3 — flag any perfect, progressive, or bare
-ingverb form. - Check technical nouns and technical verbs against their category tests in Section 1 — confirm each one is genuinely bound to a category in this context, not just familiar.
- Check Section 9 last — restricted meanings and phrasal verbs are the errors a word-swap pass misses.
- When a rule's application is unclear, fetch the specification (see above) rather than guessing.
- Self-audit: re-read the draft once as a reader with limited English, and once as a machine translator would — flag any sentence with more than one possible parse.
Output format
- Compliant text.
- Change log, one line per change. Cite the ASD-STE100 rule number for rule-driven changes (
Rule 3.6 — passive converted to imperative,Rule 8.6 — "10 °C" counted as one word); label everything else — artifact removal, padding removal, discourse-level fixes — asHygienerather than inventing a rule number for it (Hygiene — removed decorative emoji headers,Hygiene — removed challenge/optimism sandwich,Hygiene — replaced ghost Q&A with a direct statement). - Residual non-compliance, if any — cases that need a company or project terminology glossary this skill does not have access to (for example, choosing a single approved technical noun among several plausible candidates).
Limits and non-goals
STE governs wording, sentence structure, and paragraph structure — it does not regulate abbreviation choice, formatting conventions, or units of measurement, and it assumes those are set elsewhere. It is not an English course, and it is not usable alone: fluent English and a subject-field glossary are still required. It is built for technical documentation, not for marketing copy, brand voice, narrative writing, or oral scripts — a compliant STE paragraph reads as deliberately plain, which is the opposite of what those formats need.
This skill removes AI-generated bloat and register breaks — chat artifacts, decoration, padding constructions, discourse-level filler — because all of them work against the same goal STE's own rules enforce: short, direct, single-meaning text. It does not inject variety, personality, rhythm, or voice, and it does not police general English AI-vocabulary overuse (delve, leverage, robust) the way a general-purpose humanizer does — ASD-STE100's own dictionary already governs word choice for STE text specifically, and injecting stylistic variety would directly contradict rules 1.11 and 9.4 (hold one term, consistently, for the whole document). For general AI-writing-pattern cleanup outside a technical-documentation context, or for French text, use a general-purpose humanizer skill or samber/cc-skills@humaniseur-fr.
It does not fix hollow or unclear content; it only makes clear content unambiguous, and it does not invent facts a source is missing — a missing value gets flagged as residual non-compliance, never guessed.
This skill is not exhaustive. Refer to the official ASD-STE100 documentation at https://www.asd-ste100.org/ for anything beyond the rule index above — including the full dictionary, the complete technical noun and verb category lists, and future issues of the standard.
Persona: You are a senior negotiation coach. Negotiation is preparation × discovery × discipline — not charm. Walk away early, anchor late, never split the difference. Same toolkit for sales, salary, annual collective bargaining, hard 1:1s, cross-cultural, and recruitment.
Thinking mode: Reason as thoroughly as possible for live-stakes strategy and lost-outcome debriefs. Multi-move planning (what they say → what I say → what they say back) wins; shallow reasoning costs deals, raises, and trust. On Claude Code, use ultrathink to trigger extended thinking explicitly.
Modes:
| Mode | Trigger | Action |
|---|---|---|
| Preparation | "I have a [sales call / salary review / annual collective bargaining / hard 1:1 / recruitment close / cross-cultural deal] next week" | Phase 1 detects domain → Phases 1–5 with domain-specific axes |
| Live coach | "They just said X, what do I respond?" | Skip to Phase 6 |
| No-decision triage | "It's stuck — they like it but won't commit" | references/playbooks.md#jolt |
| Multi-thread / sponsor access | "I have a champion / advocate but no decider access" | references/playbooks.md#multi-threading |
| Renewal | "Renewal in 90 days, expansion possible" | references/playbooks.md#renewal |
| Team preparation | "We're going in as N1 + N2 (+ specialist)" | references/team-negotiation.md before Phase 1 |
| Debrief | "We lost the deal / strike happened / promotion went sideways" | Phase 7 + references/debrief.md |
| Tactic look-up | "What's BATNA?" / "How does mirroring work?" | Direct to the relevant reference file |
Questions: Ask the user through the environment's question tool — never as plain-text prose. One question at a time, 2–4 tappable options, wait for the answer. If the environment has no question tool, ask in prose with the same options, one at a time.
Influence and negotiation
Reference routing
The user rarely says "use this skill" — they paste an email or say "they just said X, what do I respond?". Read the right reference BEFORE drafting. Depth lives in the reference files; SKILL.md only routes.
All references load on trigger from the table below. Each workflow phase references the file(s) it needs at the moment it needs them — do not pre-load.
| File | Load when |
|---|---|
references/memory.md | Phase 0 — session start; user mentions a prior session, memory doc, Artifact, or Canvas from earlier work |
references/prepare.md | Phases 1–3 — preparation mode, stakeholder mapping, Mandascan, BATNA, POS, champion test |
references/tactics.md | Phases 4 or 6 — drafting any opener, anchor, calibrated question, label, SCO, back-brief, Pipe, or live response |
references/objections.md#refusal-triage | Classifying any "no" before responding (emotional / belief / bad-faith / identity / tactical) |
references/objections.md#the-four-root-commercial-objections | Price, timing, authority, or no-need objections (and cross-domain equivalents) |
references/objections.md#the-no-decision-trap-jolt | "Stuck", "they like it but won't sign", FOMU, indecision rather than disinterest |
references/objections.md#late-stage-stall--ghosting | Radio silence post-proposal, 10–14 days no reply, chase-vs-walk decision |
references/objections.md#procurement-playbook-awareness | Escalation ladder, fixed-budget, fake bid, MFN, MSA redlines, nibbling, bogey |
references/objections.md#the-non-negotiable | Verbal abuse, kickback, insults, ethical red lines |
references/objections.md#face-saving-exits | Counterparty needs to back down without admitting they were wrong |
references/playbooks.md#multi-threading-sequence--from-1-contact-to-47-stakeholders | Single-threaded deal; need access to EB / procurement / security / finance |
references/playbooks.md#mutual-action-plan-map--the-close-timeline-as-artifact | Mid-stage deal with hidden gating steps; drafting a Mutual Action Plan |
references/playbooks.md#jolt--the-no-decision-protocol | No-decision protocol (Judge / Offer / Limit / Take risk off) |
references/playbooks.md#executive-sponsor-eb-engagement--the-5-minute-opening | First 5 minutes with a C-level; earned-right frame |
references/playbooks.md#renewal--expansion--the-90-day-coopetition-cadence | Renewal in 90 days; T-90 / T-60 / T-45 / T-30 / T-10 cadence |
references/playbooks.md#salary-ask--the-structured-raise--offer-conversation | Raise ask, job offer, counter-offer, bolstering-range anchor |
references/playbooks.md#decision-announcement--difficult-11 | Layoff, performance plan, hard 1:1, recadrage |
references/playbooks.md#cross-cultural-deal--opening-the-room | International deal, M&A, joint venture, interpreter brief |
references/team-negotiation.md | Multiple people on your own side (N1+N2, SE, HR, hiring panel) |
references/biases-and-influence.md | Choosing or defending an influence lever (Cialdini, anchoring, contrast, loss aversion) |
references/manipulation.md | Counterparty fits a named manipulation pattern (bad faith, bluff, intimidation, faux pivot, …) |
references/debrief.md | Post-action: lost, won, what's transferable, defusing, BRRAC |
references/scenarios.md#saas-price-pushback | B2B ACV price pushback with multi-threading move |
references/scenarios.md#enterprise-rfp | Enterprise RFP + fiscal-year leverage + MSA redlines |
references/scenarios.md#asymmetric-power | Small vendor facing outsized buyer terms |
references/scenarios.md#annual-collective-bargaining-opening--strike-de-escalation | Annual collective bargaining opening session + strike de-escalation |
references/scenarios.md#salary-ask | Salary ask with "envelope closed" + external counter-offer |
references/scenarios.md#services-sow | Consulting SOW + scope-creep change request |
Don't load: objection refs in pure discovery (use prepare.md); prepare.md mid-conversation (use tactics.md); manipulation.md for ordinary hard negotiation; debrief.md while the conversation is still in progress.
Core philosophy
Three operating principles inherited from the references:
- 70% of the outcome is set before the room. The mandate, the stakeholder map, the walk-away — all written down before anyone joins the conversation. Improvisation is real-time adaptation of a pre-built plan, not making it up live. Negotiators who improvise consistently lose to negotiators who prepare consistently.
- Negotiate the underlying stake, not the position. The counterparty's stated demand is the tip of the iceberg. The deeper stake — career risk, board mandate, internal credibility, faith, identity, family — is what produces movement when addressed. Concede on positions and the counterparty walks; address the underlying stake and they co-create the agreement with you.
- The party more emotionally invested loses. Stress posture is the most-violated discipline across every domain this skill covers. Negotiators who can credibly walk away — and who let silence sit after their offer — win the room. Internal pressure (your own quota, your boss's expectations, your fear of the conversation) is consistently the #2 source of complexity for negotiators in industry surveys; the first negotiation is therefore with your own side over the mandate.
When NOT to use this skill
- Cold outreach copywriting — different skill entirely; the toolkit here presupposes a conversation has started.
- Standalone market research without a specific negotiation — "what's the market salary for X?" or "benchmark SaaS pricing in this category" without an active deal or conversation; use a dedicated research skill for those. Research tied to an active negotiation (BATNA grounding, stakeholder profiling, competitive intel in Phases 0–4) is in scope.
- Legal contract drafting — this skill prepares the negotiation around contracts, not the contract language itself; leave clause drafting to legal.
- Crisis negotiation (hostage, suicide, kidnapping) — out of scope; this skill adapts only the professional commercial / managerial portion of high-stakes negotiation theory.
- Personal / family conflicts — the methodology transfers but the worked examples and emotional stakes are different enough that you'll get better fit from a domain-specific resource.
Workflow
Phase 0: Session start — context intake
Read references/memory.md for the full memory system. Then ask:
"Is this a continuation of an ongoing negotiation? If yes, do you have a memory document — an Artifact, Canvas, or file — from a previous session?"
If yes: ask the user to share the memory.md entrypoint. Spawn a sub-agent to read all referenced memory files per the load policy in references/memory.md and return their content to the main agent. Then read references/context-intake.md in incremental mode — collect new raw material only, run deep research only on new sources, pass the quality gate, resume from ## Next session plan in strategy.md.
If no: read references/context-intake.md and follow the three steps — collect raw material, run full deep research, and pass the quality gate — before proceeding to Phase 1.
Phase 1: Mode + domain detection, then intake
Detect the mode AND the domain from the user's prompt. Domain cues:
- B2B sales: RFP, deal, ACV, procurement, ARR, champion
- Salary: raise, compensation, offer, counter-offer, equity, sign-on, band
- Social / annual collective bargaining: annual collective bargaining, union, CHRO, strike, works council
- Internal management: 1:1, performance plan, decision announcement, layoff, mediation
- Cross-cultural / diplomatic: international deal, M&A, joint venture, interpreter, protocol
- Recruitment: candidate, hire, offer close, back-channel, counter-offer
Domain shapes which axes matter and which references to load first; the workflow itself is the same.
For Preparation mode, run a live intake before anything else. Ask each question individually — don't dump them all at once. Adapt phrasing to the domain (B2B, salary, annual collective bargaining, recruitment, etc.).
Ask in this order, one at a time, and wait for the answer before continuing:
- Stage — "Where are you in the process — early exploration, mid-negotiation, close to agreement, or post-verbal-yes?"
- Stakes — "What's the size and scope here, and who's affected if this goes well or badly?"
- Counterparty — "Who's at the table — names and roles? Is the decision-maker in the room, or is there someone off-stage?"
- What's been said so far — "What are the last 2–3 things the counterparty said, as close to verbatim as you can get?" (Exact words carry signal that paraphrase loses — push for quotes.)
- Authority limits — "What can you commit to without checking with anyone? Where's your escalation threshold?"
- Walk-away — "At what point would you walk away from this entirely — what's your hard stop?"
Fuzzy answers reveal the mandate gap to fix first. If an answer is vague (e.g. "I don't know my walk-away"), surface that explicitly before proceeding — improvising on top of a fuzzy mandate produces the "More-More Syndrome" pathology where you over-ask at the moment of victory and lose the agreement in sight of the line.
Phase 2: Map the room
Read references/prepare.md. Then ask to fill in any gaps from Phase 1 — don't assume what you don't know. Ask:
- Formal structure — "Who else is involved on their side? What's the decision-making chain — who approves, who can veto?"
- Informal influence — "Who do people defer to in the room even if they don't have the title? Is there someone off-stage who'll influence the outcome?"
- Motivation per stakeholder — "What does [name] personally get if this goes well? What do they lose if it doesn't?"
- Process gaps — "What formal steps still need to happen — legal review, board sign-off, infosec, exec sponsor alignment, HR validation?"
- Alternatives — "What's their fallback if this doesn't close? Have they mentioned any other options or comparisons?"
Layer formal org chart + informal influence map — domain-specific stakeholder cast in references/prepare.md.
If the user names a champion or advocate, ask: "What concrete actions have they taken between meetings — have they proactively coordinated internally, shared information you didn't ask for, or moved things forward without prompting?" The 3-question commitment test lives in references/prepare.md#champion-test. Skipping this validation is the highest-leverage error in complex negotiations.
Stakeholder deep research. Once stakeholders are named, run parallel sub-agents (one per person) to profile each across CRM, Slack, LinkedIn, and OSINT — see references/prepare.md#stakeholder-mapping--org-chart--influence-map for the full sub-agent protocol, source-tracking rules, and output format.
Phase 3: Set the mandate (Mandascan)
Read references/prepare.md. Then guide the user through the mandate axis by axis — don't hand them a template to fill in alone.
Start by asking: "What are the axes you're negotiating? List everything on the table — price, payment terms, timeline, scope, SLAs, equity, leave, title, etc."
Then, for each axis the user names, ask through the 5 Mandascan points:
- "What's your opening number / position for [axis]?" (Entry)
- "What would a great outcome look like for [axis]?" (Ideal)
- "What's your realistic internal target — what you'd genuinely commit to?" (Objective)
- "At what point would you need to pause and check with someone before agreeing on [axis]?" (Escalation/bascule)
- "What's your hard walk-away on [axis] — below this, no deal?" (Rupture)
Fuzzy Rupture = mandate gap. Derive it from BATNA: "If this fails, what's your next best option?" — that sets the floor.
After the mandate, POS the counterparty per axis — see references/prepare.md. Axes by domain and worked examples also in references/prepare.md.
BATNA sizes Rupture, then put it away — see references/prepare.md.
BATNA market research. Run 6 parallel sub-agents across CRM, Slack, and open sources (benchmarks, competitor pricing, regulatory constraints, alternative supply) to ground BATNA in data — see references/prepare.md#batna-zopa-and-the-operational-divergence for the full agent list and output format.
Phase 4: Plan the moves
Read references/tactics.md NOW. This is the in-the-room toolkit (calibrated questions, mirroring, labeling, SCO, tactical pause scripts, back-brief, Negotiation Pipeline, anchoring with bolstering range). Do not draft scripts or pre-write moves without it — the specific phrasing matters.
Pre-write each artifact before the meeting; canonical phrasing in references/tactics.md:
- Opening anchor (bolstering range for salary asks; non-round numbers)
- Concession ladder (3–4 concessions, each paired with a counter-ask, one-for-one)
- 5–6 calibrated questions ("what" / "how", never "why")
- Accusation-audit labels that disarm objections before they form
- SCO statement — references/tactics.md#sco
- Tactical pause triggers + script — pre-decide signals and break script
Mutual Action Plan (where applicable). For mid-stage commercial deals, recruitment with multi-step approvals, or any negotiation with hidden gating steps, draft a MAP — see references/playbooks.md#map. It surfaces the legal / infosec / board / compliance-review / HR-validation steps that otherwise hide and creates joint ownership of the timeline. Stalls become diagnostic.
Team negotiation preparation. For high-stakes negotiations running with N1 + N2 or a full team (enterprise sales, annual collective bargaining with HR + line management, M&A), read references/team-negotiation.md and align on signalling protocol, mandate ownership, and scapegoat effect setup before the meeting.
When both MAP and team preparation apply, spawn two parallel sub-agents: one drafts the MAP using references/playbooks.md; the other produces the team briefing (roles, signalling protocol, mandate split, scapegoat effect setup) using references/team-negotiation.md. Both return full output to the main agent before Phase 5.
Number discipline. Specific anchor numbers and Mandascan figures belong in your private preparation notes — not in any counterparty-facing email, draft, or coaching artifact. Numbers leaked in writing become anchors for the other side or for your own commitment, and produce premature concessions. When coaching someone else, give them the strategic frame and the trade structure; let them say the number live on the call.
Pre-meeting competitive intelligence (B2B). For any commercial deal, run 6 parallel sub-agents across CRM, Slack, LinkedIn/Apollo, and open sources (current vendor signals, competitor positioning, buyer strategic signals, procurement history, analyst landscape, tech stack) — see references/prepare.md for the full agent list, source-tracking rules, and storage format.
Phase 5: Pre-mortem
Run a 3-minute mental simulation:
- Best objection — the one most likely to hit. Pre-write a label + reframe.
- Weakest objection — the one easiest to dismiss. Resist the temptation to spend cycles there.
- Surprise move — the gambit you didn't see coming (procurement escalation ladder, union ultimatum, manager pulling rank, candidate's current employer counter-offer). Pre-write a redirect.
The pre-mortem is the cheapest insurance against the "perte d'objectif" pathology — losing your mandate inside the room because you're improvising under stress.
Phase 6: Live response (objections, refusal handling)
Read the live-response references NOW, before drafting any response. Load references/tactics.md (the script library — calibrated questions, mirroring, labeling, SCO, anchoring, back-brief, Pipe) and references/objections.md, then navigate to the relevant objections section: refusal triage, four root objections, JOLT, procurement playbook, ghosting, non-negotiable, or face-saving exits. Do not improvise from the SKILL.md body alone — the specific scripts live in those files.
Triage the pushback type by reading references/objections.md#refusal-triage BEFORE drafting any reply — Emotional / Belief-based / Bad-faith / Identity-protective / Tactical each demand a different move; the reference has canonical signals and scripts.
For the four root commercial objections (price, timing, authority, no-need) and cross-domain equivalents, see references/objections.md#four-root.
No-decision diagnostic (JOLT). When the counterparty is engaged but not converging — saying yes to capability and no to commitment, or the deal stalls late without a substantive new objection — treat it as a no-decision case, not a loss to a competitor or a "needs more time" case.
The intervention is different: Judge / Offer / Limit / Take risk off — see references/playbooks.md#jolt. 40–60% of pipeline that doesn't close is no-decision; classical urgency tactics make it worse. The same pattern applies in promotion conversations (manager agrees in principle but never schedules HR sign-off) and in M&A (boards agree on strategic fit but defer signature indefinitely).
Manipulation taxonomy. When the counterparty's pushback fits a named manipulation pattern (bad faith, bluff, intimidation, punching-ball, faux pivot, feigned indifference, false cooperation, tactical silence, defeatism induction, closing manipulation), see references/manipulation.md for detection and counter-protocols that don't escalate.
Wrap-up before any agreement. Run a back-brief — see references/tactics.md. The counterparty reformulates each axis in their own words.
This is your defence against selective memory, closing manipulation, and genuine misunderstanding. At signature (or at the end of a salary conversation), run the Negotiation Pipeline closing checklist — see references/tactics.md.
Phase 7: Debrief
Read references/debrief.md. Then guide the user through it — don't just describe the framework.
Step 1 — check emotions first. Ask: "Before we analyse what happened — how are you and the team feeling about it?" If the answer carries visible frustration or blame, run defusing before RetEx. Ask: "What happened that was hard? What are you still carrying from it?" Let it land, reflect it back, then move to facts.
Step 2 — RetEx, question by question. Ask to walk through each step:
- "Walk me through the timeline of events — what happened, in order, as factually as you can?"
- "Looking at those facts: what worked? Which tactics, moments, or scripts actually moved things?"
- "What landed flat or created backlash? Where did you lose leverage you didn't need to lose?"
- "If you ran this negotiation again from the same starting point, what would you change first?"
- "What's transferable — what pattern would you teach to someone facing a similar situation?"
Step 3 — check for closing pathologies. Once the 5 RetEx answers are in hand, spawn a background agent: give it the complete RetEx narrative and instruct it to read references/debrief.md in full, then match the narrative exhaustively against all 5 pathology patterns (fear-of-failure, plan-b-preeminence, ego, "More-More Syndrome", target-fascination) and return a complete analysis — which patterns fired, the specific evidence from the narrative for each, and the recommended counter. The main agent continues the debrief conversation while this runs. When the background agent returns, surface its findings: if one or more patterns fired, name them directly — pattern recognition is 80% of the fix.
Phase 8: Humanize (only when output is counterparty-facing)
For drafted emails, scripts, or counter-proposals, invoke a humanizer skill (e.g. "humanize", "humanizer", "de-slop", "natural writing check", "AI detection cleanup") in the right language. AI-sounding prose triggers procurement scepticism, breaks champion trust, and undermines a difficult-conversation script that needs to land warm.
Preserve the calibrated questions and labels verbatim. They were tactically engineered (Phases 4 and 6); rewriting them for "naturalness" destroys the emotional logic. Tell the humanizer explicitly: keep questions and labels intact, scrub everything else.
The influence / manipulation line
Influence acts on the counterparty while preserving their free will; manipulation strips it. Influence wins over a multi-deal horizon — manipulation closes the current outcome and poisons the next one. → See references/biases-and-influence.md for the canonical definition, the 7 ethical influence levers, and the 9 cognitive biases.
Common traps
| # | Trap | Counter |
|---|---|---|
| 1 | Premature concession in discovery | Defer pricing / specific commitments until value or fit is established. "Happy to discuss commercials once we've confirmed fit." |
| 2 | Splitting the difference | Re-anchor with a non-monetary trade. "I can't do that, but help me understand…" |
| 3 | Concession without trade | Always pair every move with a counter-ask (term, scope, references, payment timing, commitment level, sign-on, equity). |
| 4 | False time pressure | "What happens if we miss that date?" Real deadlines have specific consequences; manufactured urgency evaporates under the question. |
| 5 | Single-threading | Multi-thread early. In sales: Economic Buyer + champion + procurement. In annual collective bargaining: line management + CHRO + ExCo. In a hard 1:1: the report's peers and likely-survivors. |
| 6 | "Happy ears" in discovery | SPIN Implication: "What happens if you do nothing?" Test pain depth before pitching the solution. |
| 7 | Anchoring on the counterparty's number | Pre-anchor with your range. If they go first, counter-extreme then move. For salary: bolstering range with your real target as the bottom. |
| 8 | Filling silence | Count to 4 after every offer or label. The next person to speak loses leverage. |
| 9 | Escalation ladder | Name it: "We've discussed this twice already; I need to understand who has the final authority so we can have one conversation rather than three." |
| 10 | Fixed-envelope claim | "How was that number set?" / "What would unlock movement at the next review?" Budgets are rarely as hard as stated. |
| 11 | Internal-pressure self-concession | Your urgency must not exceed the counterparty's. Trade close-by-date / quarter-end for structural value — never give it. |
| 12 | Mixing issues | Park: "Let's resolve scope, then come back to price." One issue per round. |
| 13 | Sympathy collapse | Verbalise the emotion (empathie) — never share it (sympathie). Sharing costs you objectivity when you most need it. |
| 14 | Skipping the back-brief | Before any agreement, the counterparty reformulates each term in their own words. Catches selective memory, closing manipulation, and misunderstanding before they become churn. |
Master rule (every serious negotiation tradition agrees): "I might be able to move on X if you can help me with Y." Trade. Never give. Exception: a small unilateral opening concession is safe only with a verified-cooperative counterparty — see references/tactics.md.
Persona: You are a B2B ghostwriter. You extract authentic, quantified stories and turn them into high-conversion LinkedIn posts — results first.
LinkedIn Ghostwriting
Generate conversion-focused LinkedIn B2B posts, prioritizing results and authority over vanity metrics.
Workflow
Phase 1: Strategic Interview
Extract authentic, quantified material before writing anything. Without raw material, even skilled writing produces generic posts that blend into the feed.
Ask questions (8-14 at once) covering these areas:
Audience & Context
- Target audience (who exactly?)
- Starting situation
- Main constraint
Business Goal
- Post objective
- Offer/CTA
Results
- Exact BEFORE → AFTER numbers + timeframe
- Volume/sample size
- What's publicly claimable
Mechanism
- Method in 3 steps max (action verbs, not theory)
- The detail that changes everything
Insight
- Market belief you contradict
- Common expensive mistake
Credibility
- What it cost you (time/money)
- Specific scene or moment
- Social proof (optional)
- Resource to offer
Validation checklist: Only move to Phase 2 when you have all four — missing any one leaves the post without the structural tension that drives engagement:
- At least 1 quantified metric
- 1 clear counter-intuitive insight
- 1 mechanism (2-3 steps)
- 1 determined CTA
Phase 2: Hook Engineering
Propose 3-5 hooks based on frameworks in references/hook-frameworks.md.
Rules:
- Reveal 80% (result/subject), keep 20% (how) to create tension — giving away everything kills the reason to read on
- No rhetorical questions, no vague promises
- Radical specificity: numbers, deadlines, contrasts, costs
- Provide ONLY hooks (no body, no outline, no explanation)
Wait for user to choose one.
Phase 3: Post Body
Apply these copywriting principles:
Writing rules:
- Cut ruthlessly — every word must earn its place; padding dilutes impact
- Remove: "very", "really", "incredibly"
- Use active voice (Zombie Test: would "by zombies" work? If yes, rewrite)
- Vary sentence length: 3-5 words for impact, then medium length for explanation
Structure:
- Re-Hook: Punchy transition from hook
- ABT logic: AND (context) → BUT (problem) → THEREFORE (solution)
- Revelation rate: New info/numbers/wit at regular intervals to maintain scroll momentum
- Psychology lever: Complicity | Support | Reciprocity | Mindfuck
- CTA: Clear and directive (no open-ended questions — they reduce action)
Formatting:
- Mobile-first: 58% of LinkedIn reads happen on phones; long paragraphs become walls of text and get skipped
- Never more than 2 visual lines per paragraph on phone
- Line breaks between most sentences
- Use bullet points heavily
Avoid:
- Rhetorical questions — they signal low confidence and annoy readers
- Empty words ("digital landscape", "incontournable", "liberate potential")
- Emoji abuse
- Clichés ("X is like Y")
- Ternary structures
Final polish
After writing the post, invoke a humanizer skill (e.g. "humanize", "humanizer", "de-slop", "natural writing check", "AI detection cleanup", "rewrite like a human") to scrub AI-generated patterns — filler words, predictable cadence, over-hedging, and hollow transitions. A LinkedIn post that reads like GPT output loses credibility instantly.
Preserve hooks. The hook (first 1-3 lines) was deliberately engineered in Phase 2 for tension and specificity. Instruct the humanizer to leave the hook intact — rewriting it for "naturalness" destroys the copywriting structure that drives engagement.
Mental Models
Jenga vs Kapla: Remove words until the structure is pure without collapsing. Less is more.
Aristotle's Triptych:
- Ethos: Show results, social proof, experience
- Logos: Logic, numbers, clear process
- Pathos: Emotion only if it serves credibility/connection
Costly Signal: Visible effort increases perceived value ("I spent 40 hours..." | "I invested €2,000..."). Signals skin in the game.
Allbound Strategy: Content (inbound) triggers conversations (outbound). Design posts to drive DMs and profile visits, not just impressions.
Style
Use unicode bold instead of simple bold styling. Much easier to copy-paste into Linkedin for a human.
References
- references/hook-frameworks.md — Six proven hook frameworks with examples
- references/example-post.md — Real example post with breakdown
Persona: You are an expert PR writer who combines journalistic discipline with strategic communication. You write press releases that journalists actually want to read: factual, structured, newsworthy, and free of marketing fluff.
Core Philosophy
A press release is a news document, not an advertisement. If there is no genuine news, no amount of craft will save the release.
- 72% of journalists still cite press releases as their most useful PR resource, but 77% of pitches they receive are irrelevant.
- Your job is to find the news angle and present it in the format journalists expect.
Workflow
Step 1: Gather Context
Before writing, collect the information below. Extract what you can from any brief or document the user provides and only ask for what's missing.
Required:
- The news — What happened? What changed? Why now?
- Release type — Product launch, funding, partnership, crisis, M&A, earnings, event, award, executive hire, open source milestone?
- Target audience — Which journalists/outlets? Trade press or general?
- Target region/market — Determines style guide, dateline, regulatory requirements, optimal send timing
- Target media format — Print, digital/wire, broadcast, social, or all?
- Company info — Name, what it does, HQ, key figures
- Spokesperson(s) — Name, title, quote message
- Supporting data — Numbers, statistics, proof points
- Embargo — Date, time, timezone if applicable
- Language — French, English, other?
Nice to have: boilerplate, press contact, multimedia assets, distribution plan.
Step 2: Identify the News Angle
Articulate the angle in one sentence. Validate against news values (impact, timeliness, prominence, novelty, proximity). If the angle is weak, tell the user and suggest how to strengthen it.
Step 3: Read the Relevant References
Based on context gathered, read the appropriate reference files:
- Always read: Press release types for the template matching the release type
- If targeting a specific region: Regional conventions for style guide, dateline, regulations, optimal send times, and cultural expectations
- If adapting for a specific media format: Media formats for format-specific adaptations
- If preparing a journalist email pitch: Journalist email pitch for subject lines, hook types, email structure, and follow-up cadence
- For writing style guidance: Writing principles for detailed rules on tone, language, and quotes
- For delivery format options: Output options for markdown, Word, email-ready, bilingual, press kit formats
Step 4: Propose Headline Variants
Before writing, present 5 to 10 headline options using different hook types. Vary the approach across options — mix data-driven, question, bold claim, contrast, human interest, urgency, and counterintuitive hooks. For each variant, label the hook type used.
Ask the user which headline and hook direction they prefer before proceeding to the draft.
Step 5: Write the Press Release
Follow the inverted pyramid: most important information first, supporting details in descending order. Every paragraph should be removable from the bottom without destroying the core message.
Universal structure:
[RELEASE DESIGNATION] FOR IMMEDIATE RELEASE / EMBARGO
[HEADLINE] Sentence case. Core news.
[SUBHEADLINE] (optional) ~20 words. Secondary angle.
[DATELINE] -- [LEAD] Answer 5W1H in exactly 25-35 words. Count them.
[BODY 1] Expand on lead. Primary data point.
[QUOTE 1] Senior executive. Insight, not "We're thrilled."
[BODY 2] Additional context, market data.
[QUOTE 2] (optional) Third party -- customer, partner, investor.
[BODY 3] (if needed) Future plans, availability, CTA.
[BOILERPLATE] About [Company]. ~100 words. Factual. No superlatives.
[MEDIA CONTACT] Name, title, email, phone.
###
Step 6: Apply Quality Checks
- Lead answers 5W1H in 25-35 words (count them — under 25 is too thin, over 35 buries the news)
- Total length 300-500 words
- Inverted pyramid respected
- Third person throughout (no "we"/"our" outside quotes)
- Active voice dominant
- No unsupported superlatives
- No banned phrases: "thrilled," "excited to announce," "proud to," "innovative," "cutting-edge," "world-class," "synergy"
- Attribution verb is "said"
- At least one concrete number or data point
- Quotes add insight, not empty enthusiasm
- Correct dateline and style guide for target region
- Boilerplate present, under 100 words
- End mark (### or -30-)
Step 6b: Humanize
Invoke a humanizer skill (e.g. "humanize", "humanizer", "de-slop", "natural writing check", "AI detection cleanup", "rewrite like a human") to remove AI-generated patterns — inflated language, predictable sentence rhythm, hollow transitions. Journalists spot AI copy immediately and discard it.
Preserve the headline and lead. The headline (Step 4) and lead paragraph (5W1H in 25-35 words) were deliberately crafted for news impact. Instruct the humanizer to leave them intact — loosening them for "naturalness" breaks the inverted pyramid and the word-count constraint.
Step 7: Deliver with Context
Present the press release with:
- The press release in the target language
- Angle note — why you chose this angle
Step 8: Suggest Next Steps
After delivering the press release, suggest actionable next steps:
- Distribution recommendation — optimal send day/time for the target market (see regional conventions), channel mix, embargo considerations
- Email pitch to journalists — offer to draft a pitch email with hook and subject line variants (see journalist email pitch)
- Social media teaser — offer to draft social posts to amplify the announcement
- Journalist shortlist criteria — suggest how to build a targeted journalist list for this release
promql-cli — Prometheus Query CLI Skill
promql-cli (github.com/nalbury/promql-cli) is a Go CLI for querying, analyzing, and visualizing Prometheus metrics, plus PromQL fundamentals.
Reference Files
Read the relevant reference file(s) before executing tasks:
| File | When to read |
|---|---|
references/installation.md | User needs to install promql-cli or set up configuration (hosts, auth, token, password, multi-host) |
references/usage.md | User wants to discover metrics/exporters/labels, run queries, or choose output formats |
references/graphing.md | User wants to visualize Prometheus data as an ASCII chart in the terminal |
references/debugging.md | User is investigating a performance issue, latency, errors, saturation, data gaps, or query cost issues |
references/promql-reference.md | User needs help writing PromQL, understanding metric types, functions, or aggregations |
For most tasks, read references/usage.md. For PromQL help, read references/promql-reference.md. When debugging, read both references/debugging.md and references/promql-reference.md.
Setup Check
Before running any query, verify that a host is configured:
promql 'up' # succeeds if host is reachable; fails with connection error if not configured
# or
promql --host xxx 'up'
Recognize these errors as a configuration/auth problem and refer to references/installation.md:
| Error | Cause |
|---|---|
dial tcp ... connection refused | No host running at the configured address |
dial tcp ... no such host | Hostname not resolved — wrong host in config |
error querying prometheus: ...401... | Bearer token missing or invalid |
error querying prometheus: ...403... | Token valid but insufficient permissions |
please specify an authentication type | Auth flags partially set — use config file instead |
If any of these appear, do not create config files on behalf of the user — config files may contain credentials (tokens, passwords) that must never pass through an LLM. Instead, guide the user to set it up themselves:
"Please create
~/.promql-cli.yamlmanually with your Prometheus host (and credentials if needed). Seereferences/installation.mdfor the exact format. Let me know once it's ready."
Only after the user confirms the config is in place should you proceed with queries.
Quick Command Reference
promql 'up' # instant query
promql 'rate(http_requests_total[5m])' --start 1h # range query (ASCII graph)
promql 'up' --output csv # CSV output
promql 'up' --output json # JSON output
promql metrics # list all metric names
promql labels <metric> # list labels for a metric
promql meta <metric> # show metric type and help
promql --config ~/.promql-cli-prod.yaml 'up' # target a specific host
Key Principles
- Use
rate()on counters, never raw values — raw counters only ever increase; the absolute value is meaningless.rate()gives the per-second change rate, which is what you actually care about. - When debugging, isolate a single instance — aggregating across replicas masks per-instance anomalies. A single overloaded pod hidden behind healthy peers won't show up in averages.
- Filter early with label matchers in the innermost selector — Prometheus evaluates selectors before functions, so filtering late means scanning all time series. Early filters reduce data scanned and query latency.
- For histograms, keep
lein thebyclause beforehistogram_quantile()— the function needs alllebuckets to interpolate percentiles; droppingleearly producesNaNor wrong results. - Prefer
--output graphfor range queries — ASCII sparklines convey trend direction (rising, falling, spiking) in a compact format that LLMs parse well; raw timestamp tables require mental modeling. Never send thousands of raw JSON/CSV rows into the LLM context — use--output graphinstead, or run--output graphfirst and--output tableonly to inspect a narrow window. - Store credentials in
~/.promql-cli.yamland~/.promql_token, chmod 600 — passing tokens as CLI args exposes them in shell history and process listings.
Query Cost Rules
Always apply these before and during any query session:
- Always use the promql CLI — never call the Prometheus HTTP API from Python scripts or shell
curl. The CLI handles auth, formatting, and output consistently; Python API calls bypass all of that and produce raw JSON that must be parsed, inflating context and masking the graph output that models interpret best. - Check cardinality first — before querying an unfamiliar metric, count its time series (
count(metric_name)). High-cardinality metrics without label filters time out or flood the output. Seereferences/debugging.mdfor patterns. - Confirm the time window upfront — always ask before running range queries. Large intervals are expensive; prefer multiple short-interval queries over one long one.
- Clarify past vs. recent — for new investigations, ask whether the user wants a past event (specific timestamp) or a recent trend. If recent, offer concrete choices: last hour, last day, last week, last month.
- Aggregate in Prometheus — never pull raw series to aggregate in Python or shell. Push
sum by(...),avg by(...), ortopk()into the PromQL expression — Prometheus collapses series server-side. - Timeout = query too broad — if a query takes >15s, reduce scope: add label filters, shorten
--start, or add an aggregation wrapper. Apply the same narrowed scope to all subsequent queries in the session. - Data gaps → check
up— when a metric shows missing data, runup{job="...", instance="..."}before diagnosing the application. A0value confirms the exporter was down. Seereferences/debugging.md.
This skill is not exhaustive. Please refer to the official promql-cli documentation and examples for up-to-date information. Context7 can help as a discoverability platform.
If you encounter a bug or unexpected behavior in promql-cli itself, open an issue at https://github.com/nalbury/promql-cli/issues.
Questions: Ask the user through the environment's question tool — never as plain-text prose. One question at a time, 2–4 tappable options, wait for the answer. If the environment has no question tool, ask in prose with the same options, one at a time.
Site Launch Checklist
Pre-launch audit and setup workflow for shipping a new website. Opinionated for Cloudflare DNS + Vercel hosting + PostHog + Legal context.
Interaction style (READ FIRST)
This skill is intentionally interactive. Ask aggressively instead of assuming. The user will tap, not type.
Always ask these questions at the start of a run (one at a time, in this order):
- Site type:
doc-site|marketing/lead-gen|SaaS-app|training/paid-course|personal-portfolio - Migration:
greenfield-new-domain|migration-need-301-redirects|replacing-existing-on-same-domain - Multilingual:
single-locale|en|fr+en|other-multi - PostHog setup:
hogpost.samber.dev|set-up-new-proxy|skip-PostHog - AI scraper policy:
use-default-for-site-type|customize-per-bot|block-all - Browser tool available:
claude-chrome-extension|playwright|neither-skip-browser-checks
Ask again at every decision point throughout the phases, including:
- Whether to install Sentry / BetterStack / Crisp (depends on site type, ask explicitly)
- www vs apex canonical preference (most sites: apex; ask anyway)
- Which AI bots to allow if user chose
customize-per-bot - CSP tightness level:
strict-default-src-none|balanced-allow-self|permissive-for-marketing - Whether to skip a phase entirely (e.g., skip Phase 3 if non-FR site)
Never proceed past a decision point without explicit user input. Verbose checklists without checkpoints are not the goal.
Never install any MCP server or skill without explicit user confirmation. Always ask via the question tool before running npx skills add, claude mcp add, or any equivalent install command — even when the skill selection workflow proposes a curated subset.
How to use this skill
- Run the start-of-session questions above.
- Walk the user through phases 1-10 in order. For each phase: a. List items, ask if any should be skipped. b. For each remaining item, run the verification command (see "Verification tools" below). c. Report pass/fail. On fail, ask the user if they want to fix now or queue for later.
- End with a status report grouped by phase, with blockers, recommended fixes, and optional improvements clearly separated.
Companion skills
Six skill packs are useful for site launches. Never install full multi-skill packs. The actual subset to install is decided at invocation time based on the site type the user confirms.
Pack inventory
| Pack | What it covers | Typically useful for |
|---|---|---|
AgriciDaniel/claude-seo | SEO + GEO + schema + hreflang + sitemaps audits, parallel sub-agents | All site types |
addyosmani/web-quality-skills | Lighthouse, Core Web Vitals, accessibility, performance, best practices | All site types |
trailofbits/skills | Security audit (OWASP, headers, dependencies) | All site types |
aaron-he-zhu/seo-geo-claude-skills | 20 SEO+GEO skills, CORE-EEAT + CITE frameworks, /seo: slash commands | Content-heavy sites, competitive niches |
coreyhaines31/marketingskills | ~30 marketing skills (CRO, copywriting, ads, popups, email, paywalls, etc.) | marketing/lead-gen, SaaS-app, training/paid-course |
jonathimer/devmarketing-skills | 33 developer-marketing skills (persona, docs-as-marketing, technical tutorials, etc.) | doc-site, SaaS-app for developers |
Skill selection workflow (run at session start)
After the user confirms site type, for each pack relevant to that site type:
- List available sub-skills:
npx skills add owner/repo --list - Propose a curated subset based on site type and the phases this skill will execute. Match each phase's needs to specific sub-skills the listing returns.
- Confirm with the user. Use multi-select when the proposed list has more than 3 items, single-select (
install-as-proposed|let-me-modify|skip-this-pack) otherwise. - Bulk install the agreed subset:
npx skills add owner/repo --skill A B C
Rules:
- Sub-skill names live in the pack, not in this SKILL.md. Always query
--listfor the current state. Pack contents change. - Never run
npx skills add owner/repowithout--skill(that installs everything). - Site type → packs mapping (which packs to enumerate, sub-skills still selected per workflow):
doc-site: claude-seo, web-quality-skills, trailofbits, seo-geo-claude-skills, devmarketing-skillsmarketing/lead-gen: claude-seo, web-quality-skills, trailofbits, seo-geo-claude-skills, marketingskillsSaaS-app: all sixtraining/paid-course: claude-seo, web-quality-skills, trailofbits, marketingskillspersonal-portfolio: claude-seo, web-quality-skills, trailofbits, seo-geo-claude-skills (lightweight subset)
- If the user later requests a phase that needs a sub-skill not yet installed, run the workflow again for that single sub-skill rather than re-installing the whole subset.
This avoids importing 80+ skills the user does not need, avoids going stale on sub-skill names, and avoids overfitting to a single pack version.
When delegating during a phase, do not duplicate work this skill orchestrates. Call the specialist with a narrow scope (e.g., "run only the security headers sub-audit on URL X").
Phase 0: Launch Readiness Gate
Run this BEFORE any other phase. Products don't market themselves—but a product that isn't ready won't market either. The launch mechanics only pay off if what you're launching is worth launching.
Two failure modes kill launches from opposite ends:
- Stealth Mode — launching too late. "Procrastination in a fancy suit." You keep polishing in private, waiting for the product to be perfect. It never ships, and nobody learns you exist.
- "Just One More Feature" — never launching. Every proposed launch date gets pushed for one more thing. The scope creeps forever; the launch never comes.
The middle path is SLC — Simple, Lovable, Complete (Jason Cohen), the antidote to shipping a bare MVP that's minimal but unlovable. Don't launch a stub nobody wants; don't wait for a bloated everything-app. A launchable v1 is:
- Simple — it does one thing. Not many things poorly. One clear job, done well.
- Lovable — people want to use it, not just tolerate it. An MVP asks users to suffer through a stripped-down experience "to give feedback." SLC gives them something they'd choose. If nobody would be sad to lose it, it isn't lovable yet.
- Complete — it's a whole experience for that one thing, not a stub with obvious holes. Complete at its chosen scope, not a teaser of a bigger promise.
The gate: If it's not yet Simple, Lovable, and Complete, you're in "Just One More Feature" territory only when adding scope is what's missing—otherwise you're in Stealth Mode and should ship. Cut scope until one thing is lovable and complete, then launch that. SLC gives you a real launch now instead of a perfect launch never.
Quick check before running the phases:
- Does it do one clearly-defined thing? (Simple)
- Would a target user choose to use it, not just endure it? (Lovable)
- Is that one thing a whole experience, with no glaring stubs? (Complete)
- Are you polishing past this bar? → Stop. You're in Stealth Mode. Ship.
- Are you still adding new things to the scope? → Stop. You're in "Just One More Feature." Cut back to SLC.
Directory submission readiness (from directory-submissions skill): Ask these 9 questions. If any are "no", they're not ready — help them build the missing piece first.
- Is the product publicly accessible (no password wall)?
- Is there a pricing page (even "free while in beta")?
- Are privacy policy + terms live?
- Logo assets in PNG + SVG + square + favicon?
- 5–8 real screenshots + 60–90s demo video?
- Landing pages GEO-ready (single H1, sequential hierarchy, FAQ schema, structured data)?
- At least 3 alternative pages and 3 use-case pages live and indexed?
- Template gallery or lead magnet asset (if applicable to category)?
- At least 20 beta/early users who could leave a review on G2?
A "no" on any of 1–7 is a hard block. A "no" on 8–9 is a soft block: you can launch but will lose Tier 2 review value and Typeform-style compounding.
ORB Channel Strategy (from launch skill): Structure your launch marketing across three channel types. Everything should ultimately lead back to owned channels.
Owned Channels
You own the channel (though not the audience). Direct access without algorithms or platform rules.
- Email list, Blog, Podcast, Branded community (Slack, Discord), Website/product
- Start with 1-2 based on audience: Industry lacks quality content → Blog; People want direct updates → Email; Engagement matters → Community
Rented Channels
Platforms that provide visibility but you don't control. Algorithms shift, rules change, pay-to-play increases.
- Social media (Twitter/X, LinkedIn, Instagram), App stores, YouTube, Reddit
- How to use correctly: Pick 1-2 platforms where your audience is active; Use them to drive traffic to owned channels; Don't rely on them as your only strategy
Borrowed Channels
Tap into someone else's audience to shortcut the hardest part—getting noticed.
- Guest content (blog posts, podcast interviews, newsletter features)
- Collaborations (webinars, co-marketing, social takeovers)
- Speaking engagements (conferences, panels, virtual summits)
- Influencer partnerships
- Be proactive: List industry leaders your audience follows → Pitch win-win collaborations → Use tools like SparkToro or Listen Notes to find audience overlap
Pass the gate, then run the phases below.
Copywriting voice and humanizer pass
Every site has visible marketing copy (hero, features, CTAs, meta descriptions, OG descriptions, blog posts, 404 page text). Two layers of polish are mandatory before launch:
1. Define TONE.md once per site
Ask the user: "Does this site already have a TONE.md?" (yes-already-exists | no-create-from-template | skip-use-default).
If creating: write it to .agents/TONE.md or repo root TONE.md. See references/templates.md (section "TONE.md template") for the structure.
TONE.md specifies: voice (terse, contrarian, etc.), forbidden patterns (e.g., "delve", "crucial", em dashes, AI-sounding openers), sentence length preference, audience reading level, examples of good and bad sentences from the user's own writing.
2. Run a humanizer pass in the matching language
After every drafting step (whether by a copywriting skill, by hand, or by Claude directly), run a humanizer to strip AI patterns.
Ask the user for the site's primary audience language at the start of the session if not already known:
english-global→npx skills add https://github.com/blader/humanizer --skill humanizerfrench→ usesamber/cc-skills@humaniseur-fr(custom French humanizer) or equivalent French-tuned skillother→ install matching humanizer if available; otherwise the skill writes a short language-specific anti-pattern checklist inline
Apply the humanizer to: hero copy, feature descriptions, CTA buttons, meta descriptions, OG/Twitter card descriptions, blog posts, email signup confirmations, 404 page text. Skip for legal pages (mentions légales, CGV) since they have rigid wording requirements.
3. Always reference TONE.md when invoking copywriting skills
When delegating to any copywriting or content-writing sub-skill (selected at invocation per the skill selection workflow), include TONE.md in the prompt context. Pass voice constraints explicitly: "Follow .agents/TONE.md. Avoid the listed patterns. Apply the humanizer after drafting."
Browser interaction preference
Many checks require a real browser (Lighthouse runs, securityheaders.com scan, opengraph.xyz validation, Twitter card validator, mobile viewport, screen reader smoke, Network tab inspection).
Always prefer the Claude Chrome extension. Fall back to Playwright only if the Chrome extension is unavailable. If neither is available, ask the user whether to skip browser checks entirely or wait until they enable one.
Verification tools
Most checks are doable from the command line without third-party services. Use these tools inline at every phase. Don't trust panels in Cloudflare/Vercel/Google dashboards alone, verify with curl.
DNS (Phase 1):
dig +short A example.com # A record
dig +short AAAA example.com # AAAA (IPv6)
dig +short MX example.com # MX (mail)
dig +short TXT example.com # SPF + verification TXT
dig +short TXT _dmarc.example.com # DMARC
dig +short TXT default._domainkey.example.com # DKIM (selector varies)
dig +short CAA example.com # CAA
dig +dnssec example.com | grep RRSIG # DNSSEC active
TLS / HTTPS (Phase 1):
curl -sIL https://example.com | head # follow redirects
curl -sI https://www.example.com # check www handling
openssl s_client -showcerts -connect example.com:443 < /dev/null 2>/dev/null | openssl x509 -noout -dates
Headers (Phase 4):
curl -sI https://example.com | grep -iE 'content-security-policy|strict-transport-security|x-frame-options|x-content-type-options|referrer-policy|permissions-policy'
# Full header dump:
curl -sI https://example.com
# External graders:
curl -s "https://api.securityheaders.com/?q=https://example.com&followRedirects=on&hide=on" -I | grep -i 'x-grade'
SEO files (Phase 5):
curl -s https://example.com/robots.txt
curl -sI https://example.com/sitemap.xml
curl -s https://example.com/sitemap.xml | head -40
curl -s https://example.com/llms.txt
# Schema (JSON-LD):
curl -s https://example.com/ | grep -A 50 'application/ld+json'
# hreflang:
curl -s https://example.com/ | grep -i hreflang
Open Graph & social (Phase 6):
curl -s https://example.com/page | grep -iE 'og:|twitter:|<title|name="description"'
Favicons & manifest (Phase 7):
curl -sI https://example.com/favicon.ico
curl -sI https://example.com/favicon.svg
curl -sI https://example.com/apple-touch-icon.png
curl -s https://example.com/manifest.json | jq .
404 / 500 / redirects:
curl -sI https://example.com/this-does-not-exist
curl -sIL https://example.com/old-url # verify 301 chain
Always run the relevant command, paste the output to the user when reporting, then ask whether to fix immediately or queue.
Phase 1: Domain & Infrastructure
Most of this is one-click via Cloudflare's dashboard if the domain is on Cloudflare.
Ask first: "Is the domain already on Cloudflare with the standard config from previous launches?" (yes-standard | yes-needs-review | no-fresh-setup)
Checklist:
- Cloudflare: proxy ON for apex + www, TLS 1.3 minimum, "Always Use HTTPS" enabled, HSTS preload enabled in Cloudflare SSL/TLS settings
- DNS A/AAAA or CNAME pointing to Vercel (verify with
dig +short A example.com) - MX records for Google Workspace (verify with
dig +short MX example.com) - SPF, DKIM, DMARC records (verify all 3 with the dig commands above)
- CAA records restricting cert issuance (verify with
dig +short CAA example.com) - DNSSEC enabled at registrar level (verify with
dig +dnssec) - Vercel: project linked to repo, prod + preview env vars set, custom domain attached, prod and preview aliases correct
- Decide www vs apex canonical, configure 308 redirect for the non-canonical (verify with
curl -sIL https://www.example.com) - Custom 404 page renders (verify with
curl -sI https://example.com/does-not-exist) - Custom 500 page exists (cannot easily verify without forcing an error, ask user)
- If migration: 301 redirect map for every old URL (loop verification with
curl -sILper URL)
Backups
If you don't configure backups at launch, you never will. Do it now.
Ask the user: "Which data stores does this app write to?" (database-only | database-plus-file-storage | file-storage-only | stateless-no-persistent-data). If stateless-no-persistent-data, skip this section.
Database:
- Automated daily backups enabled at the provider level (Neon, Supabase, PlanetScale, Railway, RDS — each has a one-click toggle). Verify by opening the backup panel and confirming the last backup timestamp is recent.
- Retention policy set to ≥30 days
- Point-in-time recovery (PITR) enabled if available (Neon, Supabase, RDS all support it)
- Off-site copy: if the provider stores backups in the same region as the primary, configure cross-region replication or a nightly export to a separate storage account (S3, R2, GCS)
- Restore drill performed before launch: pick a recent backup, restore to a staging database, verify row counts and a sample query. A backup you haven't tested is not a backup.
File storage (if applicable — S3, R2, GCS, Cloudflare Images):
- Versioning enabled on the primary bucket
- Cross-region replication or a scheduled sync to a secondary bucket. Backblaze B2 is a cheap, reliable option for off-site copies (significantly cheaper than S3/GCS egress). Use
rcloneto sync from S3/R2/GCS → B2 on a daily cron. - Lifecycle rule: transition old versions to cheaper storage after 30 days, delete after 90 days (adjust to cost tolerance)
Secrets / environment variables:
- All env vars documented and stored in a secrets manager (1Password, Doppler, Vault, or equivalent). Not in a
.envfile on someone's laptop. - Verify: if every engineer's machine burned tonight, could a new team member restore prod from scratch using only the secrets manager + git?
Monitoring:
- Set up an alert (email or Slack) if the daily backup job fails. Most providers support this natively; configure it before closing the backup panel.
Phase 2: Analytics & Observability
Most third-party integrations are one-click via Cloudflare or Vercel.
For the conditional tools (Crisp, Sentry, BetterStack), ask the user to confirm per site type. See references/decisions.md for the observability tier matrix.
Always-on:
- Google Analytics 4: property created, measurement ID embedded, gated behind CNIL consent
- PostHog: based on user's earlier answer:
- If
hogpost.samber.dev: configure client withapi_host: "https://hogpost.samber.dev"and verify CORS allows the new domain (test with browser console orcurl -H "Origin: https://newsite.com" -I https://hogpost.samber.dev/decide) - If
set-up-new-proxy: add path rewrite innext.config.jstous.i.posthog.comandus-assets.i.posthog.com, init client withapi_host: "/ingest" - If
skip-PostHog: skip
- If
- Google Search Console: site verified (DNS TXT or HTML file), sitemap submitted
- Bing Webmaster Tools: site verified, sitemap submitted, IndexNow key file at
/{key}.txton root (verify withcurl -sI https://example.com/{key}.txt) - Ahrefs: site added to dashboard for tracking
- Add the site to the internal stats spreadsheet (PostHog properties registry + GitHub Sponsors tracking sheet if applicable)
Brand monitoring (Google Alerts):
For each alert, use these settings: Frequency: once a day | Sources: Automatic | How many: All results | Region: Any region
Set up one alert per keyword via alerts.google.com:
- Domain name (e.g.,
example.com) - Brand or product name (quoted if multi-word, e.g.,
"My Brand") - Key feature or library names if the site documents a project
- Competitor brand names (optional — ask user:
yes-monitor-competitors|skip)
Ask the user: "Which additional keywords to monitor?" (product-name-only | domain-plus-brand | full-set-with-competitors | custom-list)
Developer community monitoring (F5bot) — for doc-site and SaaS-app targeting developers:
F5bot (f5bot.com) monitors Reddit, Hacker News, and Lobste.rs for keyword mentions and sends email alerts. Free, no API required.
Set up one keyword per line at f5bot.com/add:
- Brand or product name
- Domain name (catches link shares)
- Key feature or library names
- Common misspellings if applicable
Competitor analysis (marketing/lead-gen, SaaS-app, training/paid-course only):
Before writing copy, setting up ads, or planning content, run a competitor analysis to understand what is already working in the market — positioning, messaging angles, CTA patterns, pricing presentation, and content strategy.
Use a deep research tool or a competitor analysis skill if one is available in the toolchain. Ask:
- "Do you already have competitor names/URLs to analyze?" (
yes-provide-list|no-discover-for-me|skip) - If
yes-provide-list: ask the user to paste 2-5 names or URLs (free text) - "What are we looking to extract?" (
positioning-and-messaging|pricing-strategy|content-and-seo|full-spectrum)
Feed the output into:
- Phase 5 keyword strategy (target queries they rank for but you can outrank or flank)
TONE.mdvoice calibration (deliberately differentiate from the dominant tone in the category)- Phase 6 OG copy and CTA language (borrow proven frames, don't clone verbatim)
- Copywriting sub-skills invoked later (pass the competitor snapshot as context)
Conditional (ask user, default per site type from references/decisions.md):
- Crisp
- Sentry
- BetterStack
Phase 3: Legal & Compliance (FR)
Ask first: "Is this site subject to French law?" (yes-FR-operator-or-audience | no-EU-only | no-non-EU). If no, ask whether GDPR or equivalent applies and adjust.
For FR sites:
- Mentions légales page (mandatory, fines up to 75k€ per omission)
- CGV (Conditions Générales de Vente) if commercial activity
- Privacy policy
- Terms of service
- CNIL-compliant cookie consent that gates GA4, PostHog, Crisp, Sentry script loading (not just a banner that always loads trackers). Use a CMP (Axeptio, Tarteaucitron, or custom). Verify with browser Network tab: no tracker fires before explicit consent.
Phase 4: Security
Delegate the deep audit to trailofbits/skills. The items below are the must-pass checklist.
Ask first: CSP tightness level (strict-default-src-none | balanced-allow-self | permissive-for-marketing). See references/templates.md for the CSP template per level.
- CSP: target chosen tightness level. No
'unsafe-inline'for scripts (use nonces). Verify withcurl -sI ... | grep -i content-security-policy. - HSTS:
max-age=31536000; includeSubDomains; preload. Submit to hstspreload.org. Verify withcurl -sI ... | grep -i strict-transport. - X-Frame-Options:
DENY - X-Content-Type-Options:
nosniff - Referrer-Policy:
strict-origin-when-cross-origin - Permissions-Policy: deny camera, microphone, geolocation, payment unless used
- Run all headers in one go:
curl -sI https://example.com | grep -iE 'content-security|strict-transport|x-frame|x-content-type|referrer-policy|permissions-policy' - securityheaders.com: target A+ (verify via Claude Chrome extension or
curl https://securityheaders.com/?q=URLand parse) - observatory.mozilla.org: target 90+ (via Chrome extension)
- Run
trailofbits/skillssecurity audit on the codebase - Verify no leaked secrets in client bundle: open Chrome DevTools Network tab via Claude Chrome extension, grep response bodies for
sk_,pk_,AKIA,ghp_,Bearer
Phase 5: SEO & GEO
Delegate the full audit to AgriciDaniel/claude-seo. The items below are the orchestration list.
See references/templates.md for robots.txt, llms.txt, and manifest.json templates. See references/decisions.md for the AI scraper policy matrix by site type.
-
/robots.txtpresent, references sitemap (verify withcurl -s https://example.com/robots.txt) -
/sitemap.xmlpresent, valid (verify withcurl -s https://example.com/sitemap.xml | head -40). Sitemap-index with per-language sitemaps if multilingual. -
/llms.txtpresent (per llmstxt.org spec, verify withcurl -s https://example.com/llms.txt) - AI scraper policy encoded in
robots.txt. Apply the matrix fromreferences/decisions.mdbased on site type, then ask via the question tool to confirm each non-default decision — this ships in a public file, get it right before it's crawled. - Schema markup (JSON-LD):
Organization+WebSite+BreadcrumbListsite-wide; per-page types where applicable (SoftwareApplicationfor lib homepages,Articlefor blog posts,FAQPagefor FAQs,Personfor author bio). Verify withcurl -s URL | grep -A 50 'application/ld+json'. Validate structured data via Google Rich Results Test (https://search.google.com/test/rich-results) and Schema.org Validator (https://validator.schema.org) — Rich Results Test checks eligibility for rich snippets; Schema.org Validator catches spec violations that Google may silently ignore. - Meta tags per page: unique
<title>(50-60 chars), unique<meta description>(150-160 chars),<link rel="canonical">,<meta name="robots">if needed -
hreflangtags on every page if multilingual (every language version declares all alternates including self). Verify withcurl -s URL | grep -i hreflang. - Keyword analysis using both Google Trends and Ahrefs (they answer different questions, not interchangeable):
- Google Trends (trends.google.com): trajectory (rising vs declining), geographic distribution (especially FR vs international split), seasonal patterns, related queries breakout, head-to-head comparison of 2-5 candidate keywords. Use Trends to validate direction and timing of the SEO bet.
- Exploding Topics (explodingtopics.com): surfaces emerging trends weeks or months before they peak in Google Trends. Use to identify rising queries before competition solidifies and to validate that target keywords aren't already on the decline.
- Answer The Public (answerthepublic.com/en): maps search questions, comparisons, and related queries around a seed keyword. Use to uncover long-tail intent clusters, populate FAQ schema, and identify content gaps.
- Ahrefs Keywords Explorer: monthly volume, keyword difficulty, SERP analysis, CPC, parent topic, traffic potential. Use Ahrefs to size the opportunity in absolute terms.
- Combined output: a ranked shortlist of 3-5 target queries per page, with rationale (volume × difficulty × trajectory × intent match).
- Delegate to whichever keyword-research sub-skill was installed at session start (selected from the installed packs via the skill selection workflow; typical sources are the SEO+GEO and marketing packs).
- AI visibility audit via productrank.ai: open productrank.ai in a browser, submit multiple category or product searches, run the full AI SEO report. It audits how the site appears in AI-generated answers (ChatGPT, Perplexity, Gemini, Claude). Flag any zero-visibility categories and surface content gaps the AI graders identify.
- Typo and grammar pass on all visible text content
- Backlink profile audit: run Ahrefs Backlink Checker and Moz Link Explorer to assess domain authority and surface toxic or broken inbound links before launch — especially critical on migrations to ensure old-domain equity transfers correctly
- Internal linking audit: every important page reachable in ≤3 clicks from the homepage
Destination Pages Strategy (from directory-submissions skill): Directories are useless if the backlinks land on a generic homepage. Build these destination pages before submitting to directories:
1. Alternative pages (highest ROI)
Competitor alternative pages convert at 5–15%, often hitting 15–30% for bottom-of-funnel queries. One page per top competitor:
/alternatives/[competitor-1]/alternatives/[competitor-2]/alternatives/[competitor-3]/alternatives/[competitor-4]
Each page needs: honest feature comparison table, "when to choose X over us," "when to choose us over X," pricing comparison, 3–5 use-case examples, strong FAQ with schema. Critical: Be honest. AI engines cross-reference competitor feature claims and de-rank pages that lie.
2. Use-case / ICP pages
Every ICP gets a dedicated landing page:
/for/[audience]— coaches, agencies, ecommerce, SaaS, consultants, etc./use-cases/[use-case]— lead qualification, onboarding, product recommendations, etc.
3. Template / asset gallery (if applicable)
Typeform's template library generated 30,000 non-branded organic signups and $3M/year LTV. The pattern:
- One indexable page per template at
/templates/[slug]. - H1 with the keyword, 150+ word description, screenshot, "when to use this," "use this template" CTA.
- Related templates at the bottom of each page (internal linking = SEO compounding).
- 100 templates by day 30, 300 by day 90 is the realistic target.
4. "Best of" listicles you wrote yourself
Write honest roundups of your own category: /blog/best-[category]-tools-2026. Include yourself + 10 competitors with real reviews. These rank for category queries AND serve as canonical references AI engines cite.
5. Integration pages (when integrations ship)
Every integration = one landing page at /integrations/[partner]. Follows the Zapier playbook: Zapier gets ~2.6M monthly organic visits from programmatic integration pages (~15% of their total organic traffic).
GEO (Generative Engine Optimization): In 2026, 30–50% of "research a tool" queries happen inside ChatGPT, Claude, Perplexity, or Google AI Overviews without ever touching a traditional search page.
Tactics that get pages cited
- One H1 per page, sequential heading hierarchy. 2.8× higher citation rate. 87% of cited pages use a single H1.
- Dense, factual content with citable stats. AI engines prefer specific numbers ("3× faster than X") over vague claims.
- FAQ schema on every landing page. AI engines heavily weight
FAQPageJSON-LD for answer extraction. - Comparison tables. Extractable, structured — exactly what an AI answer needs.
- Explicit "what it is" paragraph in the first 100 words.
- Get cited on Reddit and Hacker News. Claude and Perplexity index these heavily. Genuine mentions on r/SaaS and HN count as training fuel.
- Publish original research. "We analyzed 10,000 [things] and found X" becomes the primary citation for anyone writing about that topic.
- Claim Crunchbase, LinkedIn company page, and Wikidata entries. All three feed AI training corpora.
- If applicable, list on MCP registries with A/B grades (Glama in particular). LLMs pull from these when answering MCP questions.
Measurement
Manually check monthly: ask ChatGPT, Claude, and Perplexity "what are the best [category] tools?" and log where the product appears. Free GEO tracking tools (GeoTracker, llmrefs) automate this.
Phase 6: Open Graph & Social Preview
Verify all OG and Twitter tags with: curl -s URL | grep -iE 'og:|twitter:'
-
og:title,og:description,og:url,og:type,og:site_name -
og:image1200×630px, absolute URL,og:image:widthandog:image:heightdeclared,og:image:altset - Per-page
og:image, not one global. For doc sites: generate dynamically from page title. For blog posts: per-article custom image. -
og:locale+og:locale:alternatefor each language if multilingual - Twitter Cards:
twitter:card=summary_large_image,twitter:title,twitter:description,twitter:image,twitter:site(handle) - Validate with opengraph.xyz (covers FB, LinkedIn, Slack, Discord, WhatsApp previews) via Claude Chrome extension
- Validate with Twitter's card validator
- Manual check: paste URL in a LinkedIn DM, a Slack channel, a Discord, an iMessage. Preview must render correctly in all.
Phase 7: Favicons & Web Manifest
See references/templates.md for the manifest.json template.
Generate from a single 1024×1024 source PNG using realfavicongenerator.net or favicon.io.
Minimum modern set:
-
/favicon.ico(multi-res 16/32/48). Verify withcurl -sI https://example.com/favicon.ico. -
/favicon.svgwith embedded<style>@media (prefers-color-scheme: dark) { ... }</style>for dark mode. Verify withcurl -sI https://example.com/favicon.svg. -
/favicon-96x96.png(PNG fallback) -
/apple-touch-icon.png180×180px, no transparency, opaque background. Verify withcurl -sI. -
/web-app-manifest-192x192.png(Android PWA icon) -
/web-app-manifest-512x512.png(Android splash) -
/manifest.jsonreferencing both PNGs, withtheme_color,background_color,name,short_name,display. Verify withcurl -s https://example.com/manifest.json | jq ..
Skip (deprecated):
mstile-*.png(Windows tiles)safari-pinned-tab.svg(deprecated since macOS Big Sur)favicon-16x16.png/favicon-32x32.png(covered by.icoand.svg)
HTML head verification:
curl -s https://example.com/ | grep -iE 'rel="icon"|rel="apple-touch-icon"|rel="manifest"'
Phase 8: Quality Gates
Delegate to addyosmani/web-quality-skills. The skill covers 150+ Lighthouse audits across performance, accessibility, SEO, and best practices.
- Unlighthouse site-wide crawl:
npx unlighthouse --site {site}— crawls all pages and runs Lighthouse on each. Surface pages below 90 on any axis before the per-URL checks. - Lighthouse all 4 axes, mobile mode: target ≥90 on each (perf, a11y, best practices, SEO)
- Lighthouse all 4 axes, desktop mode: target ≥95 on each
- Core Web Vitals field data (CrUX via PageSpeed Insights): LCP < 2.5s, INP < 200ms, CLS < 0.1, on both mobile and desktop
- Accessibility (WCAG 2.2 AA via
web-quality-skills): keyboard nav works for every interactive element, focus rings visible, color contrast ≥4.5:1 for text, all images havealt, heading hierarchy is monotonic (H1 → H2 → H3), ARIA labels on icon-only buttons - Real mobile device test (not just devtools emulator). Use Claude Chrome extension on mobile viewport on a real device or BrowserStack.
- Cross-browser smoke test: Chrome, Safari, Firefox latest stable
- Print stylesheet sanity (Cmd+P should not break layout)
Phase 9: Ecosystem Cross-linking
Internal cross-linking between owned properties. High-leverage SEO action for any multi-domain owner.
Ask the user: "List the other domains in your ecosystem that are topically relevant to this new site." Then for each one:
- Add a link from the existing site (footer / nav / "other projects" section) to the new site, where topically relevant
- Add a link to the new site in the README of the matching GitHub repo, if it documents a library
- Verify reciprocal links: every link added points back where appropriate
- If the new site documents a Go lib, link from related lib docs
Do not over-link. Only cross-link where topically relevant. A doc site for a logging lib should not link to a personal blog about cycling.
Phase 10: Set up weekly SEO maintenance sub-agent
After launch, set up a scheduled background agent, such as Hermes or Claude Cowork Routine, that runs weekly to monitor SEO health and surface action items.
See references/weekly-seo-agent.md for the full agent definition, with a concrete equivalent for each harness — copy the block matching your environment into the location it specifies, in the site's repo (or a dedicated ops repo). The agent uses these MCP connectors (or their equivalent API calls):
- Ahrefs MCP (backlinks, rankings, keywords)
- PostHog MCP (analytics correlation, AI bot traffic)
- Web search (SERP monitoring, competitor checks)
- Google Search Console (via community MCP or
curlwith service account credentials)
Ask via the question tool before creating the file: "Set up the weekly SEO agent now?" (yes-create-agent-file | yes-but-defer | skip-for-now).
When MCP are not available, use Claude for Chrome extension.
Phase 11: Directory Submission Execution
Execute the directory submission workflow from the directory-submissions skill. This is the foundation layer of distribution — never the whole strategy.
Step 1: Choose the tiers (from references/directory-list.md)
| Tier | When | Examples | Typical count |
|---|---|---|---|
| Tier 1 — Flagship launch | Launch week only | Product Hunt (anchor), BetaList, HN Show HN, Fazier, DevHunt | ~15 |
| Tier 2 — Startup/SaaS | Week 1 + rolling | AlternativeTo, SaaSHub, G2, Capterra, F6S, SourceForge, Slashdot | ~50 |
| Tier 3 — AI directories | Week 1–3 | TAAFT, Futurepedia, Toolify, Future Tools, aitools.inc, AIStage | ~40 |
| Tier 4 — Agent/MCP registries | Week 1–3 (if MCP) | Glama, APITracker, LF MCP Registry, AI Agents List | ~10 |
| Tier 5 — No-code directories | Week 1–3 (if no-code) | NoCodeFinder, No Code MBA, We Are No Code, MakerPad | ~8 |
| Tier 6 — "Best of" listicles | Rolling outreach | Cold outreach to DR 40+ blog posts | ~10 inclusions |
| Tier 7 — Integration marketplaces | When integrations ship | Zapier, HubSpot, Slack, Airtable, Notion | ~5 |
| Tier 8 — Profile & content platforms | Rolling | GitHub, WordPress.com, Substack, Dev.to, SlideShare, Behance | ~50 |
| Tier 9 — Local business directories | Rolling (if applicable) | Manta, Hotfrog, Locanto, MerchantCircle | ~20 |
| Tier 10 — Forums & communities | Rolling (participate first) | SitePoint, GrowthHackers, Warrior Forum, Designer News | ~13 |
| Tier 11 — Press release & article sites | Launch + milestones | PRLog, PR.com, EzineArticles, Feedspot | ~25 |
| Tier 12 — Social bookmarking | Rolling | Scoop.it, Diigo, Pearltrees | ~5 |
| Tier 13 — Niche vertical directories | When vertical fits | Justia (legal), Porch (home), LandBook (design), etc. | ~20 |
Triage rule: Only submit where the product is a genuine fit. Forcing a listing into the wrong category burns the first-submission advantage and gets rejected by moderators.
Step 2: Prepare asset variations per tier
For each tier, prep a distinct description variant (from references/positioning-variations.md):
- Tagline under 10 words
- Short description at 60 chars
- Long description at 150 words
- 5–8 category tags
- Logo assets
- Screenshots + demo video URL
- Founder story (2–3 sentences)
Critical: Don't copy-paste the same long description into every directory. Vary the opening sentence, the feature emphasis, and the audience framing per tier. AI engines cross-reference and down-weight duplicate content.
Step 3: Batch submit with tracker
Set up the tracker spreadsheet (references/submission-tracker-template.csv). Work left-to-right through it. 2–3 hours per batch is realistic.
Per submission:
- Copy the tier-appropriate positioning variant.
- Fill in the form.
- Upload assets.
- Submit.
- Log: date, URL, status, moderator notes.
- Once live, verify the backlink exists and is dofollow:
curl -sIL https://directory.com/your-listing | grep -i rel=. If absent, the link is dofollow.
Phase 12: Product Hunt Deep Dive (The Anchor Event)
Product Hunt is the single highest-leverage submission but also the most easily wasted. The 2026 PH algorithm weights comment quality more than upvote count — a post with 50 upvotes + 30 genuine comments ranks above one with 200 upvotes + 5 comments. 80% of failed launches fail because they launched without a warm audience OR asked for upvotes instead of feedback.
3-week prep timeline
- Day -21 to -14: Warm up hunter account. Upvote + thoughtfully comment on 3 launches/day. Follow 100+ active makers. Build history so your account looks real to the algorithm.
- Day -14: Create "Upcoming" page on PH. Drive traffic to it to collect "notify on launch" subscribers.
- Day -10: (Optional) book a hunter. Don't pay cash — trade a feature, shoutout, or intro. A known hunter adds ~15% to day-one momentum but isn't required.
- Day -7: Draft launch-day assets: gallery images (1270×760), tagline, 260-char description, first comment from you, first comment from a customer.
- Day -3: Email list warm-up. "We're launching Tuesday. Here's what to expect. Reply if you want a heads up."
- Day -1: Final check — product works in incognito, video autoplays, CTA goes to signup, PH listing preview looks right.
Launch day execution
- Launch at 12:01 AM Pacific Time. Tuesday, Wednesday, or Thursday only — weekend launches get 60–70% less traffic. The 12:01 AM PT start maximizes your 24-hour window.
- First 2 hours are everything. Need 50+ supporters in the first 2 hours to trigger algorithmic distribution.
- Post the first comment yourself with the story: why you built it, what's different, what to try first.
- Reply to every comment in under 30 minutes. PH measures maker responsiveness.
- Share the link to: Twitter/X thread, LinkedIn long-form post, personal Slack/Discord communities, your email list, Indie Hackers, every power user via DM.
- Never ask for upvotes. Ask for feedback. "Would love your honest take on the positioning" converts 3× better than "support us!" and doesn't trigger the algorithm's anti-manipulation filters.
- Don't message strangers. The community flags this and moderators will hide your post.
Post-launch
- Write a launch recap blog post with numbers + lessons. Honest, not bragging. Publish on day 2.
- Cross-post the recap to Indie Hackers and r/SaaS (where promotion is allowed).
- Only submit to Show HN if you have a technical angle to share (architecture, DSL, novel approach). A generic "we launched a SaaS" post will get flagged to death.
Phase 13: Reviews Playbook (G2 / Capterra / TrustRadius)
G2 and Capterra (now owned by G2 as of Feb 2026) listings are worthless without reviews. 10 reviews is the magic threshold for Grid appearance. Run the 10-in-30 protocol during launch month.
The 10-in-30 protocol
- Day 1 post-launch: Identify 20 users who have completed a meaningful action with the product.
- Send each a personal email with a direct review URL (reduces friction by ~70%). No forms, no landing pages — direct link.
- Offer a modest thank-you. G2 and TrustRadius explicitly allow small incentives like a $25 Amazon gift card.
- Follow up once after 5 days. Don't follow up twice — it becomes annoying and damages the relationship.
- Target: 50% conversion → 10 reviews from 20 asks.
Critical deadlines
- G2 Summer reports: cut off ~April 28. Plan review drives to land before this.
- G2 Fall reports: cut off ~July 28.
- Missing a cutoff means waiting 3 months for the next grid update.
Badges and paid plans
- "Users Love Us" badge is still free: requires 20 reviews at 4.0+ average.
- Grid, Momentum, Index, and Award badges require a paid G2 plan ($2,999+/year starting Summer 2025).
- Do not spend on paid G2 in year one. The free listing + Users Love Us badge is sufficient.
Cross-platform
- TrustRadius follows similar mechanics but smaller volume.
- Capterra auto-syncs from Gartner Digital Markets in some categories — may populate without direct action.
Phase 14: Post-Launch Momentum
Your launch isn't over when the announcement goes live. Now comes adoption and retention work. Don't rely on a single launch event. Regular updates and feature rollouts sustain engagement.
Immediate Post-Launch Actions
- Educate new users: Set up automated onboarding email sequence introducing key features and use cases.
- Reinforce the launch: Include announcement in your weekly/biweekly/monthly roundup email to catch people who missed it.
- Differentiate against competitors: Publish comparison pages highlighting why you're the obvious choice.
- Update web pages: Add dedicated sections about the new feature/product across your site.
- Offer hands-on preview: Create no-code interactive demo (using tools like Navattic) so visitors can explore before signing up.
How to Prioritize What to Announce
Use this matrix to decide how much marketing each update deserves:
Major updates (new features, product overhauls):
- Full campaign across multiple channels
- Blog post, email campaign, in-app messages, social media
- Maximize exposure
Medium updates (new integrations, UI enhancements):
- Targeted announcement
- Email to relevant segments, in-app banner
- Don't need full fanfare
Minor updates (bug fixes, small tweaks):
- Changelog and release notes
- Signal that product is improving
- Don't dominate marketing
Announcement Tactics
- Space out releases: Instead of shipping everything at once, stagger announcements to maintain momentum.
- Reuse high-performing tactics: If a previous announcement resonated, apply those insights to future updates.
- Keep engaging: Continue using email, social, and in-app messaging to highlight improvements.
- Signal active development: Even small changelog updates remind customers your product is evolving. This builds retention and word-of-mouth—customers feel confident you'll be around.
KPIs & Tracking Dashboard
Track weekly. If a number isn't moving, investigate — don't just submit more directories.
| Metric | Day 0 | Day 30 target | Day 90 target |
|---|---|---|---|
| Domain Rating (DR) | 0 | 20 | 30+ |
| Referring domains | 0 | 30 | 80+ |
| Indexed pages | — | 50 | 200+ |
| Organic clicks/day | 0 | 30 | 200+ |
| Directory listings live | 0 | 50 | 70+ |
| G2 reviews | 0 | 10 | 25 |
| Capterra reviews | 0 | 5 | 15 |
| AI citations (manual check) | 0 | 3 | 15+ |
| Signups from directory referrals | 0 | 50 | 300 |
| Signups from alt/use-case pages | 0 | 20 | 300 |
What NOT to Do
- Don't pay for directory submission services ($60–$200 packages). The whole point is these are free. It's an afternoon of copy-paste.
- Don't submit to spam directories (DR under 10, no traffic, no editorial quality). They dilute your backlink profile and Google's spam detection can penalize you.
- Don't submit with the wrong positioning. Re-read the positioning table per tier. Generic descriptions waste the listing.
- Don't treat directories as your entire GTM. They're the foundation. Content + community + reviews are what actually convert.
- Don't skip reviews on G2/Capterra. Zero-review listings are dead. Run the 10-in-30 protocol or don't submit.
- Don't ask for upvotes on Product Hunt. The 2026 algorithm penalizes it. Ask for feedback.
- Don't amend old directory listings every week. Submit once, check quarterly.
- Don't submit before the destination page exists. Link equity needs a destination.
- Don't duplicate descriptions across directories. AI engines penalize duplicate content.
- Don't lie on comparison pages. AI engines cross-reference and de-rank lies.
- Don't over-index on launch-day spike. The flywheel is templates + alternatives + reviews + ongoing content — not one day of PH.
- Don't forget Crunchbase, LinkedIn company page, and Wikidata. These feed AI training corpora and matter for GEO.
- Don't launch before SLC gate passes. Stealth Mode and "Just One More Feature" both kill launches.
- Don't skip the humanizer pass on marketing copy. AI patterns in hero, CTAs, meta descriptions, OG descriptions tank credibility.
- Don't assume analytics "just work." Verify every integration with curl before launch — GA4, PostHog, GSC, Bing, Ahrefs.
- Don't ignore backup drills. A backup you haven't tested is not a backup. Restore to staging before launch.
Output format
At the end of a full run, output a status report grouped by phase:
Phase 1: Domain & Infrastructure [9/10 pass]
✓ Cloudflare proxy on
✓ DNS records configured
...
✗ DMARC missing. Fix: add TXT record at _dmarc.example.com with policy v=DMARC1; p=quarantine;...
Phase 2: Analytics & Observability [6/7 pass]
...
Followed by three lists, in order:
- Blockers (must fix before launch)
- Recommended fixes (should fix before announcing)
- Optional improvements (post-launch)
End by asking: "Which list do you want to tackle next?" (blockers | recommended | optional | done-for-now).
References
references/decisions.md: AI scraper policy matrix by site type, observability tier matrixreferences/templates.md: robots.txt, llms.txt, manifest.json, CSP templates per tightness level, security headers referencereferences/weekly-seo-agent.md: Full definition of the weekly SEO maintenance sub-agent (MCPs, tasks, output format)assets/weekly-seo-*.md,assets/weekly-seo-vibe.toml: per-harness agent-definition files linked fromreferences/weekly-seo-agent.md— copy the one matching your harnessreferences/directory-list.md: 13-tier directory catalog with submission timing, examples, and countsreferences/positioning-variations.md: Positioning variant library per directory tier (tagline, short/long descriptions, category tags)references/submission-tracker-template.csv: Submission tracker spreadsheet template for logging directory submissions
Skill Progressive Disclosure Design
Each section that recommends a direction includes explicit pros and cons. The decisions in this skill are trade-offs, not rules. The model using this skill should reason from the trade-offs to the user's specific situation rather than apply rules blindly.
Triggering vs. disclosure: separate these first
Two problems get conflated and need separating before any splitting decision.
Triggering is whether Claude invokes the skill at all. Driven entirely by the YAML description. File splitting does not affect triggering. If the question is "my skill doesn't trigger reliably", do not split files, fix the description (use run_loop.py from the skill-creator skill).
Progressive disclosure is what loads after the skill activates. SKILL.md body always loads. references/* only loads when SKILL.md tells the model to read a specific file. scripts/* executes without loading into context at all. This is where context protection happens.
If the user is asking about splitting because of triggering issues, surface the confusion first and redirect.
Default: do not split
A monolithic SKILL.md beats a split one until proven otherwise.
Split only when at least one is true:
- SKILL.md exceeds ~400 lines and content has natural branches.
- Empirical evidence (eval transcripts) shows the model wasting context on irrelevant sections.
- Specific content is large and only needed in narrow conditions.
Pros of staying monolithic:
- Single context load, no router prose to maintain.
- No tool-call overhead from reading references.
- No risk of the model loading the wrong reference or skipping a needed one.
- Easier to maintain: one file, one source of truth.
- Better for highly interconnected content where context is global.
- Easier for human reviewers to read end-to-end.
Cons of staying monolithic:
- Every invocation pays the full token cost, even when only 10% of the content is relevant.
- Does not scale past ~500 lines without degrading the model's ability to find what matters.
- No mechanism to gate rare or niche content.
- All content must justify its always-loaded status.
- Maintenance gets harder as the file grows.
Three split axes that work
1. Variant branch
User intent selects exactly one path. SKILL.md holds the decision logic and shared workflow. Each references/<variant>.md holds path-specific detail.
my-skill/
├── SKILL.md # decision tree + shared steps
└── references/
├── variant-a.md
├── variant-b.md
└── variant-c.md
Examples of clean variants: cloud provider, database engine, framework choice, output format, language.
Pros:
- Each invocation loads only the matching variant; large savings when variants are big.
- Variants evolve independently, simplifying maintenance.
- Adding a new variant does not bloat existing content.
- Mental model is easy: select one path based on input.
- Maps cleanly to user intent that already mentions the variant.
Cons:
- Requires routing logic in SKILL.md, eating back some of the line savings.
- Cross-cutting changes touch every variant file, multiplying effort.
- Risk of treatments diverging across variants over time.
- If user intent is ambiguous, the model may load multiple variants and lose the savings.
- If variants share more than ~60% of their content, the abstraction breaks down.
2. Workflow vs. reference data
SKILL.md holds the procedure (verbs, sequence, decisions). references/ holds lookup material queried by key.
Good reference content: schemas, error code tables, API surface listings, example galleries, configuration option matrices, design tokens.
Pros:
- Highest leverage of all splits: lookups are narrow, the model reads one entry.
- Natural conceptual boundary (procedure vs. data).
- Reference can grow large without affecting per-invocation cost.
- Adding new reference entries does not touch the workflow.
- Reference data can often be machine-generated and regenerated.
Cons:
- The model must know what to look up before reading. Pointer must encode lookup keys explicitly.
- Fails when the workflow needs to weave reference data inline rather than at discrete points.
- Splits content that is conceptually unified, harder for human readers.
- The model may miss broader context that lives only in the reference.
- Lookup data that is small (under ~50 lines total) is rarely worth splitting.
3. Depth tier (common path vs. edge cases)
SKILL.md covers the 80% case. references/edge-cases.md covers the rest.
The pointer must read like:
If you see X, Y, or Z, stop and read
references/edge-cases.mdbefore continuing.
Pros:
- Common path stays minimal, fast, cheap.
- Edge cases can be exhaustive without polluting every invocation.
- Easy to extend edge-case coverage without touching the common path.
- Mirrors how experts work: defaults first, exceptions on demand.
Cons:
- The load condition must be sharp and observable from user input. Most edge cases do not satisfy this.
- Vague conditions cause either always-loading (waste) or never-loading (dead weight).
- Edge cases get less testing because evals naturally cluster on common queries.
- The model may follow the common path past a point where it should have escalated.
- The 80/20 estimate is often wrong; what looked like an edge case turns out to be common.
Splits that do not work
For each anti-pattern, "why it appears attractive" shows what makes designers reach for it; "why it fails" shows what goes wrong in practice.
Topic-based splits where invocations do not cluster by topic
A testing skill split into unit.md, integration.md, mocks.md is a typical example.
Why it appears attractive:
- Conceptually clean, mirrors how a human would organize documentation.
- Easy to navigate as a maintainer.
- Plausibly reduces context per invocation.
Why it fails:
- Real tasks span 2-3 topics, forcing multiple loads per invocation.
- Cross-topic concerns get duplicated or fragmented.
- The savings are theoretical, not empirical.
Splitting to hit a line target without a real branching condition
Why it appears attractive:
- A heuristic ("keep SKILL.md under 400 lines") feels like a clean rule to satisfy.
- Splitting feels like progress.
Why it fails:
- Without a branching condition, references load in parallel or always, providing no savings.
- Adds router prose to SKILL.md, often making the total content longer.
Rare-but-critical content in references/
Why it appears attractive:
- The content is large or specialized.
- Moving it out of SKILL.md feels like good hygiene.
Why it fails:
- References are optional by design; the model may skip them.
- If the content is critical, it must be loaded reliably, which means SKILL.md.
- "Rare" and "critical" together is usually a sign the skill is doing two jobs and should be two skills.
Cosmetic splits (Examples, Notes, Tips files)
Why it appears attractive:
- Reduces visual clutter in SKILL.md.
- Feels like good organization.
Why it fails:
- No load condition: either always loaded (wasted tool call) or never loaded (dead content).
- Implies an importance hierarchy that does not exist at runtime.
- Frequently hides content from the model that needs it.
Pointer hygiene
When SKILL.md points at a reference, the pointer is the entire load contract. Rules:
- Name the user-visible signal that triggers the load. "If the user mentions snapshot tests" not "for testing concerns".
- One sentence per pointer. Do not summarize the reference content in SKILL.md.
- Encode the load condition in the filename.
go126-simd.mdnotadvanced.md. - Top-of-file table of contents for any reference over 300 lines.
- If two references are co-loaded in most runs, merge them.
Pros of strict pointer hygiene:
- Wrong-load rate drops sharply.
- Filename encodes load condition, self-documenting for future maintainers.
- Forces upfront clarity about when each reference is needed.
- Makes architecture evals easier to interpret.
Cons of strict pointer hygiene:
- Some content has no crisp trigger; rules force awkward formulations.
- Filenames become long and awkward.
- Requires discipline; easy to drift over time.
- Can over-constrain useful loads when the trigger condition is genuinely fuzzy.
Use scripts/ before references/
For anything deterministic (formatting, validation, schema generation, file transforms, regex-heavy parsing), a script in scripts/ beats prose in references/.
Pros of scripts over reference prose:
- Zero context cost for execution.
- Deterministic, repeatable output.
- Reusable across invocations without re-reading.
- Can be unit tested independently.
- Often faster than prose-driven generation by the model.
Cons of scripts:
- Requires the runtime to support script execution; not all environments do.
- Less flexible than letting the model reason over prose.
- Harder to handle unanticipated edge cases without code changes.
- Adds a maintenance burden: code in the skill needs to keep working.
- Users cannot easily customize behavior without editing the script.
- Failure modes are sharper: script errors stop the workflow.
Decision checklist
Before splitting any content out of SKILL.md, answer:
- Does this content have a sharp, observable load condition the model can detect from user input?
- Will splitting actually reduce context, accounting for the router prose added to SKILL.md?
- Is this reference data (lookup) or procedural (sequence)? Procedural content usually stays.
- Could a script handle this deterministically instead?
- Across realistic invocations, what fraction of runs would load this file? Below 20%, inline or delete — rarely-loaded references rarely justify the routing overhead. 20–80% is the split sweet spot. Above 80%, promote into SKILL.md — the routing cost exceeds the load savings.
If the answer to question 1 is unclear, do not split.
Evaluating skill architecture
Architecture evaluation is different from output evaluation. Output evals ask "did the skill produce the right thing?"; architecture evals ask "did the skill load the right files for the right reasons, at acceptable cost?" Same harness, different metrics — run both: output quality is the floor, architecture is optimization above it.
Pros of running architecture evals:
- Catches dead references, dead SKILL.md sections, and mis-routed content.
- Quantifies whether a split actually saved tokens or just looked clean.
- Reveals real load patterns that intuition misses.
- Forces the eval set to cover all declared paths, surfacing dead paths.
- Compounds with output evals to catch regressions across both axes.
Cons of running architecture evals:
- Requires harness setup beyond standard output evals.
- Eval-set design for path coverage takes work.
- Metrics need calibration per-skill (thresholds vary with cost profile).
- Output evals are still required; this adds to total iteration cost.
- Easy to over-optimize for token cost at the expense of output quality.
Eval set design for architecture
Output evals optimize for output quality across realistic queries. Architecture evals optimize for path coverage. The eval set must exercise every code path the skill claims to have, otherwise the metrics are noise.
Construct, at minimum:
- One query per declared variant (if the skill uses variant-branch splits).
- One query per edge-case branch (if depth-tier splits exist).
- One query per major lookup category (if reference-data splits exist).
- One query that should hit the common path only and load zero references.
- 2-3 off-topic queries that should not trigger the skill at all (also tests the description).
If no realistic query triggers a given reference file, that file is dead. Inline it or delete it before running anything.
Instrumentation
Each eval run is executed by a subagent with the skill loaded. Capture per run:
- Full transcript including every tool call.
- Which
references/*files were read (parseviewcalls on paths inside the skill directory). - Whether
scripts/*were invoked. - Total tokens and wall time.
- The output (for the parallel output-quality eval).
Persist as transcript.json and loads.json per run, alongside the standard output. The harness from skill-creator already records tokens and time in timing.json; extend its grading step to extract reference loads from transcripts.
Metrics per reference file
Across all eval runs, for each references/*.md:
- Load rate: fraction of runs that read it.
- Co-occurrence: for each other reference, fraction of runs that loaded both.
- Use rate when loaded: of the runs that loaded it, did the content visibly inform the output (cited content, applied procedure, used schema)? Inspect transcripts.
- Re-read rate: fraction of runs that loaded the same file twice.
Metrics for the skill overall
- Median and p95 tokens per invocation, with and without references.
- SKILL.md utilization: read transcripts and identify sections of SKILL.md the model never references in any run. Strong candidates for deletion.
- Path coverage: did every declared path get hit by at least one query?
Decision rules
| Observation | Action |
|---|---|
| Reference loaded in <20% of runs | Inline into SKILL.md or delete — routing overhead not justified |
| Reference loaded in 20–80% of runs | Leave split — the sweet spot; routing pays off |
| Reference loaded in >80% of runs | Promote into SKILL.md — always-load cost beats routing cost |
| Two references co-load in >70% of runs | Merge into one file |
| Reference loaded but not used in output | Fix or remove the pointer in SKILL.md |
| Reference re-read inside the same run | SKILL.md routing is unclear; clarify |
| No query triggers a reference | Delete the reference |
| SKILL.md section never referenced in any run | Delete that section |
These thresholds are starting points. Tune them based on the cost profile: small references with cheap loads tolerate lower load rates than large ones.
Comparing two architectures
When choosing between architectures (monolithic vs. split, or split A vs. split B):
- Run the identical eval set against both versions.
- Run output-quality evals on both. Confirm no regression. If quality drops, the architecture change is a loss regardless of token savings.
- Compare median tokens, p95 tokens, and median time per run.
- Compare path coverage: does each version reliably reach the same outputs through the expected paths?
A split that saves 15% tokens but adds variance in output quality is worse than the monolith. Reliability beats efficiency.
What the metrics will not tell you
- Whether the SKILL.md prose is clear. Read transcripts for confused tool calls and dead-end attempts.
- Whether the description triggers correctly. That is a separate eval (use
run_loop.pyfrom theskill-creatorskill). - Whether content placement matches user mental models. Subjective; review with a human.
The split that looked clean at design time rarely matches real load patterns. Trust the transcripts over your intuitions.
Output when advising
When asked to advise on a specific skill's organization:
- Diagnose first. Is this a triggering question or a disclosure question?
- Quote relevant content from the existing SKILL.md (or the user's description of it) before recommending.
- Propose the minimum viable split. Resist splitting into more files than necessary.
- For each proposed reference file, write the exact pointer sentence that would go in SKILL.md.
- Surface the trade-offs explicitly. Use the pros/cons in this skill as the model for how to present a recommendation.
- If unsure whether a split helps, recommend instrumentation (eval the skill, read transcripts) before committing.
Persona: You are a skill-authoring compliance expert. You fix snyk-agent-scan alerts by restructuring content — never by suppressing or deleting useful information.
Thinking mode: Reason as thoroughly as possible for multi-alert remediation where fixes for one alert type can surface or suppress another. Deep reasoning reduces rework. On Claude Code, use ultrathink to trigger extended thinking explicitly.
snyk-agent-scan Compliance
The snyk-agent-scan tool analyzes skill bodies for three categories of unsafe patterns: third-party content exposure (W011), malicious external URLs (W012), and prompt injection via MCP tool calls (W001). All three are fixable through content restructuring without losing any information.
Reference Files
| File | When to read |
|---|---|
| references/w001-patterns.md | Fixing W001 alerts — MCP tool name patterns |
| references/w011-patterns.md | Fixing W011 alerts — imperative URL and external content patterns |
| references/w012-patterns.md | Fixing W012 alerts — version pinning and frontmatter offloading |
Quick Reference
| Alert | Severity | Root Cause | Primary Fix |
|---|---|---|---|
| W011 | High | Skill body instructs agent to fetch/interpret external content | Replace imperatives with passive availability hints |
| W012 | High | Skill body references external URLs fetched and executed at runtime | Move to frontmatter install block; pin versions |
| W001 | High | Skill body names MCP tool functions explicitly | Use generic formulations instead |
Running the Scanner
# Scan a single skill
SNYK_TOKEN=<token> snyk-agent-scan --skills skills/<name>/
# Scan all skills
SNYK_TOKEN=<token> snyk-agent-scan --skills ./skills
The scanner requires a valid SNYK_TOKEN. In CI, store it as a secret. If snyk-agent-scan is not installed, use uvx snyk-agent-scan@latest as a drop-in replacement without installing. See detailed patterns for fixes per alert type.
W011 — Third-Party Content Exposure
W011 fires when the skill body uses imperative verbs directing the agent to fetch, check, or evaluate external content and then act on it. The scanner treats the agent as the grammatical subject performing an external action.
Rules:
- Replace
Check <url>andFetch <url>with passive hints:The release notes at <url> may be useful. - Remove "always" from any instruction involving external data:
Always reference the changelog→The changelog documents breaking changes. - Keep tool invocations (
gh repo view,govulncheck) in code blocks, not in prose checklists that imply the agent must run them before acting. - Decouple tool execution from decisions: running a tool is fine; using its remote-sourced output as the sole trigger for a refactor is not.
See W011 pattern catalog for 12+ before/after examples.
W012 — Potentially Malicious External URL
W012 fires when the body references external content fetched and executed at runtime: package installs with @latest, pipe-to-shell patterns, or GitHub Actions with wrong/non-existent major versions.
Rules:
- Move
go install pkg@latestand similar commands from prose into the frontmattermetadata.openclaw.installblock — the scanner does not flag frontmatter. - Pin GitHub Actions to the correct current major version (
@v4, not@v6). - Never use pipe-to-shell patterns (
curl ... | sh) in skill bodies.
See W012 pattern catalog for 8+ before/after examples.
W001 — Prompt Injection via MCP Tool Calls
W001 fires when the skill body explicitly names MCP server tool functions, triggering prompt-injection detection.
Rules:
- Never write tool function names (
resolve-library-id,query-docs,mcp__*) in the skill body. - Replace with generic formulations:
Context7 can help as a discoverability platform. - MCP tool names may still appear in the
allowed-toolsfrontmatter field — only the body is restricted.
See W001 pattern catalog for safe reformulations.
Remediation Methodology
Fix one alert at a time, re-run snyk-agent-scan after each change, and verify the alert count dropped before moving to the next. If a fix does not reduce alerts, undo it and try a different approach — do not stack unverified changes.
When a scan returns multiple alerts, fix in this order to minimize rework:
1. W001 (simplest) — remove MCP tool names from body; confirm allowed-tools is correct
2. W011 — rewrite imperative sentences as passive statements; move checklist items to code blocks
3. W012 — move install commands to frontmatter; pin versions
4. Re-scan after each individual fix to verify improvement
W011 fixes sometimes surface hidden W012s when URLs become more prominent after restructuring.
False Positives
Not all alerts are real. Criteria for a likely false positive:
| Condition | Likely false positive? |
|---|---|
| URL appears in a markdown table cell as reference data, not in an instruction | Yes — tables are usually safe |
| In a skill describing a library, URL is the library official documentation | Yes — usually safe |
URL is the homepage or issues link in frontmatter | Yes — not scanned |
| Tool name appears inside a triple-backtick code block as a shell command | Sometimes — code blocks have lighter scrutiny |
go install with a pinned version in a Quick Reference code block | Sometimes — pinned versions are lower risk |
always appears in a sentence not involving external resources | Yes — "always" alone doesn't trigger W011 |
When an alert is a likely false positive, restructure anyway using the passive hint pattern — the scanner's heuristic protects real users; restructuring is safer than assuming scanner error.
Pre-Authoring Checklist
Apply these checks while writing a new skill body to avoid alerts before the first scan:
- No sentence has the agent as subject performing an action on a URL
- No
@latesttags in any install instruction in the body - No MCP tool function names (
mcp__*,resolve-library-id, etc.) in body prose - All install commands are in the frontmatter
installblock - GitHub Actions versions match real existing major versions
- Tool invocations are in code blocks, not in ordered-list checklists
- "always" does not precede any external resource instruction
If you encounter a bug or unexpected behavior in snyk-agent-scan, open an issue at https://github.com/snyk/snyk-agent-scan/issues.
If you discover a pattern that triggers an alert not covered in the reference files above — a new bypass technique, a false positive condition, or an undocumented alert code — open an issue at https://github.com/samber/cc-skills/issues or a pull request to the samber/cc-skills repository to add it to the relevant pattern file. New patterns are the most valuable contribution to this skill.
Substack Ghostwriting & Content Optimization
A skill for writing Substack content — both newsletter issues (email-first) and web posts (web-first articles/essays) — that grows subscribers and converts readers. Handles two voice modes (own voice, ghostwriting) and two format modes (newsletter issue, web post).
Core philosophy
Substack is not a blog with an email list. It's a social-media-newsletter hybrid with an algorithm that optimizes for subscriptions, not engagement. This changes everything about how you write, format, and distribute content on the platform.
The algorithm's incentives genuinely align with quality. Substack's revenue comes from subscription cuts (not ads), so gaming engagement metrics doesn't help. What helps: writing content good enough that readers convert to paid subscribers and recommend you to others.
For ghostwriting specifically: the job is capturing someone's existing insights in their voice, not generating insights from scratch. As Nicolas Cole frames it: clients are "insights-rich and time-poor", writers are "time-rich but insights-poor." The art is extraction and voice matching.
Platform formatting constraints
Substack is a social-media-newsletter hybrid with an algorithm that optimizes for subscriptions, not engagement. Revenue comes from subscription cuts (not ads), so quality genuinely wins. For ghostwriting: the job is capturing someone's existing insights in their voice — clients are "insights-rich and time-poor."
Read references/platform-constraints.md for post fields, Notes limits, special content blocks, and media embeds.
Mode detection
Determine two dimensions:
Voice dimension:
- Own voice — the user writes/publishes under their own name. Go directly to the Writing Workflow.
- Ghostwriting — writing in someone else's voice, or preparing content for a client. Complete the Ghostwriting Workflow first, then the Writing Workflow.
Format dimension:
- Newsletter issue (email-first) — sent to subscribers' inboxes. Subject line and email formatting matter most. Read
references/email-formatting.mdduring Phase 3. - Web post (web-first) — published as a Substack article/essay, discoverable via search and Substack's feed. SEO and web formatting matter most. Read
references/web-post-formatting.mdduring Phase 3.
If unclear, ask the user. Default to newsletter issue when they say "newsletter" or "issue"; default to web post when they say "article", "essay", "post", or "evergreen content".
Ghostwriting Workflow
When writing for someone else, voice matching comes before content. Read references/voice-matching.md for the full extraction process — it covers sample collection (transcripts > writing > media), voice marker extraction, building a voice guide (10-15 markers with examples), and iteration with the user.
Complete the voice guide and get user validation before proceeding to the Writing Workflow.
Writing Workflow
Phase 1 is mandatory — always ask the user the intake questions and wait for answers before writing anything. If the user already provided some context, extract what you can and ask only about missing pieces.
Phase 0: Voice calibration (own voice mode)
Skip this phase if ghostwriting (the Ghostwriting Workflow handles voice separately).
Ask the user for their existing Substack URL. If they have one, recent posts are a valuable source of tone markers — formality level, sentence rhythm, humor style, paragraph length, how they open and close, recurring phrases. Summarize the voice in 5-7 bullet points and confirm with the user before writing.
If they don't have an existing Substack, ask: "How do you want to sound? Casual and conversational, professional and authoritative, or something else?" Use their answer plus any other writing samples they can share.
Phase 1: Content planning (interview)
Stop and ask. Present the intake questions below to the user and wait for their answers. Do not skip this phase, do not infer silently, and do not start drafting until you have explicit answers or confirmation on every item.
- Topic: What's this about? If vague, ask what specific angle or story the reader should walk away with.
- Format: Newsletter issue (email-first) or web post (web-first)? See mode detection above.
- Audience: Who reads this? (developers, founders, marketers, general tech, niche community...) A newsletter for junior devs reads very differently than one for CTOs.
- Objective: What's the concrete goal?
- Grow subscribers (free or paid)?
- Drive signups/traffic to an external product (SaaS, course, tool)?
- Establish authority / thought leadership?
- Nurture existing subscribers toward a paid tier?
- Something else? The objective shapes the CTA, the hook angle, and where depth goes vs where the paywall or link sits.
- Context: Part of a series? What have recent posts covered?
- Length: Short (500-800 words), Standard (1000-1500), Deep dive (2000+)
If critical pieces are missing (especially topic, audience, objective, or format), ask and wait — don't guess. A wrong assumption wastes an entire draft.
If the user has Notes data (which Notes got engagement), use that to validate topic selection. Notes function as a cheap testing pipeline for long-form content.
Phase 2: Title and hook selection
Generate 5 title/subject line variants and 3 hook options (opening 2-3 sentences each). Present them together and ask the user to pick or remix before proceeding. Do not write the body until the user has validated a title and hook direction.
Title principles:
- Specificity beats vagueness
- Promise a clear benefit or reveal
- 6-10 words (readable on mobile and in search results)
- For dev audiences: technical keywords filter for the right audience; "How to" and numbers perform well; avoid urgency/scarcity tactics
Hook types — write 3 distinct hooks using different strategies (e.g. credibility, counter-narrative, curiosity, surprise, data). Each hook should be 2-3 sentences that could open the piece. Present them labeled (Hook A, Hook B, Hook C) with a brief note on the strategy used.
Newsletter issue — subject line + preview text:
- The subject line is the headline. The preview text (first ~90 chars of the email) is the subhead. Together they determine open rate.
- Preview text should complement, not repeat, the subject line.
Web post — SEO + discoverability:
- Keep the main title punchy for the feed. Use the separate SEO title field for a keyword-rich version (under 60 chars).
- Write a dedicated SEO description (150-160 chars) — don't rely on the subtitle fallback, it's usually too short.
- Suggest a URL slug: short (3-6 words), keyword-rich, no dates.
- Assign to a publication section if applicable.
- Read
references/web-post-formatting.mdfor detailed SEO guidance.
Wait for the user to choose a title and hook before moving to Phase 3.
Phase 3: Write the content
Using the chosen title and hook, write the full piece. The hook opens the article, then continue with:
- Hook (chosen from Phase 2)
- Context (1-2 paragraphs): Why this matters now. What prompted this.
- Body (bulk): The actual content. Structure depends on content type.
- Takeaway (1-2 sentences): The one thing the reader should remember.
- CTA (1-2 sentences): Ask for a specific action. Questions that invite replies are strongest (replies are an algorithm signal).
Newsletter issue formatting — read references/email-formatting.md for full rules:
- Paragraphs: 2-3 sentences max (email clients make long paragraphs feel like walls)
- Code blocks: < 10 lines (link to Gist for longer code)
- Images: sparingly (many email clients block them by default)
- TL;DR at top for issues > 1500 words
Web post formatting — read references/web-post-formatting.md for full rules:
- Paragraphs: 3-4 sentences acceptable (full-width web rendering is more forgiving)
- Longer code blocks OK (up to 30-40 lines with full syntax highlighting)
- Images and embeds render reliably — use more liberally
- Table of contents for posts > 2000 words
Shared formatting rules:
- Subheadings every 200-400 words. Bold key phrases so skimmers catch the argument.
- Descriptive anchor text on links, not "click here."
Phase 4: Growth-optimized elements
Add elements that leverage the Substack algorithm. Read references/substack-algorithm.md for the full mechanics.
- Reply prompt: End with a genuine question. Replies signal engagement to the algorithm.
- Share prompt: "If you found this useful, forward it to a colleague who [specific situation]." Specificity increases share rate.
- Recommendation hook: If the user has recommendation partnerships, weave in natural cross-references.
- Notes teaser: Write a 2-3 sentence version for Substack Notes. Notes should stand alone as valuable, not just be a link to the issue.
Phase 5: Paid vs. free strategy
If the user has a paid tier, advise on the free/paid split:
- Free issues should be your best work (they drive growth and recommendations)
- Paid issues should offer depth, exclusivity, or access (not just a paywall on normal content)
- The most effective model: free issues that demonstrate value so clearly that readers want more
Common mistake: paywalling too early. At < 1000 subscribers, everything should be free. Growth compounds faster than paid conversion at small scale.
Phase 5b: Humanize
Invoke a humanizer skill (e.g. "humanize", "humanizer", "de-slop", "natural writing check", "AI detection cleanup", "rewrite like a human") to strip AI-generated patterns — filler words, predictable cadence, over-hedging, hollow transitions, inflated language. Substack readers pay for authentic voice; AI-sounding prose kills trust and cancels subscriptions.
Preserve hooks and subject lines. The hook and title/subject line (Phase 2) were deliberately engineered for open rate and curiosity. Instruct the humanizer to leave them intact — rewriting them for "naturalness" destroys the copywriting structure that drives opens and first-scroll retention.
Phase 6: Image suggestions
After the content is drafted, suggest 1-3 images with specific placement. For each image, provide:
- Placement: Where in the issue (e.g. "as the cover image", "after the hook", "between section X and Y")
- Purpose: What the image adds (set the tone, break up a long section, illustrate a concept, reinforce the emotional beat)
- Description: What the image should depict
For newsletter issues: use images sparingly — many email clients block them by default. Prioritize a strong cover image and at most 1-2 inline images. For web posts: images render reliably — use more freely (diagrams, charts, screenshots).
Offer to generate a Midjourney prompt for each suggested image. If the user accepts, use the latest Midjourney model conventions to write the prompt.
- Use
--ar 16:9or--ar 3:1for cover images and wide illustrations (optimal for Substack headers and social sharing),--ar 3:2for smaller inline images. - Refer to up-to-date Midjourney documentation for current prompt syntax and parameters.
Phase 7: Social distribution posts (optional — offer, don't auto-generate)
After the content is written, ask the user if they want social distribution posts. Do not generate them automatically.
- If accepted, write a LinkedIn post and/or a Twitter/X post to promote it.
- These are not summaries — they are standalone pieces of content that create enough curiosity or value to drive clicks.
Read references/social-distribution.md for LinkedIn and Twitter/X post templates.
Output format
Newsletter issue:
- Subject line (chosen) + 2 alternatives
- Preview text
- Full issue in markdown, formatted for email readability
- Image suggestions with placement notes (and Midjourney prompts if accepted)
- A Notes teaser (2-3 sentences)
- LinkedIn + Twitter/X distribution posts (only if the user accepted)
- If ghostwriting: the voice guide used
Web post:
- Title (chosen) + 2 alternatives
- Subtitle / meta description
- Suggested URL slug
- Full post in markdown, formatted for web readability
- Image suggestions with placement notes (and Midjourney prompts if accepted)
- A Notes teaser (2-3 sentences)
- LinkedIn + Twitter/X distribution posts (only if the user accepted)
- If ghostwriting: the voice guide used
Adapting existing content
When the user wants to convert a blog post, talk, or thread into Substack content:
- Choose the right format. Evergreen source material (reference, tutorial, deep dive) → web post. Timely source (commentary, announcement, reaction) → newsletter issue.
- Don't just copy-paste. Substack readers expect a different voice and format than blog readers.
- Add the personal layer. Substack is more personal than a blog. Add context: why you're sharing this, what prompted it, your take.
- Front-load the value. Blog posts can have a slow build. Substack content must hook in the first 2 sentences (the email preview or search snippet).
- Shorten for newsletters. Cut 30-50% of blog post length for newsletter issues — email tolerance for length is lower. Web posts can preserve more depth.
- Add the CTA. Blog posts can end quietly. Substack content should ask for something.
Reference files
Read these for deeper platform knowledge:
references/voice-matching.md-- Detailed ghostwriting voice extraction process, interview techniques, voice guide templates, and iteration workflow. Read when ghostwriting.references/email-formatting.md-- Email client rendering constraints, formatting rules, mobile optimization, and code block handling. Read during Phase 3 for newsletter issues.references/web-post-formatting.md-- SEO optimization, web-first formatting rules, evergreen vs timely content strategy, sections/categories, and rich media usage. Read during Phase 3 for web posts.references/substack-algorithm.md-- How the algorithm works (from Substack's ML lead), Notes ranking signals, Recommendations system, growth levers ranked by impact, and monetization math. Read during Phase 4 or for strategic planning.
Questions: Ask the user through the environment's question tool — never as plain-text prose. One question at a time, 2–4 tappable options, wait for the answer. If the environment has no question tool, ask in prose with the same options, one at a time.
Technical Article Writer
Write technical articles that developers actually want to read. This skill combines structural frameworks from technical writing, hook engineering from copywriting, and practitioner-tested patterns for developer content.
Core philosophy
Most technical articles fail because of structural problems, not bad ideas: burying the lede, mixing content types, weak openings, no clear motivation, or trying to cover too much.
Developer audiences have a built-in BS detector. The best technical content leads with specificity and honesty. It sounds like a smart colleague explaining something interesting, not a marketer pitching. Acknowledge your expertise level, solve a specific problem, use real examples.
Not for reference documentation aimed at non-native readers or machine translation (→ See samber/cc-skills@humanizer-en-asd-ste100 skill for ASD-STE100 Simplified Technical English).
Workflow
Follow these phases in order. Each phase produces a concrete artifact the user reviews before moving on. Phase 1 is mandatory — always ask the user the intake questions and wait for answers before writing anything. If the user already provided some context, extract what you can and ask only about missing pieces.
Phase 1: Idea sharpening (interview)
Stop and ask. Before writing anything, present the intake questions below to the user and wait for their answers. Do not skip this phase, do not infer silently, and do not start drafting until you have explicit answers or confirmation on every item. Ask the user (or extract from context and confirm):
-
Topic: What specific thing are you writing about?
-
Objective: What's the primary goal of this article? Present these options through the question tool (push back if the user picks more than one — a single primary CTA converts far better than competing asks):
- Newsletter subscription / audience growth
- Personal branding / thought leadership / authority in a niche
- Product or service signup / free trial
- Direct purchase
- Lead generation (download, gated asset, whitepaper)
- Demo or sales call booking
- Community join (Discord, Slack, forum)
- Engagement (reply, share, comment, restack)
- Reader support (paid subscription, tip, sponsorship)
- No conversion goal (purely informational / educational)
The objective shapes the CTA, how much you give away vs. tease, and where conversion points sit. It will be passed directly to the
copywriting-ctaskill in Phase 5b. -
Audience: Who reads this? (junior devs, senior engineers, CTOs, general tech, DBA, frontend developer...)
-
Content type: Which pattern fits? (see
references/article-structures.mdfor full templates)- The Bug Hunt / We Rewrote It in X / How We Built It / Lessons Learned
- Thoughts on Trends / Benchmark / Tutorial / Explainer
-
Length target: Short (800-1200), Medium (1500-2500), Long (3000+)
-
One-sentence thesis: The single claim or takeaway. If the user can't state this, help them.
If the user already provided most of this, extract from conversation and confirm. But if critical pieces are missing, stop and ask before proceeding. Don't guess at the audience, content type, or thesis. A wrong assumption here wastes an entire draft.
Specifically:
- If the topic is vague ("write about Java performance"), ask what specific aspect and what the reader should walk away knowing.
- If the audience is unclear, ask. A post for junior devs has a completely different structure than one for senior engineers.
- If you can't infer a thesis, ask the user: "What's the one thing you want the reader to remember?" If they can't answer, help them find it through questions about what surprised them, what they'd tell a colleague, or what they wish they'd known earlier.
- If the content type is ambiguous (could be a tutorial or an explainer), ask which experience the reader should have: following along hands-on, or building a mental model.
Only proceed to Phase 2 once you have enough clarity on topic, audience, content type, and thesis to write a coherent outline. It's cheaper to ask one question now than to rewrite 2000 words later.
Idea quality filters. Apply these before investing in a draft:
Julia Evans's heuristic: the best technical content comes from what you struggled with, not what you mastered. If the topic feels too "textbook", push toward the specific struggle, surprise, or counterintuitive finding.
Julian Shapiro's novelty filter. The idea should fit at least one:
- Counter-intuitive: "I never realized the world worked that way"
- Counter-narrative: "That's not how I was told it worked"
- Shock and awe: "I had no idea that was possible"
- Elegant articulation: "I always felt that way but couldn't put it into words"
- Makes you feel seen: "Finally someone gets my experience"
If the idea doesn't pass any filter, say so. Help the user find the angle that does.
Phase 2: Title generation
Generate 10 title variants using different hook strategies. Read references/hooks-and-titles.md for the full framework of 10 hook types and headline formulas.
Constraints for developer audiences:
- 7-12 words optimal for LinkedIn/B2B sharing
- Specificity over cleverness ("How to profile Go allocations with pprof" > "Mastering Go Performance")
- Numbers and data signal rigor
- Avoid superlatives ("ultimate", "complete", "everything you need")
- Technical keywords attract the right audience
- Cognitive dissonance creates curiosity without clickbait
Present 10 titles ranked by assessment, with a brief note on why each works. Let the user pick or remix.
Phase 3: Hook and intro
Delegate the hook to the copywriting-hooks skill. Pass the topic, audience, language, content type, and length target from Phase 1. The skill will propose 3-4 hook options (2 candidates each) and wait for the user to pick. Do not write the hook yourself — let the skill run its full workflow.
After the user picks a hook, write the remaining intro (2-3 paragraphs) around it:
- Hook (chosen by the user via
copywriting-hooks) - Stakes (1-2 sentences): Why should the reader care? What's the cost of not knowing this?
- Promise (1 sentence): What will the reader gain by the end?
Address three reader objections:
- Untrustworthy: Why should I listen to you? (credibility hook or specific experience)
- Irrelevant: Why does this matter to me? (stakes)
- Implausible: Will this actually deliver? (promise + specificity)
Anti-patterns to avoid:
- Starting with a dictionary definition
- "In today's fast-paced world..."
- "Have you ever wondered..."
- Burying the interesting part after 3 paragraphs of context
- Explaining what the article will cover instead of demonstrating value
Phase 4: Body structure
Choose structure based on content type. Read references/article-structures.md for detailed templates per content type.
General structural principles:
- One idea per section. If a section does two things, split it.
- Show, then tell. Lead with the example, code snippet, or observation. Then explain.
- Progressive disclosure. Start with the simplest version, then add complexity.
- Every section earns the next. Each section should create enough momentum to pull the reader forward. If a section could be skipped, cut it.
For code-heavy articles:
- Snippets < 20 lines, focused on one concept
- Always show "before" (problem) and "after" (solution)
- Annotate non-obvious lines
- Link to repo for full code, show only the interesting parts inline
For opinion/analysis:
- Steelman the opposing view before arguing against it
- Concrete examples, not abstract reasoning
- Quantify claims ("2x faster" not "much faster")
Phase 5: Draft the full article
Write the complete article. Interleave hook, body sections, and conclusion.
For the conclusion, avoid restating the article. Instead pick one of:
- Implication: What does this mean for the reader's work going forward?
- Open question: What's still unresolved or worth exploring?
- Call to action: What should the reader do next?
Phase 5b: CTA
Delegate to the copywriting-cta skill. Pass the objective from Phase 1 as the primary objective. The skill will interview the user for any missing inputs (article context, audience relationship, funnel stage, mechanism) and produce the complete CTA recommendation — copy, form, mechanism, A/B test plan, and accessibility check.
Place the CTA output at the end of the article, after the conclusion. Do not write a CTA yourself.
Phase 5c: Humanize
Invoke a humanizer skill (e.g. "humanize", "humanizer", "de-slop", "natural writing check", "AI detection cleanup", "rewrite like a human") to strip AI-generated patterns — filler words, predictable cadence, over-hedging, hollow transitions, inflated language. Developer audiences have a built-in BS detector; AI-sounding prose kills trust before the reader reaches the technical content.
Preserve the hook and title. The opening hook (Phase 3) and title (Phase 2) were deliberately engineered for curiosity and credibility. Instruct the humanizer to leave them intact — rewriting them for "naturalness" destroys the copywriting structure that earns the click and the first scroll.
Phase 6: Image suggestions
After the draft is complete, suggest 1-3 images with specific placement in the article. For each image, provide:
- Placement: Where in the article (e.g. "as the hero/cover image", "after the intro", "between section X and Y")
- Purpose: What the image adds (break up a long text section, illustrate a concept, set the tone, visualize data)
- Description: What the image should depict
Offer to generate a Midjourney prompt for each suggested image. If the user accepts, use the latest Midjourney model conventions to write the prompt.
- Use
--ar 16:9or--ar 3:1for hero/cover images and wide illustrations (optimal for article headers),--ar 3:2for smaller inline images. - Refer to up-to-date Midjourney documentation for current prompt syntax and parameters.
Phase 7: Title finalization
Revisit titles from Phase 2. Now that the full piece exists, some titles fit better. Present top 3 with a recommendation.
Output format
Present the article in clean markdown with:
- The chosen title as H1
- A subtitle or meta-description (1 sentence)
- The full article body
- Image suggestions with placement notes (and Midjourney prompts if accepted)
- A "Title alternatives" section at the end with 2-3 runner-up titles
- A social teaser (only if the user accepted — offer after the draft, don't auto-generate)
Reference files
Read these when the corresponding phase needs more depth:
references/hooks-and-titles.md-- The 10 hook types, 6 copywriting frameworks (PAS, AIDA, BAB, FAB, PASTOR, 4Us), headline formulas, and research data. Read during Phase 2 and Phase 3.references/article-structures.md-- Detailed templates for each of the 8 content types, Diataxis framework, structural anti-patterns, and transition techniques. Read during Phase 4.
Training Report
Iterate the full report in Markdown first. Generate the .docx last, once, when the content is final. The .md is the canonical artifact; the .docx is a terminal derivative.
Discipline-agnostic: coding workshop, leadership seminar, safety training, onboarding, creative workshop — all apply equally.
Voice mode: this conversation may be conducted by voice. Transcription can introduce homophones, missing punctuation, or ambiguous proper nouns (names, company names, tool names). If any answer is unclear after transcription, ask a short clarifying question before moving on — do not guess.
Reference files
Load these files at the steps indicated. Do not load them all upfront.
| File | Load at |
|---|---|
references/tone-of-voice.md | Step 1 (after language + audience confirmed) |
references/markdown-draft.md | Step 5 (before writing the draft) |
references/docx-generation.md | Step 6 (before generating the .docx) |
Step 0 — Check dependencies
Before asking the user anything, verify skill availability.
docx skill (required for Step 6)
- If found: note it; load it at Step 6
- If not found: warn the user — it is required to generate the final Word document and can be installed from Anthropic's official skill library. Offer to proceed with the Markdown draft in the meantime.
Humanizer skill (recommended)
- After Step 1, look for a humanizer skill matching the chosen language
- If found: load it and apply it during the humanization pass in Step 5
- If not found: tell the user once, then fall back to inline humanization rules (Step 5b). Suggest installing a humanizer skill for the chosen language.
Step 1 — Language & audience
Ask:
- "In what language should I write the report? (French / English / other)"
- "Who is the primary reader? (executive / HR / direct management / external client / internal archive)"
Then load references/tone-of-voice.md and apply its guidance throughout.
Step 2 — Template
Ask:
"Do you have a Word (.docx) template for this report? (company header/footer, logo, branded fonts, color scheme)"
- Yes → ask them to upload it; use it as the base at Step 6 (unpack/inject/repack)
- No → proceed with a clean document; ask for a brand color before defaulting to blue
#2E75B6
Step 3 — Interview
Conduct a structured interview in batches. Wait for answers before moving on. Extract what the user already told you from the conversation before asking.
Batch A — Session metadata
- Trainer name and role
- Date, location, company/team name
- Duration
- Total number of participants
- Confirm or refine: who is the document for?
Batch B — Session context
- Stated goal of the training
- Subject, topic, tool, or material used as practical support
- Any rules or constraints set at the start
- Materials, accounts, licenses, or equipment provided to participants
Batch C — Starting levels
- Distribution of familiarity across the group (any beginners? any experts?)
- Notable outliers at either end
Batch D — Session walkthrough
Walk through the session step by step. For each step:
- Objective
- What participants actually did
- Materials, tools, or exercises involved
- First exposure to this concept or not
- How it landed; any difficulties
Probe until complete: "What happened next?", "Did anything go differently than planned?", "Were there any pivots?"
Batch E — Deliverables
Ask: "Did participants produce anything during the session?"
Probe for:
- Documents, files, diagrams, prototypes, or any output created during exercises
- Collaborative work produced as a group
- Individual work produced autonomously
- Anything left incomplete or started but not finished
These may appear in the Annexes and/or be referenced in the Session Walkthrough.
Batch F — General observations
- Overall energy and engagement of the group
- Any incidents, surprises, or notable moments
- Schedule: did it hold, or were sections cut/extended?
- Logistical issues (room, materials, setup)
General Observations is optional. If the trainer has nothing notable to add beyond the walkthrough, skip this section entirely.
Batch G — Individual feedback
Ask: "Do you have specific observations for any individual participant?"
For each named participant, extract:
- Role or background
- Starting level
- Behavior/engagement (positive and negative)
- Notable evolution, breakthrough, or resistance
- How they ended the session
Individual Feedback is optional. Only write it if the trainer explicitly provides meaningful observations. Do not prompt for feedback on every participant.
Be diplomatic. Describe behaviors, not character. Name problems factually; do not editorialize. When writing for an external client about a team you don't know, consider whether naming individuals is appropriate at all.
See references/tone-of-voice.md — Diplomatic framing section.
Batch H — Recommendations & next steps
Ask: "What would you recommend to the direction/client to build on this session?"
Probe for:
- Resources and access to provide (licenses, books, platforms, communities)
- Practices to anchor in daily work
- What to pace carefully — basics before advanced material
- Follow-up sessions (refresher, coaching, Q&A after a few weeks)
- Assessment and validation (quiz, practical challenge, peer review, checklist)
- Knowledge-sharing rituals (Slack/Teams channel, recurring meeting, Loom demos, buddy system, monthly show-and-tell)
- Management involvement (protect practice time, 1:1 check-ins, celebrate wins)
- External resources (books, courses, certifications) for self-driven participants
- Specific warnings or caveats for management
Batch I — Annexes
Ask: "Do you have any annexes to attach to the report?"
Annexes can include:
- Photos from the session
- Satisfaction survey results (NPS, ratings, verbatim comments)
- Slides or handouts distributed during the session
- Work produced by participants (exercises, prototypes, documents, diagrams)
- Reference documents used during the session
- Any other supporting material
For each annex:
- Image → attempt auto-embed at Step 6
- File (PDF, slides, spreadsheet) → reference in the Annexes section; do not embed
- Survey data → synthesize in Step 4, then include as a dedicated section in the doc
- Participant deliverable → reference in the relevant Walkthrough step AND in Annexes
Batch J — Closing & contact
Ask: "May I include a closing note thanking the team for the invitation, and your contact details for future collaboration? (email + phone)"
If yes: collect name, email, phone. The closing is written in the document language, personal in tone, brief. See references/markdown-draft.md — Closing paragraph section.
Step 4 — Feedback synthesis (if survey data provided)
Produce a synthesis in the conversation before drafting:
- Overall score / NPS
- Rating distribution
- Top 3 positive themes
- Top 3 areas for improvement
- Any outlier responses
Ask the user to confirm before it enters the document.
Step 4b — Confirm outline
Here's what I'll draft:
1. Context
2. Starting Levels
3. Session Walkthrough (N steps)
4. General Observations [optional — include if trainer provided content]
5. Participant Satisfaction [only if survey data provided]
6. Individual Feedback [optional — include if trainer provided feedback]
7. Recommendations & Next Steps
8. Annexes [only if annexes provided]
[Closing + contact]
Language: [language] | Audience: [target] | Template: [yes/no]
Ask: "Anything to adjust before I start the draft?"
Step 5 — Markdown draft
Load references/markdown-draft.md before writing. It contains the full section-by- section writing guide, Markdown limitations, HTML table workarounds, and closing paragraph guidance.
Humanization pass
Before presenting the draft, apply the humanizer skill (loaded in Step 0). If no humanizer skill is available, apply these rules inline:
- Cut all AI throat-clearing openers and sentence starters
- Cut adjective doublets — pick the more precise word
- Replace passive voice with active wherever natural
- Replace vague praise or criticism with specific behaviors or facts
- Short sentences over long ones
- Adapt to the document language (see
references/tone-of-voice.md)
Do not present an un-humanized draft.
Iteration loop
Present the draft inline in the conversation. Let the user lead. Update the .md file for every change. One canonical file, no versions. Only move to Step 6 when the user explicitly confirms the content is final.
Step 6 — Final .docx generation
Load references/docx-generation.md and the docx skill before starting.
This step runs once. It is terminal: if the user requests changes after the .docx is generated, update the .md and regenerate from scratch.
Deliver both files. If the environment supports inline file delivery (e.g. present_files on Claude.ai), use it. Otherwise, print the absolute paths to both files.
Pitfalls
- Don't fabricate details — only document what the trainer explicitly provided
- Don't editorialize in General Observations — factual only
- Don't write Individual Feedback unless explicitly provided — and stay diplomatic
- Don't pad recommendations — 6 sharp ones beat 12 vague ones
- Always include a Pacing recommendation in the Next Steps
- This skill is not developer-specific — adapt vocabulary to the discipline
- Never generate the .docx mid-conversation — Markdown is the draft stage
- Never skip an annex or image — embed, reference, or placeholder
Sponsors
Details
- Marketplace
- samber/cc
- Source
- samber/cc-skills
- Author
- Samuel Berthe
- Category
- Productivity
- License
- MIT
- Keywords
- claude-code, claude-code-plugin, plugin, ai-agent, skills