docs: make Remix docs readable and installable by AI agents
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
- Domain
- devtools, documentation
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
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/remixandhttps://concepta.dev/llms.txtreturnHTTP/2 429withx-vercel-mitigated: challengeto curl and to agent fetch tools (checked 2026-11-04). - No llms.txt.
https://btwld.github.io/remix/llms.txtreturns 404, and nothing inapps/docsgenerates 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 --listlistsusing-remixandbuilding-remix-design-system. The setup instructions inusing-remixare unpinned (tracked in #383).
Reference
TanStack AI's agent skills setup has three parts.
- Install discovery skills (
npx skills add …). - Run an installer that writes a committed block into the agent config file.
- Verify in a fresh agent session against concrete expected output (for example "uses
chat(), notstreamText()").
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.txton concepta.dev, or serve them from a host without it. - Generate
llms.txt(andllms-full.txtif 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/remixnext 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
curlof a docs page and ofllms.txton the canonical host returns 200.- A fresh agent session given only the setup prompt in an empty Flutter app reaches clean
flutter analyzeandflutter 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from btwld/remix
-
Difficulty 2/5 1-3 hours Newbie friendliness 80/100
Maintainers usually reply within 1 day
-
Difficulty 3/5 Half a day Newbie friendliness 65/100
Maintainers usually reply within 1 day
-
Difficulty 3/5 Half a day Newbie friendliness 68/100
Maintainers usually reply within 1 day
-
Difficulty 3/5 Half a day Newbie friendliness 62/100
Maintainers usually reply within 1 day
-
Difficulty 3/5 1-2 days Newbie friendliness 55/100
Maintainers usually reply within 1 day
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
AppFlowy-IO/AppFlowy#9147 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
Difficulty 1/5 Under an hour Newbie friendliness 62/100
ccch1mneyyy/dsh-Go#1682 ·
Maintainers usually reply within 1 day
-
help wanted
Difficulty 1/5 Under an hour Newbie friendliness 76/100
pesaclarity/ujumbe-parsers#64 ·
Maintainers usually reply within 1 day
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
patarapolw/lingua_srs#278 ·
Maintainers usually reply within 1 day