---
name: wiki-bloat
description: Wiki-bloat is when wayyyy too many wiki pages are being made. THE rule against it, straight from John (Adom's founder): before creating ANYTHING on the wiki, first find where that thing should already live, and put it there. "Add it to the skillpack" means literally that, locate the existing pack's repo and add a SKILL.md file to it; it never means mint a new page. Read this BEFORE any POST /pages, any new slug, any "should this be its own page" moment. Trigger words: wiki bloat, wiki-bloat, too many wiki pages, too many pages, should this be a page, new wiki page, create a wiki page, standalone page or skillpack, where should this skill live, add a skill to the pack, fold into existing, one page too many, page sprawl, new slug.
---

# Wiki-bloat, and how not to cause it

**Wiki-bloat means wayyyy too many wiki pages are being made.** That is the whole
definition, in the founder's words. Every page you add is a slug someone must find, a
surface that can drift out of date, and a competitor to the page that already covered the
territory. The wiki gets better when pages get RICHER, not when they get more numerous.

## The rule (memorize this, it overrides your instincts)

> Before creating anything, FIRST find where that thing should already live.

An AI's default instinct when asked to "make a skill" or "write this up" is to create a new
page: new slug, new repo, new hero, new listing. That instinct is the bloat machine. The
correct first move is a SEARCH, not a CREATE:

1. Is there an existing skillpack whose territory covers this? Then the task is: fetch that
   pack's repo, add `skills/<name>/SKILL.md`, extend its install.sh + package.json files[]
   + the skill-map table in the root SKILL.md, bump the version, republish. No new page
   exists afterwards. When a human says "add it to the skillpack," they mean EXACTLY this
   mechanical sequence, nothing grander. (This very skill was added that way.)
2. Is there an existing PAGE whose triggers already overlap yours? Extending it (directly
   if you own it, via a wiki PR if you do not) beats a second page that splits discovery.
   Two pages with overlapping triggers means agents load the wrong or partial context
   forever after.
3. Is the thing repo-specific, a helper, a build note, a convention only one codebase
   cares about? It goes IN THAT REPO (tools/, skills/, docs/), never on the wiki at all.
4. Only if all three above come up genuinely empty is a new page on the table, and then
   the archetype decision (Page vs Skillpack vs Family, see wiki-repo-styles) is made
   deliberately, not defaulted.

## The platform already warns you; do not steamroll it

The publish pipeline contains deliberate bloat checkpoints. Treat them as STOP signs:

- The hero requirement's own nudge says it outright: "the hero is the moment to decide you
  are creating one page too many." New app/skill heroes must be made in Hero Studio, in
  front of a human. That friction is intentional: a page worth creating is worth a human
  pausing over.
- Reaching for `--skip-lint` on a NEW page is a smell. The lint is where the platform asks
  "are you sure this should exist?" Skipping it to force a page into existence is how bloat
  ships.

## Case study (real, 2026-07-26)

A cross-app theme spec needed a home. It was genuinely shared content (two apps implement
it), so a standalone page felt defensible, and one was created. The founder's response:
"dude, are you creating wiki-bloat?" He was right: the adom org already had a brand/design
skill whose triggers include "theme tokens." The spec belonged INSIDE that existing surface,
and the new page fragmented discovery the moment it existed. The hero gate had even flagged
the decision, and got pushed past. Lesson: "the content is good" is not the test. "Does a
home already exist?" is the test, and it comes FIRST, before authoring, before slugs,
before anything.

And the counter-example, same day: a skill about wiki-bloat itself was requested WITH its
home named ("add it to the wiki skillpack"). The right execution was exactly rule 1: fetch
the pack, add one SKILL.md, extend the three list files, republish. Zero new pages.

## Case study 2 (real, 2026-08-02): the UNDELETE loophole

An AI was told to make a screen-takeover etiquette guide "an adom/core skill so all adom users
future ai threads know about this technique." Correct reading: add/extend a skill in the CORE PACK
(adom/adom). What the AI did instead: searched for a standalone page, found the slug existed but
was soft-deleted (it had already been cleaned up as bloat), ran `page undelete`, and pushed content
into the resurrected page. Founder: "oh my god. you created wiki bloat."

Three compounding failures, each independently avoidable:

1. **The content already had a home.** `adom/adom` ALREADY SHIPPED `skills/foreground-etiquette` -
   a ten-second pack-repo listing would have shown it. Rule 1 of this skill, not followed.
2. **"Make it a core skill" was read as "mint a page."** When a human names the pack ("adom/core",
   "the main skill pack all users get"), the task is the rule-1 mechanical sequence inside THAT
   pack. It is never a new slug.
3. **`page undelete` is a bloat backdoor.** A soft-deleted page is very often a page someone
   ALREADY JUDGED to be bloat. Resurrecting it dodges every creation checkpoint: the create-time
   conflict, the hero-in-front-of-a-human gate, the new-page lint. Treat an existing soft-delete as
   a STOP sign with a reason behind it: find out WHY it was deleted before even considering
   undelete, and never undelete just because your content needs somewhere to land.

(Tooling gap, filed the same day: the CLI reprimands on shared-identity publishes and placeholder
changelogs, but `page create` and `page undelete` ask no bloat question at all. Until they do, this
skill IS the gate.)

## Checklist before any POST /pages or new slug

- [ ] Did a human actually ask for a NEW PAGE, or did they ask for the CONTENT? (Content
      can live in an existing home; "write a skill for X" does not mean "mint a slug".)
- [ ] Searched the registry and installed skills for overlapping triggers? (`adom-wiki pkg
      search`, GET /discover, and grep ~/.claude/skills/ descriptions.)
- [ ] Checked the obvious skillpacks and hub pages whose territory borders this?
- [ ] If an existing home exists and you do not own it: proposed a PR instead of forking
      the territory?
- [ ] If truly new: picked the archetype on purpose, and prepared to make the hero in
      front of a human rather than around them?
- [ ] Remembered that soft-deleting a page BLOCKS its slug forever? A bloat page is not
      free to undo, which is one more reason not to create it casually.

## Related

wiki-repo-styles (the archetypes and when each is right), wiki-skillpack (the mechanics of
adding a sub-skill to a pack), wiki-hero + wiki-hero-studio (the human gate), wiki-forking
(the PR path into pages you do not own), wiki-discovery (why overlapping triggers hurt).