Content Filename From Title

content-filename-from-title

Public URLs age badly when filenames carry implementation detail (walkthrough-part-1.html), numbering (part-3-thing.html), or cluttering punctuation (url-%E2%86%94-purl-conversion.html). A title-word filename (anatomy.html, parsing.html, conversion.html) is short, speakable on a call, typeable, and doesn't need to change when the surrounding ordering does.

Claude must apply the same reasoning every time, or the fleet of filenames will drift stylistically across contributors and across sessions. This skill captures the reasoning as a deterministic procedure so the output is reproducible.

Where it fits in the repo

• tour.json - the parts[].filename field is the URL segment the page is published under at socketdev.github.io/socket-packageurl-js/<filename>.html.
• docs/*.md - the file stem becomes the URL segment when docs are stitched into the GH Pages flow (see docs/pages-design-system.md for the surrounding design system).
• Any future blog or guide manifest added to this repo.

A build-time validator in scripts/tour.mts enforces the shape ([a-z]+) and uniqueness; this skill decides the choice (which word).

• ASCII lowercase letters only: matches ^[a-z]+$.
  • No digits (part2 - FORBIDDEN)
  • No hyphens (url-conversion - FORBIDDEN)
  • No underscores, dots, slashes, or unicode
• Unique across all entries in the manifest. If the word you picked is already taken, pick another that's still content-bearing.
• Single word. Compound phrases (buildingandstringifying) are FORBIDDEN - pick the stronger of the two nouns instead.

Soft constraints (style)

• Typeable. A user on a call should be able to say "go to the anatomy page" and the listener can type it correctly without spelling.
• Stable. The word should still make sense if the surrounding ordering changes. part-one is unstable (it renames when content is reordered); anatomy is stable.
• Content-bearing, not generic. page, doc, content, item are FORBIDDEN. Pick a word that would still be meaningful if you only saw it in a URL with no context.

Apply these rules in order. Stop at the first rule that produces a clean single word.

Step 1 - Inventory the nouns in the title

Write out every noun and nominalized action (gerund, -ion, -ance). Discard every filler word (articles, prepositions, conjunctions, "of", "and", "&"). Discard every word that appears in 2+ other titles of the same manifest - those are qualifiers, not distinguishers.

Why: a filename needs to distinguish this page from its siblings. A word that isn't unique within the set can never be load-bearing.

Step 2 - Among remaining candidates, pick the distinguishing noun

If one noun is unique to this title and the others are not, that noun wins.

Example: "URL ↔ PURL Conversion" has three nouns (URL, PURL, Conversion). URL and PURL appear in multiple titles; Conversion is unique to this one. → conversion.

Step 3 - If several nouns are candidates, pick the superset

If the title lists multiple concepts that are facets of one bigger concept, pick the bigger one.

Example: "Validation, Errors & Results" - errors and Result<T,E> are outputs of validation. → validation.

Step 4 - If the title is "verb on a subject", pick the verb's nominal form

Gerund (-ing) if the activity itself is the topic; -ion / -ance if the state or result is the topic.

Example: "Parsing & Normalization" - normalization is a substep of parsing. The activity is the topic. → parsing.

Step 5 - If the title is a plain subject noun, use it directly

If the title is already a single content noun (Ecosystems), that's the filename. Just lowercase it.

Step 6 - Check hard constraints, then pick an alternative if needed

Now validate the chosen word against the hard constraints:

1. Does it match ^[a-z]+$? If not, reshape: URL ↔ PURL → consider nominals like conversion, not urltopurl.
2. Is it unique across the manifest? If not, go back to Step 2 and pick the next-best candidate.
3. Is it content-bearing? If it's generic (items, details), go back to Step 3 - you probably picked too abstract a word.

Step 7 - Sanity check

Read your picks as a list. Does it feel like a coherent table of contents? If one word feels off-tempo (too long, too clinical, too cute), adjust. Internal consistency matters - don't mix gerunds + nouns + adjectives.

These are the filenames currently in tour.json at the time this skill was written. Each shows the rule that produced the choice.

Counter-examples - choices the procedure rejects

Copy this into your working notes when adding/renaming a manifest entry:

Filename choice: _______________

- [ ] Matches ^[a-z]+$ (lowercase ASCII letters only)
- [ ] Unique across every other entry in the manifest
- [ ] Content-bearing (not 'page', 'item', 'content', etc.)
- [ ] Stable under reordering (no 'part1', 'first', etc.)
- [ ] Typeable from hearing it spoken
- [ ] Feels consistent with neighbor filenames' style (all gerunds?
      all plain nouns? all -ion forms? one style across the set)

If any checkbox fails, return to the decision procedure and pick again.

• The filename is internal (e.g. a build artifact under dist/, an intermediate JSON in .cache/). Internal paths don't need to be pretty - use whatever the code naturally emits.
• The filename is code-shaped, not content-shaped. TypeScript source files follow the convention of the ecosystem (kebab-case, matching export names). This skill is for content filenames only.
• The manifest exposes a hash or date-based identifier (e.g. a release slug, a git-sha-addressable blob). Use the hash; it's already optimal.