Add comprehensive AI coding agent instructions (e.g. AI promts) for LLM coding agents for improved AI coding agents development efficiency (i.e. GitHub Copilot, Claude Code, and Gemini CLI)

[Hedda]

Suggest adding a custom GitHub Copilot instructions file to GitHub repository as a standardized way for offering AI coding agents guidelines or handbooks (origiginally developed for GitHub Copilot and Microsoft VS Code but these days used by all other AI coding agents as well).

• https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions

The goal you would to achieve with this is to give an AI coding agent more project-specific context and make them produces better code that specifically follow the guidelines set by the project leaders as it meant to describe not only how the project is structured today and development patterns (plus testing approaches) but best practices for how new pull requests should look to simplify PR reviews.

• "Create repository custom instructions files that give Copilot additional context on how to understand your project and how to build, test and validate its changes."

It should also allow you to enable Copilot reviews (GitHub Copilot code review) for this repo which automatically runs and can hopefully catch some common mistakes in new pull requests:

• https://docs.github.com/en/copilot/concepts/agents/code-review
  • https://docs.github.com/en/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review

For reference, many other projects from the Open Home Foundation have now added basic or comprehensive custom instructions (e.g. structured AI promts) used by AI coding agents to guide them to produce more useful outputs for a specific Git repository. See examples in these OHF repos:

• https://github.com/home-assistant/core/blob/dev/.github/copilot-instructions.md
  • https://github.com/home-assistant/core/blob/dev/AGENTS.md
    • https://github.com/home-assistant/core/blob/dev/CLAUDE.md
• https://github.com/music-assistant/server/blob/dev/.github/copilot-instructions.md
  • https://github.com/music-assistant/server/blob/dev/CLAUDE.md
• https://github.com/zigpy/zha-device-handlers/blob/dev/.github/copilot-instructions.md

Note that not all those are following the same standard as usually other project only have a single ,md text-file with contain the source of truth and just have additional promt files that simly symlink to that file for better compatibily with different LLM models. Common example when have the repo on GitHub is make .github/copilot-instructions.md be the source of truth and then have AGENTS.md, CLAUDE.md, and GEMINI.md etc. dummy-files in the root riectory that just symlink to that .github/copilot-instructions.md file.

So recommend at least add comprehensive Copilot instructions file called copilot-instructions.md to help improve AI coding agents development efficiency for this repo, epciallyaly giving clear guidelines for how you would pull requests to be formatted (e.g. only one feature per pull request, etc.), similar to the ones they recently added to other OHF repositories:

Those instructions and promts help GitHub Copilot reviews which looks to have benefited their project. Please also read these for more reference:

• https://docs.github.com/en/copilot/how-tos/configure-custom-instructions
  • https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
  • https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-organization-instructions
• https://github.blog/ai-and-ml/github-copilot/5-tips-for-writing-better-custom-instructions-for-copilot/
• https://copilot-instructions.md/
• https://code.visualstudio.com/docs/copilot/customization/custom-instructions
• https://github.com/github/awesome-copilot
  • https://developer.microsoft.com/blog/introducing-awesome-github-copilot-customizations-repo
• https://dev.to/louis7/3-minute-guide-make-github-copilot-generate-high-quality-code-2cph
  • https://medium.com/@frank.laule/mastering-github-copilot-customization-with-copilot-instructions-83e8cc1ca10a
    • https://github.com/SebastienDegodez/copilot-instructions

FYI, sounds like GitHub went all in on the concept of adding helper prompts to repos during the GitHub Universe 2025 announements:

• https://githubuniverse.com

GitHub also introduced "Agent HQ" mission control panel and announced that it will later comming months/year open up the GitHub ecosystem to third-party coding agents as well, all of which will be able to make use of this type of reusable promts if repos have them:

• https://github.blog/news-insights/company-news/welcome-home-agents/

  • https://github.blog/news-insights/product-news/agents-panel-launch-copilot-coding-agent-tasks-anywhere-on-github/

Tip is that GitHub Copilot have a "Copilot Instructions Blueprint Generator" and other skills that can generate AI instructions:

• https://github.com/github/awesome-copilot/tree/main/skills
  • https://github.com/github/awesome-copilot/blob/main/skills/copilot-instructions-blueprint-generator/SKILL.md
  • https://github.com/github/awesome-copilot/blob/main/skills/technology-stack-blueprint-generator/SKILL.md
  • https://github.com/github/awesome-copilot/blob/main/skills/architecture-blueprint-generator/SKILL.md
  • https://github.com/github/awesome-copilot/blob/main/skills/project-workflow-analysis-blueprint-generator/SKILL.md
  • https://github.com/github/awesome-copilot/blob/main/skills/readme-blueprint-generator/SKILL.md
  • https://github.com/github/awesome-copilot/blob/main/skills/code-exemplars-blueprint-generator/SKILL.md
  • https://github.com/github/awesome-copilot/blob/main/skills/folder-structure-blueprint-generator/SKILL.md

(Do note that if make it simple and initially just add AI-generated AI instructions then it is a good idea to later manually clean up a bit in the future).

Another tip is to check out this collection of community-contributed instructions, prompts, and configurations:

• https://developer.microsoft.com/blog/introducing-awesome-github-copilot-customizations-repo

By the way, that collection was started by Microsoft engineers it has for example ready repository instructions and promts for tests, etc.

• https://github.com/github/awesome-copilot

There looks to be collections and best practice prompts that could perhaps be used as a basis?

