My personal suggestion is that whatever docs you’re trying to write, please consider writing them primarily for people instead.
On one hand, whether or not “AI agents are here to stay”, it’s clear that things will continue to change a lot, throwing massive churn what are effective ways to run these “skill files”. It’s massively unclear that what we have as the best practices at prompting LLMs would still be relevant even after a few months. Prompts like “do not invent flags” could literally become irrelevant overnight — who knows.
On the other hand, LLMs are supposed to be able to ingest natural language, so by writing for people, you will also reap the benefits of clearer documentation immediately for people working on the code.