Shipping Across Surfaces
Land a change everywhere the same fact is stated, enumerating the full surface...
Install
npx skills add kajisho5/ffmpeg-skill --skill shipping-across-surfaces -g -a claude-code -y- Repository
- kajisho5/ffmpeg-skill4.3k
- Category
- Design
- Updated
- 4d ago
- License
- MIT
- Context cost
- Mediumabout 2,742 tokens
- Runs scripts
- No, instructions only
What it does
Land a change everywhere the same fact is stated, enumerating the full surface inventory (landing copy, docs, machine-readable summaries, changelog badges repeated across every page, sitemap, README, descriptions embedded in code, and untyped frontend consumers of typed responses), generating a surface instead of restating it, drift tests where you cannot generate, never hand-maintaining a copy of a surface another codebase owns, shipping a paired PR when you change a format a different codebase decodes, and keeping overloaded product words apart. Use when adding or renaming a user-facing feature, editing product/marketing copy or docs, renaming a serialized response field, changing a serialization or share-link format, wiring one repo's output into another's checks, or reviewing a PR that touched only one place a fact appears.
Shipping Across Surfaces
Most product facts are stated more than once. The feature exists in code, is described on a landing page, summarized for agents, listed in a changelog, repeated in a nav badge, restated in a README, and embedded again in the description string of every tool or endpoint that exposes it. Each copy drifts independently, and none of them are covered by tests.
The failure is never loud. Nothing goes red; the product simply describes itself inaccurately in the four places you didn't edit, and the one place a reader happened to look is the stale one.
Enumerate the surface inventory once, in the repo
"I'll remember the other places" does not survive the second feature. Write the
list down, in CONTRIBUTING.md, a PR template, or the skill/guide the project
already keeps, and treat it as the definition of done for a user-facing change.
A realistic inventory for a product with a public site:
- Landing page: hero, section ledes, the feature cards, the free/paid list
<meta>/ OG / Twitter tags, and the structured data (SoftwareApplicationdescription,FAQPageentries), search engines read the copy you forgot- Docs page, and any machine-readable summary for agents (
llms.txt) - Changelog entry and the version badge repeated in the nav of every page
- Sitemap, and the footer product column present on every page
- README, comparison pages, onboarding/skill files
- The descriptions embedded in code, every tool, command, or endpoint description, not just the primary one
That last bullet is the one that gets missed. A rename lands in the tool it was named after and stays wrong in the three sibling tools that mention it in passing. Grep for the old string across the whole tree, not just the docs directory, before calling the change done.
All of these ship in the same PR. A follow-up "update docs" commit means the interval between them shipped a product that contradicted itself.