• https://github.com/github/awesome-copilot/blob/main/README.collections.md
• https://github.com/github/awesome-copilot/blob/main/README.instructions.md
• https://github.com/github/awesome-copilot/blob/main/README.prompts.md
• https://github.com/github/awesome-copilot/blob/main/README.chatmodes.md

PS: Maybe a copy of this should be added to backlog-issues for OHF-Voice with a checklist if want to add this to all repos and would like to track it?

• https://github.com/OHF-Voice/backlog-issues

PPS: By the way, note that can also add organization custom instructions for GitHub Copilot to the whole OHF-Voice org here on GitHub too(?):

• https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-organization-instructions

[Hedda]

Oh, regardless of how add above you probably also want to add a file with an AI-policy too (i.e. a repository-level AI contribution policy) that clearly states how you expect the usage of AI look like. Meaning that you explain expectations for using AI tools when submitting PRs and communicating with maintainers.

That should make it clear that AI is a tool and that humans need to be in the loop.

See this PR which I think will probably add such a file to Home Assistant’s core repo after changes has been made to it:

• Add AI policy to core home-assistant/core#167047

This document must be explicitly linked from contributor entry points (for example, CONTRIBUTING.md and the pull request template) so that contributors can easily discover and follow it.

[MemoAsh]

One structure that may keep this maintainable across Copilot, Claude Code, Gemini, and Codex is to separate the instruction file by job:

AGENTS.md                         # portable repo-wide rules
.github/copilot-instructions.md   # GitHub/Copilot bridge if needed
CLAUDE.md                         # Claude bridge if needed
GEMINI.md                         # Gemini bridge if needed

Then keep AGENTS.md focused on things that should be true for every agent:

• project layout and important packages
• setup/test commands
• PR expectations
• files or areas that require extra care
• what the agent must verify before saying done

For a project like this, I would also add a small verification section, not just coding style. For example:

• state which command was run
• state which hardware/audio path was not tested
• do not claim microphone/speaker behavior is verified unless it was actually exercised
• keep PRs to one feature or fix

I made a small example repo showing the pattern as AGENTS.md plus task-specific workflow files:

https://github.com/MemoAsh/agent-workflow-pack

The most relevant part is probably the verification checklist idea. It helps AI-agent instructions behave less like a one-time prompt and more like a repeatable project workflow.

[omaramin-2000]

This one is in progress: #356

[ofekron]

PR #356 is useful progress, especially the hardware-verification caveat and completion receipt. I would address a few cross-provider and maintenance issues before merging the instruction design.

1. Choose one authoritative file. The PR currently repeats overview, architecture, commands, quality rules, and verification facts in both AGENTS.md and .github/copilot-instructions.md. They will drift. I would make AGENTS.md the portable source of truth and keep provider files as minimal adapters generated/validated from it.

2. Do not rely on symlinks or “see another file” alone. Symlink handling differs across Windows, Git clients, sandboxes, and providers. Some agents will not automatically follow a prose reference. A small generation/check script gives portability and CI drift detection.

3. Keep claims aligned with executable evidence. The instructions say verify Python 3.11, 3.12, and 3.13, while the PR description says tests run on 3.12 and lint on 3.13. Agents should run only available checks and report unverified versions explicitly rather than claiming the whole matrix.

4. Separate contribution policy from coding instructions. Human accountability, AI disclosure, and review expectations belong in a linked AI contribution policy/CONTRIBUTING entry, not only in model prompts.

5. Use least privilege. The new kilo.json grants bash and wildcard read access. Repository instructions should not silently widen tool permissions; permission configuration needs its own review and the smallest scope required.

6. Keep volatile inventories out of long prompts. File lists and architecture summaries age quickly. Prefer stable navigation rules and commands that let the agent inspect the current tree.

Maintainer disclosure: these lessons come from Better Agent, a multi-provider local workspace I’m building for Claude, Codex, Gemini, and other coding agents: https://github.com/ofekron/better-agent

It is source-available and free for non-commercial use; commercial use requires separate permission. Its provider-config sync path defines capabilities once, applies native provider projections, and checks for drift rather than hand-maintaining duplicate instructions.

[Hedda]

Example from the Music Assistant server repo which is also governed by the Open Home Foundation:

• https://github.com/music-assistant/server/blob/dev/AGENTS.md

Also add AI_POLICY.md to point developers to before they submit PRs developed with the help of AI:

• https://github.com/music-assistant/.github/blob/main/AI_POLICY.md

"*Please have a look at our AI Policy before contributing code or documentation.*"

[florian-asche]

I need some help with that topic. I would like to have some simple help for AI with this project, if i guess, that is the AGENTS.md right? Do i need a CLAUDE.md or GEMINI.md too?

I would love to have just one for all AI's.

I would love to have a AI in the PR review that helps us. Do you know how that works?

What is the AI_POLICY good for?

[florian-asche]

I made a new PR just for AI stuff here: #366

[Hedda]

Do i need a CLAUDE.md or GEMINI.md too?

You do not need those anymore, (before you needed those or symbolic links as direct to AGENTS.md). Today they all know to look at AGENTS.md

[Hedda]

I would love to have a AI in the PR review that helps us. Do you know how that works?

That is done separately via agents optimized per GitHub repo, so suggest you talk to OHF leads on how they have that setup.

Ping @marcelveldt

[florian-asche]

Hm ok, then i split even more and put that github repo OHF stuff into another MR.

[florian-asche]

Would love to have your feedback to #366 here, will merge when u say its ok!