opencode-skills-collection 3.1.12 → 3.1.14

package/bundled-skills/ui-skills-root/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: ui-skills-root
+description: Use before UI-related work to select the smallest useful UI Skills context through the ui-skills CLI.
+risk: unknown
+source: https://github.com/ibelick/ui-skills/tree/main/skills/ui-skills-root
+source_repo: ibelick/ui-skills
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/ibelick/ui-skills/blob/main/LICENSE
+---
+
+# UI Skills Root
+## When to Use
+
+Use this skill when you need use before UI-related work to select the smallest useful UI Skills context through the ui-skills CLI.
+
+
+You are the routing layer for UI Skills.
+
+This skill is shown by `npx ui-skills start` and is also available in the registry.
+
+Use it when an agent in Codex, Cursor, or Claude Code has a clear UI goal.
+
+If the goal is unclear, ask one short question.
+
+If the goal is clear, choose the right category, load the smallest useful skill context, then implement.
+
+## Protocol
+
+1. decide if the task is UI-related
+2. if not, return `no skill needed`
+3. identify the likely category
+4. inspect that category with the CLI
+5. select the smallest useful skill set
+6. load only selected skill(s)
+7. implement using that context
+
+## CLI
+
+```bash
+npx ui-skills start
+npx ui-skills categories
+npx ui-skills list --category <category>
+npx ui-skills get <slug>
+```
+
+## Selection Rules
+
+Prefer 1 skill.
+
+Use 2 only when the task needs two clear angles.
+
+Use 3 only for broad review, redesign, or multi-surface work.
+
+Never use more than 3.
+
+Route by topic, then stack, then specificity.
+
+Prefer specific skills over broad skills.
+
+Prefer framework-specific skills when the stack is obvious.
+
+For quick cleanup, prefer the most specific craft, visual, or layout skill available.
+
+If unsure, inspect categories and pick the safest narrow skill.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/ui-tokens/SKILL.md

@@ -1,73 +1,65 @@
 ---
 name: ui-tokens
-description: "List, add, and update StyleSeed design tokens while keeping JSON sources, CSS variables, and dark-mode values in sync."
-category: design
-risk: safe
-source: community
+description: View, add, or modify design tokens in the StyleSeed design system
+risk: unknown
+source: https://github.com/bitjaru/styleseed/tree/main/engine/.claude/skills/ss-tokens
 source_repo: bitjaru/styleseed
 source_type: community
-date_added: "2026-04-08"
-author: bitjaru
-tags: [ui, tokens, design-system, theming, styleseed]
-tools: [claude, cursor, codex, gemini]
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/bitjaru/styleseed/blob/main/LICENSE
 ---
 
-# UI Tokens
-
-## Overview
-
-Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill manages design tokens without letting the source-of-truth files drift apart. It is meant for teams using the Toss seed's JSON token files and CSS implementation together.
-
+# Design Token Manager
 ## When to Use
-- Use when you need to inspect the current token set
-- Use when you want to add a new color, shadow, radius, spacing, or typography token
-- Use when you need to update a token and propagate the change safely
-- Use when the project has both JSON token files and CSS variables that must stay aligned
 
-## How It Works
+Use this skill when you need view, add, or modify design tokens in the StyleSeed design system.
 
-### Supported Actions
 
-- `list`: show the current tokens in a human-readable form
-- `add`: introduce a new token and wire it through the implementation
-- `update`: change an existing token value and audit the downstream usage
+## When NOT to use
 
-### Typical Source-of-Truth Split
+- For applying tokens in components → use `/ss-component` or `/ss-pattern`
+- For finding token violations in existing code → use `/ss-lint`
+- For brand-wide color/font choices that don't exist yet — define a skin first, then add tokens
+- For non-CSS token systems (Figma, native iOS/Android) — Tailwind v4 / CSS variables only
 
-For the Toss seed:
-- JSON under `tokens/`
-- CSS variables and theme wiring under `css/theme.css`
-- typography support in the font and base CSS files
+Action: **$0** | Token type: **$1**
+Arguments: $ARGUMENTS
 
-### Rules
+## Token File Locations
 
