After adopting Agent Skills as the standard way to give Cursor and Claude Code domain context, I built a project-specific skill for React Native apps that follow the U.S. Web Design System (USWDS). The skill lives in a dedicated repo so it can be installed as a remote rule in any RN/USWDS project. This post describes what the skill provides, how it’s structured, and how skills-based context improves agent-assisted development.

Skill repository: github.com/vancedenson-ac/react-native-uswds

Why a USWDS React Native Skill?

• Narrow domain: USWDS has specific tokens (colors, spacing, radius), component semantics, and accessibility expectations. Generic agents often hardcode hex values, use TouchableOpacity, or skip accessibilityRole/accessibilityLabel.
• Library coupling: Our app uses a local library (./rn-uswds-components) that mirrors USWDS in React Native—theme API, USA-prefixed components, usePressAnimation, web vs native branching. The agent needs that layout and those conventions in context.
• Consistency: One skill ensures theme tokens, component choice, and accessibility rules are applied consistently across features and refactors without re-explaining in every chat.

A single skill packages “when to use this,” “how we implement it,” and “what’s wrong/right” so the agent can apply it automatically when working on RN/USWDS UI.

What the Skill Provides

1. SKILL.md — Entry Point and Conventions

The skill’s SKILL.md defines:

• Description (frontmatter): When the skill applies: implementing UI with rn-uswds-components, mapping USWDS tokens to RN theme, choosing USA components, theming, accessibility/government-style consistency.
• Official USWDS refs: Links to designsystem.digital.gov, design tokens, theme color tokens, components overview.
• When this skill applies: App uses (or will use) rn-uswds-components; tasks involve tokens, component selection, or integration.
• Core conventions:
  • Theme via useUSWDSTheme() / USWDSThemeProvider; no hardcoded USWDS values.
  • Prefer USA-prefixed components; Pressable (not TouchableOpacity); StyleSheet.create + theme for static styles.
