agent-first-docs
Skill0 starsChanged 7 days agoMITView on GitHub
Write a product's docs, quick start or marketing page around one copyable coding-agent prompt, and serve docs as agent-readable Markdown (llms.txt, .md URLs). Use for onboarding docs, quick starts, product pages, heroes and CTAs.
In this repository27 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- analytics-reviewSkill
- autopilotSkill
- browseSkill
- create-prSkill
- design-uiSkill
- foremanSkill
- harness-auditSkill
- image-genSkill
- implementSkill
- investigateSkill
- marketing-videoSkill
- plan-draftSkill
- qaSkill
- reconSkill
- release-prdSkill
- releaseSkill
- review-prSkill
- semantic-decisionSkill
- setup-projectSkill
- teamSkill
- telemetry-reviewSkill
- testSkill
- token-auditSkill
- triageSkill
- ui-auditSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Keep it in one maintained source per language.
- Distinctive: line 33
Never invent speed/savings claims, prices, customers, integrations, guarantees or release/license status.
- Distinctive: line 35
Verify every command against the product's current contract and provider docs.
- Very specific: line 41
Verify the built result through the project's browser workflow: text fit on desktop and mobile, plus one adverse case (unknown .md URL, …
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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.
Files
agent-first-docs
The 2found convention for how a product introduces itself: a reader — human or
agent — gets from "what is this" to a working first result by pasting one
prompt into a coding agent. Derive the requirement from supplied artifacts or
conversation; no ticket gate. Shared refs are filesystem paths beside this
skill's directory, so read them by path, not as skill://.
The one prompt
- Keep it in one maintained source per language; the docs quick start and the marketing CTA both render it from there. Never write a second prompt.
- It names the task, the public Markdown docs URL, the optional source repo and the result the agent must verify. No placeholders; no mandatory plugin install unless the product needs one.
- It opens the quick start, before prerequisites or install commands, after a one-line invitation.
Surfaces
| Surface | Leads with | Keeps out |
| Marketing page | What the visitor achieves; one primary CTA (the prompt as a concrete activation task) and a secondary docs link | Manifest fields, command grammar, full procedures — they live in docs |
| Docs / quick start | The prompt, then setup paths, then focused references | Marketing claims |
Rules
- Make setup actionable from where the user is: for each real barrier (account, billing, VM, credentials) say what the user supplies, what the agent does, the path when the resource is missing, and the completion check. Credentials travel as a private file or secret-store reference, never values in chat or argv.
- Never invent speed/savings claims, prices, customers, integrations, guarantees or release/license status. Keep material limitations in fit guidance or FAQ.
- Verify every command against the product's current contract and provider docs; examples are not authorization to create live resources.
- Hosted docs follow AX Markdown delivery. Preserve existing URLs when improving paths; verify the CTA's real target and language.
- Reuse the host's components, tokens and copy controls; keep translations and metadata aligned.
- Verify the built result through the project's browser workflow: text fit on
desktop and mobile, plus one adverse case (unknown
.mdURL, clipboard denied, broken CTA target). Leave changes reviewable; publishing is the caller's.
Output
STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
VERDICT: DOCUMENTED
SUMMARY: <surfaces changed, prompt source, AX endpoints, verification, limits>
NEXT: <remaining action or none>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
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.