-- keep JSON and CSS in sync
-- prefer semantic names over descriptive names
-- provide dark-mode support where relevant
-- update the token implementation, not just the source manifest
-- check for direct component usage that might now be stale
+| Type | JSON Source | CSS Implementation |
+|------|-----------|-------------------|
+| Colors | `tokens/colors.json` | `css/theme.css` `:root` + `@theme inline` |
+| Typography | `tokens/typography.json` | `css/fonts.css` + `css/base.css` |
+| Spacing | `tokens/spacing.json` | Tailwind utilities (no custom CSS needed) |
+| Radius | `tokens/radii.json` | `css/theme.css` `@theme inline` |
+| Shadows | `tokens/shadows.json` | `css/theme.css` `:root` |
 
-## Output
+## Instructions
 
-Return:
-1. The requested token inventory or change summary
-2. Every file touched
-3. Any affected components or utilities that should be reviewed
-4. Follow-up actions if the new token requires broader adoption
+### `list` — Show current tokens
+Read and display the requested token file in a formatted table.
 
-## Best Practices
+### `add` — Add new token
+1. Add the token to the JSON source file (`tokens/*.json`)
+2. Add the CSS custom property to `css/theme.css` under `:root`
+3. If it needs a Tailwind utility, add to the `@theme inline` block
+4. If it has a dark mode variant, add to the `.dark` block
 
-- Add semantic intent, not one-off brand shades
-- Avoid token sprawl by extending existing scales first
-- Keep naming consistent with the rest of the system
-- Review contrast and accessibility when introducing new colors
+### `update` — Modify existing token
+1. Update the value in the JSON source file
+2. Update the CSS custom property in `theme.css`
+3. Check all components for direct usage that might need updating
 