• Implementation notes: Library layout (theme/, hooks/, components/<Name>/, barrel), web vs native press feedback, usePressAnimation, accessibility props, theme override via partial theme in the provider.
• Quick reference table: Spacing, colors, buttons, forms, feedback, layout, overlay, data/nav, typography — which token or component to use.
• Integration checklist: Peer deps, provider usage, barrel imports, prefer props over custom wrappers.
• Rules table: Eight rules with impact (HIGH/MEDIUM/LOW) and pointers to rules/*.md and AGENTS.md.

Example “quick reference” slice from the skill:

The agent gets this without opening the full design system site; when it needs deeper token or API detail, it follows links to references/.

Structure: SKILL + References + Rules + AGENTS.md

The repo is organized so the agent loads metadata and core instructions first, then references and rules on demand.

react-native-uswds/
├── SKILL.md              # Main skill: when, conventions, quick ref, rule index
├── AGENTS.md             # Compiled agent guide: refs, implementation notes, rules by category
├── README.md
├── LICENSE
├── references/
│   ├── official-links.md       # When to use each USWDS doc/site
│   └── tokens-and-components.md # Token tables + component API summary
└── rules/
    ├── theme-use-tokens.md
    ├── components-usa-prefix.md
    ├── accessibility-preserve.md
    ├── styling-style-sheet.md
    ├── platform-web-fallback.md
    ├── provider-theme-override.md
    ├── pressable-not-touchable.md
    └── imports-barrel.md

• SKILL.md: Single place for “when this skill applies,” core conventions, and the rule index. Kept under ~500 lines; heavy detail lives in references/ and rules/.
• references/: Progressive disclosure. official-links.md tells the agent which USWDS page to hit for tokens vs components vs accessibility. tokens-and-components.md gives spacing/color/typography/radius/shadow/z-index tables and a component summary (props, variants).
• rules/: One file per convention, each with incorrect/correct code examples and impact. The agent (or human) can open the specific rule when refining or reviewing code.
• AGENTS.md: Flattened view for automation: official refs, implementation notes, quick reference, and rules grouped by theme/tokens, components/styling, accessibility/platform, integration. Useful when the agent is given “follow AGENTS.md” or when the skill is used in a context that prefers a single doc.

This follows the same pattern as in Cursor Skills Guide: progressive loading — metadata and SKILL body first, references and rules when needed.

Rules: What the Agent Enforces

Each rule file is short, with a clear wrong vs right so the agent can correct its own or existing code.

Theme and tokens (HIGH)

theme-use-tokens: All USWDS values must come from the theme.

Incorrect:

const styles = StyleSheet.create({
  box: {
    backgroundColor: '#005ea2',
    padding: 16,
    borderRadius: 8,
  },
})

Correct:

function MyComponent() {
  const theme = useUSWDSTheme()
  const styles = useMemo(() => StyleSheet.create({
    box: {
      backgroundColor: theme.colors.primary,
      padding: theme.units(2),
      borderRadius: theme.radius[2],
    },
  }), [theme])
  return <View style={styles.box} />
}

Components (HIGH)

components-usa-prefix: Prefer USA-prefixed library components over custom equivalents.

Incorrect: Custom Pressable + hardcoded styles mimicking a button.
Correct: import { USAButton } from '../rn-uswds-components' and <USAButton variant="primary" onPress={onSubmit}>Submit</USAButton>.

Accessibility (HIGH)

accessibility-preserve: When wrapping USA components, preserve or forward accessibilityRole, accessibilityLabel, accessibilityState.

Incorrect: Wrapping USAButton in a View that captures touch and doesn’t forward a11y props.
Correct: Use USAButton directly or forward props (e.g. accessibilityLabel={label} {...props}).

Platform and interaction (MEDIUM)

pressable-not-touchable: Use Pressable for custom tap targets; on native use usePressAnimation for scale/opacity; on web use opacity-only to avoid DOM issues.

Incorrect: TouchableOpacity with activeOpacity={0.8}.
Correct: Pressable with usePressAnimation({ scaleActive: 0.98 }) and pass onPressIn/onPressOut and animatedStyle.

Other rules cover styling (StyleSheet.create + theme), theme override via USWDSThemeProvider, web fallback for press feedback, and barrel imports. Each rule file is linked from SKILL.md and AGENTS.md so the agent can open the right one when editing or reviewing.

How I Used the Skills Methodology

1. Followed the skill contract: One directory, SKILL.md with name and description, optional references/ and rule-like files. The repo is structured so it can live under .cursor/skills/react-native-uswds/ or be pulled as a remote rule from GitHub (Cursor loads it as agent-decided context).
2. Description = discovery: The frontmatter description lists concrete trigger cases (rn-uswds-components, tokens, USA components, theming, accessibility). That’s what the agent uses to decide “this skill is relevant” when I’m working on a screen or a component.
3. Progressive disclosure: SKILL.md stays a single, scannable doc; token tables and component APIs live in references/tokens-and-components.md; “when to use which official link” in references/official-links.md. The agent doesn’t need to load every table up front.
4. Rules as executable guidance: Each rule has incorrect/correct snippets. That gives the agent a clear target when generating or refactoring code (e.g. “use theme tokens” or “use USAButton”).
5. AGENTS.md for single-doc consumers: Some flows (or other tools) prefer one compiled doc; AGENTS.md is that view, with the same rules and refs organized by category.

I didn’t use the built-in create-skill skill for the initial draft; I had an existing set of markdown notes and rule-style docs. I restructured them into the standard layout (SKILL.md + references + rules) and added frontmatter and the “when this skill applies” section so Cursor could treat it as a skill. The create-skill flow would work well for a net-new skill (e.g. another design system or stack).

How Skills Assist Development in Practice

• Fewer repeated instructions: I no longer say “use theme tokens, not hex” or “use USAButton” in every task. The skill is attached when the project (or chat) has the skill installed; the agent applies the rules from SKILL.md and the rule files.
• Consistent corrections: When the agent suggests hardcoded colors or TouchableOpacity, I can point it at the skill or the specific rule; the incorrect/correct examples steer the next edit.
• Onboarding and audits: New contributors (or future me) can read SKILL.md and AGENTS.md to see how we do USWDS in RN. The same files drive the agent, so human and agent stay aligned.
• Reuse across projects: The skill lives in vancedenson-ac/react-native-uswds. Any RN/USWDS app can add it as a Cursor remote rule and get the same conventions and references without copying markdown into each repo.

Installing and Using the Skill

1. As a Cursor remote rule (GitHub):

   • Cursor Settings → Rules → Project Rules → Add Rule → Remote Rule (Github).
   • Enter: https://github.com/vancedenson-ac/react-native-uswds
   • Cursor syncs the repo; the skill’s SKILL.md and structure are used as agent-decided context when relevant.

2. Local clone (e.g. in a monorepo):

   • Clone or copy the repo into .cursor/skills/react-native-uswds/ (or ~/.cursor/skills/react-native-uswds/ for user scope).
   • Cursor discovers it on startup; the agent applies it when the description matches the task.

3. Manual invocation: If the skill is available in your environment, you can type /react-native-uswds in Agent chat to pull it into context for the next request.

Takeaways

• Skills = domain in a box. For USWDS + React Native, one skill encodes tokens, components, accessibility, and platform behavior so the agent doesn’t guess or hardcode.
• SKILL.md + references + rules keep the main doc small and load heavy detail on demand; AGENTS.md gives a single-doc view for automation or readers.
• Wrong/right rule files make the skill “executable”: the agent can correct against concrete examples.
• Hosting the skill in a repo makes it reusable and version-controlled across projects and teams.

If you’re building React Native UIs that mirror USWDS (or a similar design system), packaging your conventions and references as a skill—following the Agent Skills layout—will make agent-assisted development more consistent and less repetitive. The react-native-uswds repo is a working example you can fork or install via Cursor’s remote rules.

Resources

• React Native USWDS Agent Skill — This skill (SKILL.md, AGENTS.md, references, rules).
• Cursor Skills Guide — Skills overview, SKILL.md format, references, rules, scripts.
• U.S. Web Design System — Official design system and components.
• USWDS Design Tokens — Token philosophy and theme tokens.
• Cursor Docs: Context → Skills — Skill directories, optional dirs, migration.
• Cursor Docs: Remote rules (GitHub) — Installing skills/rules from a repo.
• Agent Skills (agentskills.io) — Open standard and specification.