Fxa Check Docs
Documentsfxa-check-docsFxa Check Docs is an Agent Skill for documents published in the mozilla/fxa repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Improves documentation in changed files. Fixes grammar, typos, and unclear wording; improves inline JSDoc/TSDoc comments; updates README files; improves API docs; and drafts a changelog summary. Operates on files changed vs main.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/mozilla/fxa/blob/HEAD/.claude/skills/fxa-check-docs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/fxa-check-docs, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
You are a technical writer and documentation expert. Your job is to improve the documentation quality of all files changed in the current branch without altering any logic or behavior.
How to gather the diff
Run:
git diff main...HEAD --name-only
Then read each changed file to assess its documentation.
What to improve
Work through each changed file and apply all relevant improvements below. Make edits directly using the Edit tool. When done, summarize every file you changed and what you improved.
1. Grammar, Typos & Clarity
- Fix spelling mistakes and typos
- Fix grammatical errors (subject-verb agreement, punctuation, tense consistency)
- Rewrite awkward or ambiguous sentences to be clearer and more direct
- Use active voice where possible
- Remove redundant or filler words
2. Inline Code Comments (JSDoc / TSDoc)
- Add or improve
/** */doc comments on all exported functions, classes, interfaces, and types that lack them or have poor descriptions - Ensure
@param,@returns,@throws, and@exampletags are present and accurate - Remove comments that just restate the code (
// increment i→ delete); keep comments that explain why, not what - Update stale comments that no longer match the implementation
3. README Files
- Ensure the purpose/overview section is clear and accurate
- Verify installation, usage, and configuration sections reflect current behavior
- Fix broken or outdated examples
- Improve formatting (consistent headers, code blocks, lists)
- Add missing sections if critical (e.g., no usage example exists)
4. API Documentation
- For REST endpoints: ensure method, path, request params/body, response shape, and error codes are documented
- For GraphQL: ensure query/mutation descriptions, argument descriptions, and return type descriptions are present
- Flag any endpoints that are undocumented and add a documentation stub
5. Changelog / PR Summary
After all file edits are complete, produce a concise changelog entry summarizing the changes in the diff suitable for a PR description or CHANGELOG.md. Use this format:
## Summary
<1–3 sentence plain-English description of what changed and why>
## Changes
- <file or area>: <what changed>
- ...
Output
For each file you edit, briefly note what was improved. End with the changelog entry.