Add initial agents/claude tooling. #360
Conversation
sudomateo
left a comment
sudomateo
left a comment
There was a problem hiding this comment.
I'll probably write this up more broadly internally but I don't want to be overly dogmatic when it comes to reviewing and merging AI agent content like AGENTS.md, slash commands, and skills. This whole space is rapidly changing so anyone with maintainer access to this repository should be empowered to merge changes to such files without an overly strict review. The only thing I ask is to keep https://agents.md compatibility in mind for those that don't use Claude Code.
AGENTS.md
Outdated
|
|
||
| For local testing, set `OPENAPI_SPEC_PATH` environment variable to use a local spec file instead. | ||
|
|
||
| **Claude skill:** Use `/fetch-spec` to automatically fetch the spec and save it to |
There was a problem hiding this comment.
This is technically a slash command rather than a skill. I know it's all just blurred at this point but just letting you know.
There was a problem hiding this comment.
TIL. I'm changing this to a proper skill so claude can discover it.
.claude/commands/fetch-spec.md
Outdated
| 4. Report what you found: | ||
| - The Omicron commit version | ||
| - The versioned spec filename | ||
| - Confirm the spec was saved to `/tmp/oxide-openapi-spec.json` |
There was a problem hiding this comment.
Can this save outside the current working directory?
There was a problem hiding this comment.
Yep, it'll ask permission, but it works.
.claude/commands/fetch-spec.md
Outdated
There was a problem hiding this comment.
I'll test this with Amp and others, but I think we should put the commands in .agents/commands with .claude/commands symlinked to it.
Add AGENTS.md, along with a CLAUDE.md that symlinks to the former, and a `fetch-spec` claude skill.
| - Source spec version tracked in `VERSION_OMICRON` | ||
| - Generator in `internal/generate/` | ||
| - Templates in `internal/generate/templates/` | ||
| - **Do not manually edit** `types.go`, `paths.go`, `responses.go`, or `version.go` |
There was a problem hiding this comment.
Late to the party, but I was actually wondering about it the other when I was prototyping splitting these files into groups if it would be better to add a prefix (like generated_*.go) to mark which files are auto-generated and should not be manually edited. It sounds like this could be helpful here as well (though I'm not sure how good AIs are at respecting glob patterns 😬 ).
There was a problem hiding this comment.
I know we discussed this a bit on our sync this week but I wanted to comment here as well. We should feel free to make changes that enable better AI processing. Things like renaming files to generated_*.go or updating the package layout are no longer considered nice to have design decisions but instead provide tangible benefits to ourselves and AI agents. The AI landscape is rapidly changing and our changes to AGENTS.md and others should similarly be subject to rapid modification when necessary. Not reckless modification, rapid modification.
Add AGENTS.md, along with a CLAUDE.md that symlinks to the former, and a
fetch-specclaude skill.