Construct agent and skill files from common templates

[klinvill]

@elefthei currently there's some duplication in the agent files. This is only two copies of one file so it's not too bad to manage, but I wanted to open this draft PR to surface what my previous comment (in #1) about potentially using common templates could look like. Granted, it adds a lot of extra boilerplate and a github action should be created to automatically run the python script that generates the latest output agent and skill files, then push those files to a deployment branch that the plugins can be pulled from. Any thoughts on if this is a desirable direction to go (avoiding duplication for agent files) or if it's just overkill for the current plugins?

This draft adds in a jinja template for the agent file (under templates/agents/fstar-coder.md.j2). The template accepts a key-value dictionary of header entries and renders it as a YAML header. This draft also adds a python script (generate_plugins.py) that reads custom headers for each vendor (e.g. templates/agents/claude.headers.yaml) and injects them into a rendered agent file for that specific vendor (copilot or claude). The rendered files are saved under the out/<vendor> directory, so currently the rendered copilot agent files get saved to the out/copilot/plugins/proof-copilot/agents/ directory. Having a separate output directory makes it easy to ensure that files meant for a different vendor do not end up getting installed along with the plugin (I believe claude code will currently pull the fstar-coder.agent.md file down as well). The skills files currently aren't specialized for either vendor so the python script currently just copies them over to the output directories.

If you want to give this a try yourself, I set it up using the uv python package manager. Installation instructions for uv are at https://docs.astral.sh/uv/getting-started/installation/. Once it's installed, you can just run uv run python generate_plugins.py and uv will handle the python environment setup and installation for you.

[elefthei]

Hi @klinvill I am not seeing the duplication you identified, can you reply with maybe two duplicate files? Using Jinja here seems like a good idea, but still if we can avoid the CI indirection that would be best.

[klinvill]

Sure! They're not exact duplicates, but the fstar-coder.agent.md and fstar-coder.md files differ only in the headers. Specifically, diffing those two files gives the following output:

4c4,5
< tools: ["bash", "edit", "view", "glob", "grep", "task"]
---
> model: opus
> tools: Bash, Read, Edit, Write, Glob, Grep, Agent

Regarding avoiding CI indirection, another option is to just manually regenerate any vendor-specialized agent and skill finals with each commit (could maybe use a git hook?). My preference is to not have any generated/output static files in the branch that people commit and merge to, and to have a separate deploy branch that is only ever written to by a CI job that is triggered any time the main branch receives new commits (this is effectively the workflow I use for my personal website). There are definitely other valid options though that avoid CI but come with their own tradeoffs (like the use of local git hooks). Note that this draft PR doesn't currently add any additional instrumentation like hooks or CI, so I'm happy to update it or feel free to fork it off yourself to experiment with if the templating is a useful start!