Add initial agents/claude tooling. #360

sudomateo · 2026-01-13T21:10:40Z

Nice overview!

lgfa29 · 2026-01-14T17:44:43Z

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 😬 ).

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.

-Original file line number
+Diff line change
@@ -0,0 +1,66 @@
+    # Fetch OpenAPI Specification
+    ## Description
+    Use this skill when you need to look up details about the Oxide API, including:
+    - Finding endpoint definitions, paths, or HTTP methods
+    - Looking up schema/type definitions from the API spec
+    - Understanding request/response formats for API operations
+    - Investigating API changes or additions
+    - Comparing generated code against the source OpenAPI spec
+    ## Instructions
+. Read the `VERSION_OMICRON` file to get the Omicron commit hash
+. Check if a cached spec exists for this version:
+       ```bash
+       test -f /tmp/oxide-openapi-spec-{commit}.json && echo "cached"
+       ```
+       If the file exists, skip to step 5 - the spec is already cached. Report that the cached spec is
+       being used.
+. Use curl to get the symlink target (the versioned filename):
+       ```bash
+       curl -sL "https://raw.githubusercontent.com/oxidecomputer/omicron/{commit}/openapi/nexus/nexus-latest.json"
+       ```
+       The response body contains the versioned filename (e.g., `nexus-2026010800.0.0-1844ae.json`)
+. Download the actual OpenAPI spec:
+       ```bash
+       curl -sL "https://raw.githubusercontent.com/oxidecomputer/omicron/{commit}/openapi/nexus/{versioned-filename}" -o /tmp/oxide-openapi-spec-{commit}.json
+       ```
+. Report what you found:
+       - The Omicron commit version
+       - Whether the spec was fetched fresh or loaded from cache
+       - Confirm the spec is available at `/tmp/oxide-openapi-spec-{commit}.json`
+. The spec is now available at `/tmp/oxide-openapi-spec-{commit}.json` for further analysis
+    ## Optional Arguments
+    If the user provides arguments like:
+    - `--endpoint <name>` or `endpoint <name>`: Search for and display details about a specific endpoint
+    - `--schema <name>` or `schema <name>` or `type <name>`: Search for and display a specific
+      schema/type definition
+    - `--search <term>`: Search endpoints and schemas for the given term
+    Use `jq` or read the temp file to fulfill these queries.
+    ## Output Format
+    - **Default to YAML** when displaying schemas or endpoint details (use `yq` or `jq ... | yq -P`)
+    - Only use JSON or table format if the user explicitly requests it (e.g., `--json` or `--table`)
+    ## Notes
+    - The spec is large (~2MB JSON), so summarize rather than output the entire thing
+    - If fetching fails, suggest checking if VERSION_OMICRON contains a valid commit hash
+    - Reference `internal/generate/main.go:getOpenAPISpecURL` for the canonical implementation

Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		../.agents/skills

-Original file line number
+Diff line change
@@ Expand Up / @@ -2,21 +2,28 @@ @@
     name: Release checklist
     about: Steps to take when releasing a new version (only for Oxide release team).
     labels: release
     ---
     ## Release checklist
-    <!--
+    <!--
      Please follow all of these steps in the order below.
      After completing each task put an `x` in the corresponding box,
      and paste the link to the relevant PR.
     -->
