[DOCS] Add AGENTS.md, CLAUDE.md, and organizer skills; fix stale doc references - #16157
Open
mattstratton wants to merge 7 commits into
Open
mattstratton wants to merge 7 commits into
mattstratton wants to merge 7 commits into
Conversation
Give AI coding assistants a map of the repo and the rules that actually break a pull request, with the enforcing workflow named for each one. AGENTS.md is the single source of truth; CLAUDE.md is a pointer to it so there is nothing to keep in sync. AGENTS.md is the format Codex, Cursor, Copilot and Gemini read, which matters here because contributors arrive with all of them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Nine step-by-step guides for what local organizers actually do: new-event, add-sponsor, add-speaker, build-program, add-organizer, add-talk-media, cancel-event, change-sponsor-logo, and submit-changes (the shared commit/push/PR flow the other eight end with). Plain Markdown with YAML frontmatter, no tool-specific content. Claude Code discovers them automatically; other assistants are pointed at the paths from AGENTS.md. The skills write files directly from the templates in utilities/examples/ rather than calling utilities/add_*.sh, since most of those scripts only exit via CTRL+C and several have known bugs. change_sponsor_logo.sh is the exception and is still called directly. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Event data has lived at data/events/YYYY/city/main.yml since data-move.sh ran, but utilities/README.md and utilities/docs/cancel-event.md still described the flat data/events/yyyy-city.yml layout. Also: - Speaker and organizer images are resolved from assets/, not static/. Only sharing cards still live under static/. - Speaker headshots can be .png, .jpg or .webp, and add_speakers.sh assumes .png for the destination filename regardless of input. - The talk media list was missing googleslides, pdf, notist and slideslive, and did not say which fields take an ID versus a full URL. - slideslive frontmatter has superseded the hand-pasted embed script that the "Embedding Videos Other than Vimeo or YouTube" section still showed. - Blanking coordinates while a page still uses the event_map shortcode breaks the build; noted in the cancellation runbook, which is the one place that tells organizers to blank it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The PR Tests section described three required jobs including a Windows build and a gulp html-min step. The Windows job is commented out, there is no gulpfile, and two workflows went unmentioned: pr.yml (fails on an empty PR description, or one still containing the template's "Bluth" placeholder) and no-sponsors-changes.yml (fails on any change under static/img/sponsors/). Also: - config.toml and config-windows.toml do not exist; config lives in config/. - Added /assets/ to the acceptable-change directories. It is where event images belong now, and CODEOWNERS already grants content-reviewers over it. - Noted that Hugo must be the extended build. - Pointed README.md and CONTRIBUTING.md at AGENTS.md for anyone using an AI assistant. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
reference.md gave three different answers for where the event data file lives (YYYY-CITY.yml in the TOC, main.yml in the heading, CITY.main.yml in the prose). It is data/events/YYYY/CITY/main.yml. Field corrections, all verified against the layouts: - registration_open was undocumented, and it takes priority over registration_date_start/_end/registration_closed rather than complementing them. - gitlab was documented as a speaker field; no layout reads it there. It is rendered for team_members, which the doc omitted, along with twitch. - Added locale and comments_uuid. - social_shares also accepts bluesky, threads and mastodon. - enddate is required whenever startdate is set: several templates call time .enddate inside an if .startdate block with no guard. - coordinates was marked Required and DEPRECATED at once. Nothing consumes it, and a blank value breaks the build where event_map is still used. - Speaker image resolves from assets/ first, and may be .webp. - The valid Type list omitted blog, speaking, sponsor and events. Added a warning that workshop, ignite and keynote are program item types, not page types, and render a blank page when used as one. - Documented the 14 shortcodes that had no entry. All 31 are now covered. theme CONTRIBUTING.md: the Style Guide link pointed at the archived standalone theme repo, the Dev Setup section was empty, and the Releasing TOC entry had no section. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for devopsdays-web ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Error: Mixed case filenames foundThis can cause problems because git and Linux are case sensistive. Please rename the following to lowercase-with-dashes:
Please rename the files, commit and push again. |
.claude/settings.local.json holds one developer's local tool permissions and should never be shared, but it sat one `git add .claude/` away from being committed. The shared skills in .claude/skills/ stay tracked. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Error: Mixed case filenames foundThis can cause problems because git and Linux are case sensistive. Please rename the following to lowercase-with-dashes:
Please rename the files, commit and push again. |
The lint job used julie-ng/lowercase-linter@v1, whose exception list is hardcoded in the action and cannot be extended through its inputs. That list covers README.md, CONTRIBUTING.md and similar, but predates the agent instruction files AGENTS.md, CLAUDE.md and SKILL.md. Those have to use those exact names to be discovered by the tools that read them, so they cannot be renamed to satisfy the linter. Replaced the action with an equivalent inline check applying the same rule (a name containing both upper and lower case is an error) against an allowlist we control, seeded with the action's own exceptions plus the three agent files. Verified both directions: the check passes on the current tree and exits 1 with a rename suggestion for a staged Jane-Doe.md, including for a mixed-case directory component. Two side effects worth noting: - The lint job no longer needs GITHUB_TOKEN. - We lose the action's "suggested fixes" PR comment. The failure output names each offending path and its lowercase form instead. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Member
Author
|
Please note that the case-sensitive linter is always going to fail on this PR bc this PR actually fixes that :) |
issyl0
approved these changes
Sep 18, 2026
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds instructions for AI coding assistants, and corrects the places where our existing docs describe a repo layout we stopped using.
New files
AGENTS.md— the repo map, the rules that actually break a PR (and which workflow enforces each one), how to preview locally, and how to submit. Written for any assistant;AGENTS.mdis the format Codex, Cursor, Copilot and Gemini all read.CLAUDE.md— a pointer toAGENTS.mdso there is exactly one source of truth and nothing to keep in sync..claude/skills/— nine step-by-step guides for the things organizers actually do:new-event,add-sponsor,add-speaker,build-program,add-organizer,add-talk-media,cancel-event,change-sponsor-logo, andsubmit-changes(the shared commit/push/PR flow the other eight end with). They are plain Markdown with YAML frontmatter and contain nothing Claude-specific — Claude Code discovers them automatically, other tools are pointed at the paths fromAGENTS.md.Documentation corrections
Each of these was a case of the docs describing something that is no longer true:
data/events/YYYY/city/main.yml.utilities/README.mdandutilities/docs/cancel-event.mdstill described the flatdata/events/yyyy-city.ymllayout thatdata-move.shmigrated away from.reference.mdgave three different answers in one document.assets/, notstatic/. Only sharing cards still live instatic/.CONTRIBUTING.mddescribed three required CI jobs including a Windows build and a gulp html-min step. The Windows job is commented out, there is no gulpfile, and there are two other workflows (pr.yml,no-sponsors-changes.yml) it never mentioned. Also replaced the reference toconfig.toml/config-windows.toml, which do not exist, withconfig/.reference.md: addedregistration_open(undocumented, and it silently overrides theregistration_date_*fields); movedgitlaboff the speaker table, where no layout reads it, and onto the team members table, where one does, along withtwitch; addedlocaleandcomments_uuid; corrected the validTypelist and noted thatworkshop/ignite/keynoteas a page type render a blank page; documented the 14 shortcodes that had none; noted thatenddateis required wheneverstartdateis set; correctedcoordinatesfrom "Required: Yes" to deprecated.themes/devopsdays-theme/CONTRIBUTING.md: the Style Guide link pointed at the archived standalone theme repo; filled in the empty "Dev Setup" section and dropped the "Releasing" TOC entry that had no section..gitignore: added.claude/settings.local.json. It holds one developer's local tool permissions and was onegit add .claude/away from being committed. The shared skills in.claude/skills/stay tracked.Follow-up issues filed for the bugs found along the way, none of which are fixed here: #16150 #16151 #16152 #16153 #16154 #16155 #16156
What to check in the deploy preview
Nothing user-facing changes — every file in this PR is documentation or agent instructions, and none of it is under
content/. The deploy preview should be byte-identical to production.Verified with the pinned Hugo version (0.152.2, via
cibuilds/hugo:0.152.2) that the site still builds clean, and separately exercised theadd-sponsorskill end to end against a real event to confirm the instructions actually produce a working result.🤖 Generated with Claude Code