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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions