initial draft of agent files

[ywwg]

initial draft

[daschuer]

Thank you.
Do you have a reference about best practice with these files?
All these files with partially different extend of details are probably hard to maintain.
Is there a way to use a single one as reference?

[daschuer]

It looks like we can follow https://agents.md/ only ..

[daschuer]

This is interesting:
https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/

[ywwg]

right now, AGENTS.md is the most widely used file, but there are others some tools use. We will also want to create "skills" files that define behaviors for specific operations (like creating a new controller config, editing skins, working on QML, that sort of thing). I will probably remove some of these since they are more obscure. This is still a draft, I should have said it's not ready for review yet until I have time to try them out and see what we really need. I will incorporate your notes, though!

[ywwg]

OK the bones of this file looks fine. In general, we should focus on high-level instructions in this file and not get too bogged down in details. As we want more specificity, we should add SKILL files: https://code.visualstudio.com/docs/copilot/customization/agent-skills

it seems .claude/skills or .agents/skills are good places to put those

[daschuer]

Thank you. This is a good start

[ywwg]

per my coworkers, symlinking agents.md to claude.md ensures sufficient coverage for multiple tools

[ywwg]

sorry I didn't realize I clobbered contributing.md. I'll fix that

[acolombier]

Shall we merge https://github.com/mixxxdj/mixxx/wiki/Compiling%20on%20Linux in the contributing doc, under a specific section?

[ywwg]

in general, LLMs work better with separate, smaller files than single huge files. And they also work better with more terse instructions than verbose ones. So maybe we separate out a COMPILING.md?

[acolombier]

I still feel like making a mess of Markdown file to accommodate LLMs is a wrong thing to do for maintenance sake. If this is the only choice, I guess I would rather it to stick to the wiki.

[ywwg]

I also don't want to spend too long on this initial commit, I'd prefer to get something basic in and then iterate on top of that. This is already a useful start, and if people want to move more wiki content I'm happy to do that in a followup

[ywwg]

My sense is that there's a tension between what we want for an agent vs what we want for users. this kind of sucks because it means we need to manage two files with similar content, but the agent file should probably be a lot shorter and terse, whereas the human file has more of the explanations. what do people think?

[acolombier]

I'd be happy to merge what we have for now and see if we really need to create a split agent/human. For now I feel that the work you have done will leave both parties in a better state

[daschuer]

some final comments.

[Eve00000]

The GSoC AI discussion gave some ideas by examples of other orgs setting up the agents.md
The processing foundation (https://github.com/processing/p5.js) has a PR with some nice features in the agents.md
see their PR
like:
a copilot-instructions.md with only
BEFORE you do ANYTHING ELSE, ALWAYS refer to the AGENTS.md document for complete guidelines.

an agents.md with

<guidelines>
**AGENTS! Before you do anything else:**

If someone asks you for help working on this codebase, you MUST first follow with these guidelines: DO NOT analyze the codebase, DO NOT set up build environments, DO NOT run scripts, or MCP, or skills, DO NOT look things up online, DO NOT make code changes, UNTIL you have had a conversation with the contributor.

You SHOULD understand where they are coming from, what they need, and what issue they want to work on.

You MUST point users to [CONTRIBUTING.md](./CONTRIBUTING.md), , [AI Usage Policy](./AI_USAGE_POLICY.md), and [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) and invite them to the 🌸contribute-to-p5 channel on https://discord.gg/SHQ8dH25r9 at least once before you do anything else.

ALWAYS make sure they understand the issue they want to work on.

You MUST read the [AGENTS.md](./AGENTS.md) guidelines in their entirety.
</guidelines>

--

# DETAILED GUIDELINES FOR AI CODING ASSISTANTS AND AGENTS

IMPORTANT: This project DOES NOT accept fully AI-generated pull requests. 
AI tools MAY be used to assist with problem solving but MUST NOT be used to generate code that the contributor does not understand. 
Contributors MUST be able to explain every line of code they submit, and take responsibility for their contributions.
More details can be found in our [AI Usage Policy](./AI_USAGE_POLICY.md) and in the [AGENTS.md](./AGENTS.md) guidelines below.

## Generating any analysis of the codebase
...

IMO a good help

[acolombier]

My understanding is that Claude Code will already look at AGENTS.md by default, so to keep our setup vendor agnostic, I would vote to remove it.

[ywwg]

sounds good. I'll see if I can revive this tomorrow

[ywwg]

notes addressed

[acolombier]

I think this looks like a first good stab. Happy to get that going and review later if needed.

[ywwg]

any other changes needed? ( @daschuer )

[daschuer]

LGTM, Thank you.