meta

Files (1)

• SKILL.md

SKILL.md (first lines)

# How to use this skill library

> You have a skill library. **Use it.** This file is loaded on every turn so you remember it exists. The other skills are loaded by phase; you don't have to manage that — the harness does. Your job is to *consult* skills before acting, and to propose reusable candidates when you solve something that will come up again.

## The rule that everything else follows

**Before writing code or invoking a non-trivial tool, ask: is there a skill for this?**

If yes → read it, follow its decision tree, then act.
If no but the problem is recurring or clearly general → solve it, then propose a candidate via `write_auto_skill` when that tool is available.
If no and the problem is one-off → just solve it. Don't pre-codify.

The harness will surface relevant skills in your context automatically based on the current phase. If you find yourself reasoning about a problem and no relevant skill is loaded, **don't guess** — call `request_skill_load(name)` to pull one, or `list_skills()` if you're not sure what's available. Both are cheap and safe.

## Tools you have for skill management

- **`request_skill_load(name)`** — pull a skill not auto-loaded for this phase. Use when you hit a problem that feels like it should have established guidance. If the name is wrong, the tool returns suggestions.
- **`list_skills(scope?)`** — see what's available. `scope` is `core | auto | all`. Call this when an error message contains a domain word you haven't seen before (e.g. "Vega," "leanback," "manifest schema") — there's probably a skill for it.
- **`write_auto_skill(name, applies_to, content)`** — submit a reusable candidate. The harness validates its kebab-case name, phase scope, length, gotchas or anti-patterns, and code example before accepting it. If this tool is unavailable, report the candidate for human review instead of writing into `skills/auto/` directly.

## When to consult a skill (not just notice it's loaded)

The skill being in your context isn't enough. Actually open it and reason from it when:

- You're about to write a new file. → `template-anatomy.md` says where it goes.
- You're about to write a new screen. → `shared-ui-catalog.md` says whether to reuse instead.
- A focus / D-pad bug is reported. → `spatial-navigation.md` has the diagnostic tree.
- A build is failing. → `expo-tv-config.md` or `eas-build.md` has the symptom table.
- Anything touches Vega. → `vega-sdk.md`. Vega is not Android.
- You're applying brand colors / fonts. → `theming.md`. Don't eyeball contrast.

If you act without consulting and you were wrong, that's the failure mode this library exists to prevent.

## The inventory (one-line each)

- `template-anatomy.md` — where every file lives in the monorepo
- `shared-ui-catalog.md` — what components/screens already exist; **reuse before generating**
- `theming.md` — brand kit → theme tokens; contrast and typography rules
- `manifest-wiring.md` — content.json → hooks → screens; validation rules
- `spatial-navigation.md` — React TV Space Navigation patterns and focus debugging
- `vega-sdk.md` — Fire TV Vega OS (Kepler) — different runtime from Fire OS
- `firetv-leanback.md` — Android TV / Fire TV (Fire OS) manifest requirements
- `expo-tv-config.md` — `EXPO_TV=1`, prebuild, config plugin
- `video-player.md` — `react-native-video` and Kepler media; stream types
- `eas-build.md` — TV build profiles, when to use EAS vs local
- `10ft-ui.md` — type scale, contrast, safe areas — only for new screens

## Proposing auto-skill candidates

After solving a novel, reusable sub-problem, call `write_auto_skill(name, applies_to, content)` if the validated tool is available. Otherwise, include the proposed name, phase scope, and body in your response for human review. Never write directly into the skills directory. Include:

1. **A phase scope** in `applies_to` that identifies which phase should load it.
2. **The decision** you made and why. Not the code — the judgment.
3. **The anti-pattern** you almost fell into. This is often the most valuable part.
4. **A concrete example** from this run as illustration.

Accepted candidates are indexed immediately and load only for matching phases. They remain candidates until a human reviews their accuracy, scope, and overlap with core skills.

The validated tool rejects:
- A name that is not kebab-case, is unsafe, or already exists.
- Missing or invalid `applies_to` phase scope.
- Body shorter than ~500 characters → reject as too thin.
- No Gotchas or Anti-pattern section → reject; the warning is half the value.
- No code example → reject as insufficiently concrete.

Read the rejection reason, fix, retry. Don't retry blindly.

### Quality bar for auto-skills

- Would a fresh agent, loading this skill cold, make the right call without further context? If no, expand.
- Is it specific enough to be useful but general enough to apply across similar tasks? If only useful for the one case, don't write it.
- Is the anti-pattern section concrete? "Don't be wrong" is not a skill. "Don't use `<TouchableOpacity>` for focusable elements because it responds to touch, not D-pad select" is a skill.

## What the harness handles, so you don't worry about it

- **Which skills are loaded.** Phase-based, automatic.
- **Tool dispatch.** You name tools; the harness executes.
- **State.** Iteration count, budget, file diffs — tracked.
- **Safety.** Tool permissions; you don't need to second-guess every action.

## What you handle

- **Reading the right skill at the right moment.** Not just having it in context.
- **Reusing template components and screens.** This is the highest-leverage habit.
- **Flagging when you need a skill that doesn't exist.** Don't fake it.
- **Proposing a candidate after you've solved something novel and reusable.**

## The reuse rule, restated

The base template (`AmazonAppDev/react-native-multi-tv-app-sample`) ships ~80% of a working TV app. Your job is *customization*, not *generation*. If you're writing a `<View>` with a `<FlatList>` and `<TouchableOpacity>`, stop. The template has `<Grid>`. Use it.

When you find yourself wanting to write from scratch, the question is always: **what existing component or screen am I about to reinvent?** If the answer is "nothing — this is genuinely new," then proceed (and load `10ft-ui.md` first). Otherwise, reach for the existing piece.

## Anti-patterns at the meta level

- **Skill loaded, not consulted.** A skill is not a flag; it's a process. Open it, follow it.
- **Generating instead of reusing.** Always the wrong default for this codebase.
- **Presenting a one-off as recurring.** Require evidence of recurrence or a clearly general invariant before proposing a candidate.
- **Vague skills.** "Be careful with X" is not a skill. Specific decision trees and anti-patterns are.
- **Treating skills as documentation to read once.** They're programs to execute every relevant turn.

From giolaq/tv-build-harness, MIT-0.

More from giolaq/tv-build-harness