agentleFS
giolaqgiolaq/tv-build-harness/skills/rn-template-anatomy/SKILL.md

rn-template-anatomy

Skill4 starsChanged 5 months agoMIT-0View on GitHub

Template repo file structure: where screens, navigation, theme, data, and platform entries live in the monorepo

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Only differs in styling? → put platform in styles, not in files.

    line 71
  2. Distinctive:

    If any of those fail before you start, fix that first.

    line 124

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Template anatomy

The base template is AmazonAppDev/react-native-multi-tv-app-sample. Knowing where things live is half the job. Editing the wrong file is most of the failures.

Top-level layout

react-native-multi-tv-app-sample/
├── apps/
│   ├── expo-multi-tv/      # Universal app: Android TV, Apple TV, Fire TV (FOS), Web
│   └── vega/               # Fire TV Vega OS only (separate SDK)
├── packages/
│   └── shared-ui/          # All shared components, screens, hooks, theme, data
├── package.json            # Yarn workspaces root
└── tsconfig.base.json      # Shared TS config

When you touch which app

apps/expo-multi-tv/ — anything that runs on Android TV, Apple TV, Fire TV FOS, or Web. Edit when:

  • Changing app metadata (app.json: name, slug, bundle ID, banner)
  • Adjusting Expo plugins, native build settings
  • Adding a platform-specific native dependency

apps/vega/ — Fire TV Vega OS only. Edit when:

  • The target platform list includes firetv-vega
  • A feature uses @amazon-devices/* packages
  • Vega-specific manifest changes

Do not try to merge the two apps. They share UI via packages/shared-ui and that's the boundary. If a feature won't work on Vega, gate it; don't fork the shared package.

packages/shared-ui/ is the heart

This is where ~80% of edits go. Layout:

packages/shared-ui/
├── components/      # Reusable UI: Drawer, Grid, Hero, Tile, Player, etc.
├── screens/         # Composed screens: Home, Detail, Player, Settings
├── navigation/      # Drawer/route config
├── hooks/           # Data hooks (manifest consumption)
├── theme/           # Tokens, theme provider
├── data/            # Static data, manifest goes here
└── remote-control/  # Per-platform remote handlers

Metro platform resolution

Metro picks the right file by extension. This is how the template handles platform splits without if (Platform.OS === ...) everywhere.

ExtensionResolved when
Foo.android.tsAndroid TV + Fire TV FOS builds
Foo.ios.tsApple TV build
Foo.kepler.tsVega OS build (Kepler is the Vega runtime)
Foo.web.tsWeb build
Foo.tsFallback for any platform without a specific file

Decision tree: do I need a platform-specific file?

  1. Does the API call work identically on all platforms? → single Foo.ts.
  2. Different SDK on Vega but the rest is the same? → Foo.ts (default) + Foo.kepler.ts (override).
  3. Different on every platform? → drop the default and write one file per platform.
  4. Only differs in styling? → put platform in styles, not in files. Keep one file.

Asset locations

AssetLocationNotes
App iconapps/expo-multi-tv/assets/icon.png1024×1024
Splashapps/expo-multi-tv/assets/splash.png1920×1080 minimum for TV
Android TV bannerapps/expo-multi-tv/assets/icon-400x240.pngExact 400×240, required for leanback
Shared imagespackages/shared-ui/assets/Component-local images
Vega assetsapps/vega/assets/Vega-specific

Yarn workspaces commands

# Install root + all workspaces
yarn

# Add a dep to a specific workspace
yarn workspace expo-multi-tv add <pkg>
yarn workspace @multi-tv/shared-ui add <pkg>

# Run a script in a workspace
yarn workspace expo-multi-tv run android

Anti-pattern: running npm install in a sub-app directory. It breaks the workspace symlinks. Always use yarn at the root, or yarn workspace ....

Anti-pattern: adding react or react-native to packages/shared-ui/devDependencies. With nmHoistingLimits: workspaces, this installs a physical copy at packages/shared-ui/node_modules/react/ which the web bundler resolves as a separate React instance, crashing the app with "Invalid hook call." Use only @types/react for typechecking in shared-ui. The runtime react is resolved via Metro's nodeModulesPaths (pointing to the expo app's node_modules) on all platforms.

Where new content goes

You want to add…Put it here
A new componentpackages/shared-ui/components/<Name>/
A new screenpackages/shared-ui/screens/<Name>/ + register in navigation/
Content manifestpackages/shared-ui/data/content.json (overwrites existing)
A new data hookpackages/shared-ui/hooks/use<Name>.ts
Theme tokenspackages/shared-ui/theme/tokens.ts
Vega-only featureapps/vega/src/<feature>/

Dangerous places — touch with care

  • apps/*/ios/ and apps/*/android/ — native projects, regenerated by expo prebuild. Manual edits get blown away. If you need a change, do it via Expo config plugins.
  • app.json plugins array — order matters; @react-native-tvos/config-tv must come before plugins that modify the manifest.
  • tsconfig.base.json — changing path aliases breaks Metro resolution. If you must, also update Metro config.

Quick sanity checks before any larger edit

  1. yarn runs cleanly from the root.
  2. yarn workspace expo-multi-tv tsc --noEmit passes.
  3. The file you're about to edit isn't auto-generated (check for "DO NOT EDIT" headers and prebuild output dirs).

If any of those fail before you start, fix that first. Don't pile new changes on a broken tree.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.