-    - [ ] Make sure the [VERSION](https://github.com/oxidecomputer/oxide.go/blob/main/VERSION) file has the new version you want to release.
-    - [ ] Make sure the changelog file in the `.changelog/` directory is set to the new version you want to release.
+    - [ ] Make sure the [VERSION](https://github.com/oxidecomputer/oxide.go/blob/main/VERSION) file has
+          the new version you want to release.
+    - [ ] Make sure the changelog file in the `.changelog/` directory is set to the new version you want
+          to release.
     - [ ] Make sure all examples and docs reference the new version.
-    - [ ] Make sure you've pulled the latest tag on main, and generate changelog by running `make changelog`. Add the date of the release to the title, and update associated Oxide API version.
+    - [ ] Make sure you've pulled the latest tag on main, and generate changelog by running
+          `make changelog`. Add the date of the release to the title, and update associated Oxide API
+          version.
     - [ ] Release the new version by running `make tag`.
     - [ ] Update GitHub release description with release notes generated from `make changelog`.
     - [ ] Create a release branch from the commit of the release tag.
-    - [ ] Bump the version in [VERSION](https://github.com/oxidecomputer/oxide.go/blob/main/VERSION) and run `make generate` to update the generated files.
-    - [ ] Create a new file for the next release in [.changelog/](https://github.com/oxidecomputer/oxide.go/blob/main/.changelog/).
+    - [ ] Bump the version in [VERSION](https://github.com/oxidecomputer/oxide.go/blob/main/VERSION) and
+          run `make generate` to update the generated files.
+    - [ ] Create a new file for the next release in
+          [.changelog/](https://github.com/oxidecomputer/oxide.go/blob/main/.changelog/).

-Original file line number
+Diff line change
@@ -0,0 +1,4 @@
+    {
+      "proseWrap": "always",
+      "printWidth": 100
+    }

-Original file line number
+Diff line change
@@ -0,0 +1,64 @@
+    # AGENTS.md
+    This file provides context for AI coding assistants working on this codebase.
+    ## Project Overview
+    **oxide.go** is the official Go SDK for administrating an Oxide rack. It's an OpenAPI-generated
+    client library providing programmatic access to the Oxide infrastructure management API.
+    ## Build and Test Commands
+    ```bash
+    make all          # Run fmt, lint, test, staticcheck, vet
+    make test         # Run tests
+    make lint         # Run golangci-lint
+    make generate     # Regenerate SDK from OpenAPI spec
+    ```
+    Note: prefer to run make targets like `make generate` over one-off `go generate` or `go run`
+    commands. The make targets include additional steps and context that are needed for correct
+    behavior.
+    Note: unless otherwise specified, we should update generated code and run unit tests before
+    considering a change complete.
+    ## Key Patterns
+    ### Code Generation
+    The SDK is generated from the Oxide API's OpenAPI specification:
+    - 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`
+    ### Finding the OpenAPI Specification
+    To fetch the upstream OpenAPI spec manually:
+. Read `VERSION_OMICRON` to get the Omicron commit hash (e.g., `06c0808`)
+. Fetch
+       `https://raw.githubusercontent.com/oxidecomputer/omicron/{commit}/openapi/nexus/nexus-latest.json`
+. This file is a symlink - the response body contains the versioned filename (e.g.,
+       `nexus-2025120300.0.0.json`)
+. Fetch the actual spec at
+       `https://raw.githubusercontent.com/oxidecomputer/omicron/{commit}/openapi/nexus/{versioned-filename}`
+    See `getOpenAPISpecURL` in `internal/generate/main.go` for the full implementation.
+    For local testing, set `OPENAPI_SPEC_PATH` environment variable to use a local spec file instead.
+    **Skill:** The `fetch-spec` skill automatically fetches the spec and saves it to
+    `/tmp/oxide-openapi-spec.json`. Claude will use this skill automatically when looking up API
+    details, or you can invoke it explicitly with `/fetch-spec endpoint disk` or
+    `/fetch-spec schema Instance`.
+    ## Code Style
+    - Mozilla Public License headers on all files
+    - Run `make fmt` before committing
+    - Run `make lint` to check for issues
+    - Unexported functions/constants by default
+    - Clear godoc comments on public APIs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add initial agents/claude tooling. #360

Uh oh!

Diff view

Diff view

There are no files selected for viewing

sudomateo Jan 13, 2026

Uh oh!

lgfa29 Jan 14, 2026

Uh oh!

sudomateo Jan 21, 2026

Uh oh!

Uh oh!

Add initial agents/claude tooling. #360

Uh oh!

Add initial agents/claude tooling. #360

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

sudomateo Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

lgfa29 Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

sudomateo Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!