Skip to content

Provide AI coding assistant support: AGENTS.md + Agent Skills #35

Description

@linyuqing222

Summary

Add two complementary AI development aids to the template:

  1. A top-level AGENTS.md — always-on repo orientation.
  2. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions