Add AGENTS.md, skills page, and refcache skill (#9706)

Author: chalin

.claude/skills/resolve-refcache-conflicts/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: resolve-refcache-conflicts
+description:
+  Skill for resolving static/refcache.json merge or rebase conflicts in the
+  current branch or a specified PR.
+argument-hint: '[optional-pr-number]'
+---
+
+`static/refcache.json` is an auto-generated file. Resolving conflicts requires
+first taking the integration branch's side, finishing the merge/rebase, then
+running `npm run fix:refcache` to restore any URLs unique to the active branch.
+
+## Prerequisites
+
+If the current branch has a merge or rebase in progress, then skip the rest of
+this section and jump to **Preparation**.
+
+The current branch must be clean (`git status --short`). If not clean, offer to
+run `git stash` or `git commit` to clean it up, or stop.
+
+If `$ARGUMENTS` is a PR number, then check out the PR branch with:
+`gh pr checkout $ARGUMENTS`.
+
+## Preparation
+
+At this point, we are ready to resolve the conflicts in the active branch:
+
+1. Determine the integration reference (`$BASE_BRANCH`) and fetch it:
+   - If an `upstream` remote exists: `git fetch upstream`, use `upstream/main`.
+   - Otherwise: `git fetch origin`, use `origin/main`.
+
+2. If merge or rebase is in progress (`git status`), skip this step. Otherwise,
+   ask the user whether to run `git merge $BASE_BRANCH` or
+   `git rebase $BASE_BRANCH`, then run it.
+
+3. If there are no conflicts: stop, we are done.
+
+4. Conflicts other than `static/refcache.json`: resolve them with the user.
+
+5. If no `static/refcache.json` conflict remains: stop, we are done. Otherwise,
+   proceed to **Resolve**.
+
+## Resolve
+
+1. Check out the `$BASE_BRANCH` version of `static/refcache.json`. Assumes the
+   active branch is being rebased/merged from `$BASE_BRANCH`, not the other way
+   around:
+
+   | Operation                                   | Command                                      |
+   | ------------------------------------------- | -------------------------------------------- |
+   | Rebase of active branch onto `$BASE_BRANCH` | `git checkout --ours static/refcache.json`   |
+   | Merge of `$BASE_BRANCH` into active branch  | `git checkout --theirs static/refcache.json` |
+
+2. Stage the resolved files, then continue:
+   - Rebase: `git add static/refcache.json && git rebase --continue`
+   - Merge: `git add static/refcache.json && git commit --no-edit`
+   - If other files were resolved in Preparation step 4, `git add` those too
+     before continuing.
+
+3. Rebase only: for each subsequent rebase stop that conflicts on
+   `static/refcache.json`, repeat Resolve steps 1–2. If other paths are also
+   conflicted on that stop, run Preparation step 4 first.
+
+4. Run `npm run fix:refcache` once, after the entire rebase/merge completes.
+   Note: this runs a full Hugo build and link check — requires network,
+   installed npm dependencies, and populated submodules; can take several
+   minutes.
+
+5. Commit the changes, if any:
+
+   ```sh
+   git add static/refcache.json
+   git diff --cached --quiet static/refcache.json || \
+      git commit -m "Refresh refcache after resolving conflicts"
+   ```
+
+6. Push:
+   - Merge: `git push`
+   - Rebase: `git push --force-with-lease`

.gitignore

@@ -1,3 +1,7 @@
+# cSpell:ignore worktrees
+
+/.claude/worktrees
+
 # Hugo-generated assets
 .hugo_build.lock
 /public

AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS.md — OpenTelemetry.io guide for AI agents
+
+Maintainer-focused documentation for **building, testing, and deploying this
+website** is the [**Site** section][content/en/site/].
+
+Treat that tree as the primary reference for site tooling, CI, and conventions.
+Start at [content/en/site/][]. Useful subsections:
+
+- [Build][] — npm scripts, workflows, patches, localization
+- [Testing][]
+- [Design][]
+- [Skills][]
+
+The **Docsy** theme is a git submodule. For theme-specific agent notes, see
+[themes/docsy/AGENTS.md](themes/docsy/AGENTS.md).
+
+Repo-wide contribution context: [CONTRIBUTING.md](CONTRIBUTING.md),
+[README.md](README.md).
+
+[content/en/site/]: content/en/site/_index.md
+[Build]: content/en/site/build/_index.md
+[Testing]: content/en/site/testing/_index.md
+[Design]: content/en/site/design/_index.md
+[Skills]: content/en/site/skills.md

content/en/site/_index.md

@@ -25,6 +25,8 @@ Tentatively planned content organization:
   purpose, ownership, and overall status.
 - **Needs, requirements, and features** — Stakeholder needs, requirements, and
   other relevant information broken down into features.
+- [**Skills**](./skills/) — Skills for agents and humans to use when maintaining
+  the site.
 - **Design** — Architectural design, Information Architecture (IA), layout, UX
   choices, theme related decisions, and other design-level artifacts.
 - **Implementation** — Code-level structure and conventions, Hugo/Docsy

content/en/site/skills.md

@@ -0,0 +1,18 @@
+---
+title: Skills for agents and maintainers
+linkTitle: Skills
+description: Skills for agents and maintainers to use when maintaining the site.
+weight: 22
+---
+
+Source: [`.claude/skills/`][] - links use the **upstream** repository and
+**`main`**; the same paths apply in any clone (including forks on another
+default branch).
+
+- [`/resolve-refcache-conflicts <optional-pr-number>`][resolve-refcache-conflicts]:
+  resolve `static/refcache.json` merge/rebase conflicts.
+
+[`.claude/skills/`]:
+  https://github.com/open-telemetry/opentelemetry.io/tree/main/.claude/skills
+[resolve-refcache-conflicts]:
+  https://github.com/open-telemetry/opentelemetry.io/blob/main/.claude/skills/resolve-refcache-conflicts/SKILL.md

static/refcache.json

@@ -15299,6 +15299,10 @@
     "StatusCode": 206,
     "LastSeen": "2026-04-10T10:01:49.139856918Z"
   },
+  "https://github.com/open-telemetry/opentelemetry.io/blob/main/.claude/skills/resolve-refcache-conflicts/SKILL.md": {
+    "StatusCode": 206,
+    "LastSeen": "2026-04-20T20:54:18.265886-04:00"
+  },
   "https://github.com/open-telemetry/opentelemetry.io/blob/main/.cspell.yml": {
     "StatusCode": 206,
     "LastSeen": "2026-04-10T09:58:01.148862206Z"
@@ -15507,6 +15511,10 @@
     "StatusCode": 206,
     "LastSeen": "2026-03-24T09:53:38.909114584Z"
   },
+  "https://github.com/open-telemetry/opentelemetry.io/tree/main/.claude/skills": {
+    "StatusCode": 206,
+    "LastSeen": "2026-04-20T20:54:16.690618-04:00"
+  },
   "https://github.com/open-telemetry/opentelemetry.io/tree/main/.github": {
     "StatusCode": 206,
     "LastSeen": "2026-04-10T10:03:33.402863208Z"