-## Additional Resources
-
-- [StyleSeed repository](https://github.com/bitjaru/styleseed)
-- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ui-tokens/SKILL.md)
+## Rules
+- Always keep JSON and CSS in sync
+- Use semantic names, not descriptive names (`--success` not `--green-500`)
+- Colors should support both light and dark modes
+- New tokens must be added to BOTH the JSON source AND the CSS implementation
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
-- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
-- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/ui-update/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: ui-update
+description: Update StyleSeed engine in your project — analyzes what's outdated and updates safely
+risk: unknown
+source: https://github.com/bitjaru/styleseed/tree/main/engine/.claude/skills/ss-update
+source_repo: bitjaru/styleseed
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/bitjaru/styleseed/blob/main/LICENSE
+---
+
+# StyleSeed Update Assistant
+## When to Use
+
+Use this skill when you need update StyleSeed engine in your project — analyzes what's outdated and updates safely.
+
+
+## When NOT to use
+
+- For first-time setup → use `/ss-setup`
+- For just one new component or skin — copy that file manually
+- For projects that have heavily diverged from upstream — manual diff review first
+- For updating user code/components — this updates engine files only, not your custom UI
+
+Automatically detect and update StyleSeed files in the current project.
+
+## Reassure the user first
+
+Updating is **safe and reversible**. Updates are additive — new rules,
+components, skins, and skills get added; your `theme.css`, your components, and
+your app code are never overwritten, and design rules only ever get added (never
+changed in a breaking way). A big version jump looks like a lot changed, but
+it's almost all additions. **Do NOT warn the user that the build will break**
+unless you actually find a changed component/import API. Tell them: commit first,
+copy the new rules + skills, run a build, and `git reset --hard` if anything is
+off — they can't permanently break their project.
+
+## Instructions
+
+### Step 1: Detect Current Setup
+
+Scan the project to find where StyleSeed files are:
+
+```bash
+# Find DESIGN-LANGUAGE.md
+find . -name "DESIGN-LANGUAGE.md" -not -path "*/node_modules/*"
+
+# Find CLAUDE.md
+find . -name "CLAUDE.md" -not -path "*/node_modules/*"
+
+# Find skills (ss-* is current; ui-*/ux-* are legacy names to migrate from)
+find . -path "*/.claude/skills/ss-*" -o -path "*/.claude/skills/ui-*" -o -path "*/.claude/skills/ux-*" | head -20
+
+# Find theme.css
+find . -name "theme.css" -not -path "*/node_modules/*"
+
+# Find .cursorrules
+find . -name ".cursorrules"
+```
+
+Report what was found and where.
+
+### Step 2: Check StyleSeed Version
+
+**Fast check first** — compare the local version to the published one without cloning:
+```bash
+# local marker (may be absent on older installs)
+cat engine/VERSION 2>/dev/null || cat VERSION 2>/dev/null || echo "unknown"
+# latest published version + what's new
+curl -s https://styleseed-demo.vercel.app/version.json
+```
+If the local version already matches `version.json`'s `version`, tell the user they're
+up to date and stop. Otherwise report `whatsNew` and continue.
+
+Then clone/pull to actually diff the files:
+```bash
+if [ -d "/tmp/styleseed" ]; then
+  cd /tmp/styleseed && git pull
+else
+  git clone https://github.com/bitjaru/styleseed.git /tmp/styleseed
+fi
+```
+
+Compare:
+- `engine/VERSION` (or `version.json`) vs the local copy — the source of truth
+- DESIGN-LANGUAGE.md rule count + Table of Contents
+- Skills present in `.claude/skills/` vs upstream (don't hardcode a count — list the diff)
+- Whether `CLAUDE.md`, `AGENTS.md`, and `.cursorrules` exist (ship all three)
+- New engine docs (VISUAL-CRAFT.md, APP-PLAYBOOKS.md, PAGE-TYPES.md)
+
+### Step 3: Report & Ask
+
+Show the user what needs updating:
+
+```
+StyleSeed Update Report:
+
+Current state:
+- DESIGN-LANGUAGE.md: [location] — [old/current version indicator]
+- Skills: [count] found (latest: 12)
+- Golden Rules: [yes/no]
+- .cursorrules: [yes/no]
+
+Recommended updates:
+1. ✅ [safe] Update skills (X → 12)
+2. ✅ [safe] Add .cursorrules
+3. ⚠️ [review] Update DESIGN-LANGUAGE.md ([old line count] → [new line count])
+4. ⚠️ [merge] Add Golden Rules to CLAUDE.md (won't overwrite existing content)
+
+Shall I proceed? (I'll ask before each ⚠️ item)
+```
+
+### Step 4: Execute Updates
+
+For each update, in order:
+
+**Always safe (do without asking):**
+- Copy skills: `cp -r /tmp/styleseed/engine/.claude/skills/ .claude/skills/`
+- Copy .cursorrules (if not exists): `cp /tmp/styleseed/engine/.cursorrules .cursorrules`
+
+**Ask before doing:**
+
+For DESIGN-LANGUAGE.md:
+- Show diff summary: how many new rules, what sections added
+- Ask: "Update DESIGN-LANGUAGE.md? (Y/N)"
+- If yes: copy to the detected location
+
+For CLAUDE.md (Golden Rules):
+- Check if Golden Rules section already exists
+- If not: ask "Add Golden Rules section to your CLAUDE.md? This adds 10 lines at the top. Your existing content stays untouched."
+- If yes: insert Golden Rules after the first heading
+
+**Never touch:**
+- theme.css — say "Your theme.css (skin) is untouched."
+- components/ — say "Your components are untouched. Run `/ss-lint` to check compliance."
+
+### Step 5: Summary
+
+```
+Update complete!
+
+✅ Skills: 12 (added X new)
+✅ .cursorrules: added
+✅ DESIGN-LANGUAGE.md: updated to latest
+✅ Golden Rules: added to CLAUDE.md
+
+Not touched:
+- theme.css (your skin)
+- components/ (your code)
+
+Next: run /ss-lint on your pages to check for rule violations.
+```
+
+## Important
+
+- NEVER overwrite theme.css
+- NEVER overwrite a project-specific CLAUDE.md — only MERGE the Golden Rules section
+- NEVER overwrite components without explicit user approval
+- Always show what will change before changing it
+- If unsure, ask the user
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/unslop-commit/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: unslop-commit
+description: Rewrites commit messages so they sound like a careful human engineer wrote them. Strips AI/marketing slop ("comprehensive solution", "robust implementation", "leverage", "enhance", "seamlessly", "This commit..."). Keeps Conventional Commits format. Subject ≤72 chars (aim ≤50),...
+risk: unknown
+source: https://github.com/MohamedAbdallah-14/unslop/tree/main/plugins/unslop/skills/unslop-commit
+source_repo: MohamedAbdallah-14/unslop
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/MohamedAbdallah-14/unslop/blob/main/LICENSE
+---
+
+# Unslop Commit
+## When to Use
+
+Use this skill when you need rewrites commit messages so they sound like a careful human engineer wrote them. Strips AI/marketing slop ("comprehensive solution", "robust implementation", "leverage", "enhance", "seamlessly", "This commit..."). Keeps Conventional Commits format. Subject ≤72 chars (aim ≤50),...
+
+
+## Purpose
+
+Generate or rewrite commit messages so they read like a real engineer wrote them at the end of a real day. Conventional Commits format. Direct, specific, no template English. Why over what.
+
+## Trigger
+
+`/unslop-commit`, `/commit`, "write a commit", "commit message", "humanize this commit", "de-slop this commit". Auto-trigger when the user has staged changes and asks for a commit message.
+
+## Rules
+
+### Subject line
+
+- Format: `<type>(<scope>): <imperative summary>`
+- Scope optional. Types: `feat`, `fix`, `chore`, `refactor`, `docs`, `test`, `perf`, `build`, `ci`, `revert`.
+- Imperative mood: `add`, `fix`, `move`, `remove` — not `added`, `fixes`, `fixing`.
+- ≤50 chars when possible. Hard cap 72.
+- No trailing period.
+- Lowercase after `:` unless the project capitalizes.
+
+### Body (only when subject can't carry it)
+
+- Add for: non-obvious "why", breaking changes, migrations, security context, data integrity.
+- Wrap at 72 chars. Bullets `-` for two or more independent points. Single paragraph for one thought.
+- End with refs: `Closes #42`, `Refs #17`. No `BREAKING CHANGE:` unless truly breaking — and then write it.
+
+### Never include
+
+- Template prefixes: "This commit...", "This change...", "We are...", "I have..."
+- Marketing verbs: comprehensive, robust, enhance, leverage, seamless, holistic
+- Filler adverbs: just, really, basically, simply, actually
+- Restating the filename when scope already names it
+- "As requested by..." (use `Co-authored-by:` if you need attribution)
+- AI attribution unless the project requires it
+- Emoji unless project convention says so
+
+### Auto-clarity (always include body)
+
+- Breaking changes
+- Security fixes
+- Data migrations
+- Reverts (cite the reverted commit)
+
+## Examples
+
+### Bad → good (slop subject, no body)
+
+- Bad: `feat: implement a comprehensive, robust solution for user profile retrieval with enhanced error handling`
+- Good: `feat(api): return profile fields the mobile client actually needs`
+
+### Bad → good (vague body)
+
+Bad:
+```
+fix: fixed the bug
+
+This commit addresses an issue where the application was not working correctly
+in some edge cases. We've improved the logic to handle these scenarios.
+```
+
+Good:
+```
+fix(checkout): ignore stale cart id from localStorage
+
+Stale cart ids came from tabs that hadn't refreshed after a deploy. Server
+now treats unknown ids as empty cart instead of 500.
+
+Closes #842
+```
+
+### Breaking change
+
+```
+feat(api)!: rename /v1/orders to /v1/customer-orders
+
+The old route stays in place until the next major release but logs a
+deprecation warning. Internal services have been migrated.
+
+BREAKING CHANGE: third-party integrations using /v1/orders directly need
+to switch to /v1/customer-orders by 2026-07-01.
+
+Closes #1290
+```
+
+## Boundaries
+
+- Output the message only, in a single fenced block, ready to paste.
+- Do not run `git commit`, stage, or amend.
+- If the change is genuinely trivial (`docs(readme): fix typo`), keep it trivial. Don't pad.
+- Never invent context the user didn't provide. If the "why" isn't clear, ask, or omit the body.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/unslop-file/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: unslop-file
+description: "Humanize natural-language memory files (CLAUDE.md, todos, preferences, docs) by removing AI-isms and adding burstiness while preserving every code block, URL, path, command, and heading exactly. Two modes: --deterministic (fast, regex-based, no API) and LLM (default, calls Claude for..."
+risk: unknown
+source: https://github.com/MohamedAbdallah-14/unslop/tree/main/plugins/unslop/skills/unslop-file
+source_repo: MohamedAbdallah-14/unslop
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/MohamedAbdallah-14/unslop/blob/main/LICENSE
+---
+
+# Unslop Humanize
+## When to Use
+
+Use this skill when you need humanize natural-language memory files (CLAUDE.md, todos, preferences, docs) by removing AI-isms and adding burstiness while preserving every code block, URL, path, command, and heading exactly. Two modes: --deterministic (fast, regex-based, no API) and LLM (default, calls Claude for...
+
+
+## Purpose
+
+Rewrite natural-language memory files (CLAUDE.md, AGENTS.md, todos, preferences, docs) so they sound human-written: no sycophancy, no stock vocab, no five-paragraph essay shape, no tricolon padding. Everything technical stays exact: code blocks, inline code, URLs, file paths, commands, headings, tables.
+
+Two modes:
+
+- **`--deterministic`** — fast regex pass that strips canonical AI-isms and tightens tricolons. No API call, no `ANTHROPIC_API_KEY` needed. Best for batch processing and CI.
+- **LLM mode (default)** — calls Claude (via Anthropic SDK or `claude --print` CLI fallback) to do a full rewrite that engineers burstiness, restructures performative paragraphs, and matches voice. Slower but better quality.
+
+Humanized version overwrites the original. A `FILE.original.md` backup is written first. Re-run after editing the `.original.md` to regenerate.
+
+### Intensity levels (`--mode`)
+
+| Mode       | What runs                                                                                   | Use when…                                                    |
+| ---------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `subtle`   | Stock vocab only.                                                                           | Structure is fine; you just want AI vocabulary gone.         |
+| `balanced` | (Default.) Sycophancy, hedging, transitions, stock vocab, authority tropes, signposting, performative balance, em-dash cap. | Everyday docs / READMEs / CLAUDE.md.                         |
+| `full`     | Balanced + filler phrases + negative-parallelism tricolons + stronger LLM prompt.           | Marketing copy, release notes, slop-heavy LLM output.        |
+
+### Two-pass audit
+
+Use the deterministic pass to get a report, then fix anything that slipped:
+
+```bash
+humanize --deterministic --report audit.json doc.md     # writes audit + humanized
+humanize doc.md                                         # optional LLM polish on top
+```
+
+`audit.json` lists every rule that fired, every `before → after` pair, and `counts_by_rule`. Great for reviewing what the regex changed before trusting the diff to merge.
+
+## Trigger
+
+`/unslop-file <filepath>`, `/unslop:humanize <filepath>`, or "humanize memory file", "de-slop this doc", "strip AI tone from this file".
+
+## Process
+
+The scripts live in a `scripts/` directory adjacent to this SKILL.md.
+
+Common layouts:
+- Full repo: `unslop/SKILL.md` + `unslop/scripts/`
+- Synced mirror: `skills/unslop-file/SKILL.md` + `skills/unslop-file/scripts/`
+- Codex bundle: `plugins/unslop/skills/unslop-file/SKILL.md` + sibling `scripts/`
+
+Always prefer the `scripts/` sibling of the currently loaded SKILL file.
+
+Steps:
+
+1. Locate the directory containing this SKILL.md and its `scripts/` sibling.
+2. Run from that directory: `python3 -m scripts <absolute_filepath>` (LLM mode), or add `--deterministic` for the regex pass.
+3. CLI flow: detect file type → write `.original.md` backup → humanize → validate (preserve check + AI-ism residual check) → on validation error: targeted fix call (LLM mode) → retry up to 2 times.
+4. On final failure: report errors, restore original, exit 2.
+5. On success: report path of humanized file and `.original.md` backup, exit 0.
+6. Return result to user.
+
+## Humanization Rules
+
+### Remove (canonical AI-isms)
+
+- **Sycophancy openers**: "Great question!", "Certainly!", "Absolutely!", "Sure!", "I'd be happy to help", "What a fascinating..."
+- **Stock vocab**: `delve`, `tapestry`, `testament` (praise form), `navigate`/`embark`/`journey` (figurative), `realm`, `landscape` (figurative), `pivotal`, `paramount`, `seamless`, `holistic`, `leverage` (filler verb), `robust` (filler), `comprehensive` (when "complete" works), `cutting-edge`, `state-of-the-art` (filler), `interplay`, `intricate`, `vibrant`, `underscore(s)/d/ing` (figurative), `crucial`, `vital` (role/importance/part), `ever-evolving`, `ever-changing`, `in today's (digital) world/age`, `dynamic landscape`.
+- **Hedging openers**: "It's important to note that", "It's worth mentioning", "Generally speaking", "In essence", "At its core", "It should be noted that", "It's also worth pointing out".
+- **Authority tropes** (sentence start): "At its core,", "In reality,", "Fundamentally,", "What really matters is", "The heart of the matter is", "At the heart of X is/lies".
+- **Signposting announcements**: "Let's dive in(to ...)", "Let's break this down", "Here's what you need to know", "Without further ado", "In this article, I'll ...", "Buckle up".
+- **Transition tics** (sentence start): "Furthermore,", "Moreover,", "Additionally,", "In conclusion,", "To summarize,".
+- **Performative balance**: "however" / "on the other hand" appended to every claim.
+- **Em-dash pileups** (more than two em-dashes per paragraph).
+- **Filler phrases** (`--mode full` only): "in order to" → "to", "due to the fact that" → "because", "prior to" → "before", "with regard to" → "about", "a wide variety of" → "many", "at this point in time" → "now", "the fact that" → "that", etc.
+- **Negative-parallelism tricolons** (`--mode full` only): "No guesswork, no bloat, no surprises." — the rhetorical triple-no punch.
+
+### Tighten
+
+- Tricolons: "X, Y, and Z" stacks where two would suffice — keep two, drop the weakest
+- Bullet soup: three bullets that say the same thing → merge into one sentence
+- Five-paragraph essay shapes: vary paragraph length; don't write four paragraphs of identical length
+
+### Preserve EXACTLY (never modify)
+
+- Fenced code blocks (```...```) — every byte
+- Indented code blocks (4-space)
+- Inline code (`...`)
+- URLs and markdown links
+- File paths (`./src/`, `/etc/`, `C:\Users\...`)
+- Commands (`npm install`, `git rebase`, `docker run`)
+- Technical terms, proper nouns, API names
+- Dates, version numbers, numerics
+- Environment variables (`$HOME`, `${NODE_ENV}`)
+
+### Preserve structure
+
+- All markdown headings (text exact)
+- Bullet hierarchy and nesting
+- Numbered lists
+- Tables (compress cells; keep structure)
+- YAML frontmatter
+
+### CRITICAL RULE
+
+Everything inside ` ``` ... ``` ` is read-only. No comment changes, no whitespace changes, no line reordering. Inline backticks: same. Code is the substrate; humanization only operates on prose between code regions.
+
+## Pattern (before → after)
+
+| #   | Before                                                                                                                                                                                                                | After (deterministic, `--mode balanced`)                                               |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| 1   | It's important to note that running tests prior to pushing changes is a comprehensive best practice. Additionally, it's worth mentioning that this can prevent broken builds.                                         | Running tests before pushing changes is a broad best practice. This can prevent broken builds. |
+| 2   | The application leverages a microservices architecture that comprises multiple discrete components.                                                                                                                   | The application uses a microservices architecture that comprises multiple discrete components. |
+| 3   | At its core, caching trades memory for latency.                                                                                                                                                                       | Caching trades memory for latency.                                                     |
+| 4   | Let's dive in. Here is the first step.                                                                                                                                                                                | Here is the first step.                                                                |
+| 5   | The intricate interplay between caching and latency is crucial.                                                                                                                                                       | The detailed link between caching and latency is important.                            |
+| 6   | In today's digital world, we ship fast.                                                                                                                                                                               | Today, we ship fast.                                                                   |
+
+### At `--mode full`, additionally:
+
+| #   | Before                                                   | After                                 |
+| --- | -------------------------------------------------------- | ------------------------------------- |
+| 7   | We ran the tests in order to verify the fix.             | We ran the tests to verify the fix.   |
+| 8   | The build failed due to the fact that the disk was full. | The build failed because the disk was full. |
+| 9   | No guesswork, no bloat, no surprises.                    | _(stripped)_                          |
+
+### Reference
+
+- `blader/unslop` — Claude-Code skill listing 30+ AI tells; we incorporated the strongest signals.
+- Wikipedia: *Signs of AI writing* — public taxonomy cross-referenced for vocab.
+- Full comparison + gap analysis: `docs/research/IMPLEMENTATION_TRACE.md`.
+
+## Boundaries
+
+- Only operate on `.md`, `.txt`, `.markdown`, `.rst`, or extensionless natural language.
+- Never modify `.py`, `.js`, `.ts`, `.json`, `.yaml`, `.yml`, `.toml`, `.env`, `.lock`, `.css`, `.html`, `.xml`, `.sql`, `.sh`.
+- Mixed prose-and-code files: humanize only the prose; leave fenced code untouched.
+- If unsure whether a file is prose or code: leave unchanged.
+- Backup `FILE.original.md` is written before overwrite. Never humanize a file already named `*.original.md`.
+- Sensitive paths (anything matching `.env*`, `*.pem`, `*.key`, `~/.ssh/`, `~/.aws/`, etc.) are refused before any read or API call.
+- Files larger than 500 KB are refused.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.