Summary
Add two complementary AI development aids to the template:
- A top-level
AGENTS.md — always-on repo orientation.
- One or more Agent Skills (
SKILL.md folders) — on-demand,
task-specific packages for the repeatable parts of add-on work.
Both are open formats supported across major coding agents, so the same files
work regardless of which assistant a contributor uses.
Motivation
A growing share of add-on developers, including blind and low-vision developers,
now work with AI coding assistants. NVDA add-on conventions are niche
and thinly documented compared with mainstream frameworks,
so these tools can't be assumed to have reliable knowledge of them.
Without project-specific guidance they are likely to guess, producing code
that needs rework before it builds or passes review.
The areas where guidance would help most:
manifest.ini fields and buildVars.py configuration
- The scons-based build and packaging step
- The gettext localization flow
- Placement and structure of
globalPlugins vs appModules
minimumNVDAVersion / lastTestedNVDAVersion and API compatibility
- Add-on Store submission requirements
The template already exists to lower the barrier to starting an add-on.
Shipping maintained AI aids extends that same benefit to the now-common case
of developing with an assistant.
Why both, and how they divide
AGENTS.md and skills are complementary, not alternatives:
AGENTS.md loads as soon as the agent opens the repo.
It answers "how does this repo work and what must I not break."
- Skills load only when relevant and can bundle scripts and templates.
They answer "do this specific repeatable task correctly."
Proposal
AGENTS.md (orientation):
- Repo layout and what each key file does (
manifest.ini, buildVars.py,
sconstruct, addon/, etc.)
- How to build and package the add-on
- API version fields and how to set them
- Conventions/constraints not to violate (e.g. avoid global plugins that run
on every key press, for performance)
- Pointers to the NVDA Add-on Development Guide and Add-on Store submission docs
Skills (candidates, one SKILL.md folder each):
- Scaffold a
globalPlugin / appModule
- Run the gettext localization workflow
- Build and package into a
.nvda-addon
- Generate Add-on Store submission metadata
Summary
Add two complementary AI development aids to the template:
AGENTS.md— always-on repo orientation.SKILL.mdfolders) — on-demand,task-specific packages for the repeatable parts of add-on work.
Both are open formats supported across major coding agents, so the same files
work regardless of which assistant a contributor uses.
Motivation
A growing share of add-on developers, including blind and low-vision developers,
now work with AI coding assistants. NVDA add-on conventions are niche
and thinly documented compared with mainstream frameworks,
so these tools can't be assumed to have reliable knowledge of them.
Without project-specific guidance they are likely to guess, producing code
that needs rework before it builds or passes review.
The areas where guidance would help most:
manifest.inifields andbuildVars.pyconfigurationglobalPluginsvsappModulesminimumNVDAVersion/lastTestedNVDAVersionand API compatibilityThe template already exists to lower the barrier to starting an add-on.
Shipping maintained AI aids extends that same benefit to the now-common case
of developing with an assistant.
Why both, and how they divide
AGENTS.mdand skills are complementary, not alternatives:AGENTS.mdloads as soon as the agent opens the repo.It answers "how does this repo work and what must I not break."
They answer "do this specific repeatable task correctly."
Proposal
AGENTS.md(orientation):manifest.ini,buildVars.py,sconstruct,addon/, etc.)on every key press, for performance)
Skills (candidates, one
SKILL.mdfolder each):globalPlugin/appModule.nvda-addon