docs: make Remix docs readable and installable by AI agents

Open
#385 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
dart, flutter

Research direction

Start by reading the docs app under apps/docs and the existing using-remix skill; the issue says no generator currently creates llms.txt. Check how the docs are built and served on both hosts, and how Getting Started and the README are organized. Done when the canonical host serves readable docs and generated llms.txt, and the setup prompt has versioned installs and verifiable checks.

Written by the indexing model from the issue text.

Description

documentation enhancement

Purpose

Remix ships agent skills (npx skills add btwld/remix) and Agent UI surfaces, but its docs are hard for AI agents to read and there is no guided agent setup. This issue makes the docs machine-readable and adds a copyable setup prompt with verifiable "done when" checks.

Depends on #383 for pinned versions. The prompt must not reintroduce unversioned install commands.

Evidence

  • concepta.dev blocks non-browser clients. https://concepta.dev/documentation/remix and https://concepta.dev/llms.txt return HTTP/2 429 with x-vercel-mitigated: challenge to curl and to agent fetch tools (checked 2026-11-04).
  • No llms.txt. https://btwld.github.io/remix/llms.txt returns 404, and nothing in apps/docs generates one.
  • Two hosts serve the docs. https://btwld.github.io/remix/ (200) and https://concepta.dev/documentation/remix. It's unclear which one is canonical.
  • The skills work. npx skills add btwld/remix --list lists using-remix and building-remix-design-system. The setup instructions in using-remix are unpinned (tracked in #383).

Reference

TanStack AI's agent skills setup has three parts.

  1. Install discovery skills (npx skills add …).
  2. Run an installer that writes a committed block into the agent config file.
  3. Verify in a fresh agent session against concrete expected output (for example "uses chat(), not streamText()").

Remix has the first part. The verification checklist is the most useful part to copy.

What to build

  • Let bots through the challenge for docs paths and llms.txt on concepta.dev, or serve them from a host without it.
  • Generate llms.txt (and llms-full.txt if cheap) from the docs app.
  • Add a copyable setup prompt to Getting Started and link it from the README. Draft below. Versions come from the docs build, not typed text.
  • Link npx skills add btwld/remix next to the prompt.
  • Decide which docs host is canonical and redirect the other one.

Draft prompt:

Set up Remix (Flutter components) in this project.

1. Run `flutter --version`; require Flutter 3.44 or newer.
2. Install exact prereleases (unversioned installs pick old 0.x releases):
   flutter pub add remix:^{{remix}}
   flutter pub add dev:remix_cli:^{{cli}}
3. Install agent skills: npx skills add btwld/remix
   Read skills/using-remix/SKILL.md before writing UI code.
4. dart run remix_cli:remix init --preset vanilla
   dart run remix_cli:remix add button
5. Put UiTheme in WidgetsApp.builder (above the Navigator), render
   UiButton.primary, then run `flutter analyze` and `flutter test`.

Done when: analyze is clean; code uses UiButton/Ui* from lib/ui/ui.dart
(not hand-built Remix stylers); uses `.padding(.horizontal(16))` and
`.borderRadius(.circular(8))`, never `paddingAll`/`borderRounded`;
never edits *.g.dart.

Completion criteria

  • curl of a docs page and of llms.txt on the canonical host returns 200.
  • A fresh agent session given only the setup prompt in an empty Flutter app reaches clean flutter analyze and flutter test, and its code passes every "done when" check.

Non-goals

A remix agents installer that writes AGENTS.md blocks, like TanStack Intent. Revisit it once the prompt has proven useful. Note that pub's global cache makes "point at the skill inside the installed package" harder than with node_modules.

Dominant language
Dart
Stars
24
Forks
5
Avg merge
15h 29m
Merged PRs (30d)
144

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from btwld/remix

All issues in btwld/remix

Similar issues

More Dart issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.