--- 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//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).