Add shared agent guidance (AGENTS.md, CLAUDE.md, AI.md) - #7655
Open
florent-leborgne wants to merge 15 commits into
Open
Add shared agent guidance (AGENTS.md, CLAUDE.md, AI.md)#7655florent-leborgne wants to merge 15 commits into
florent-leborgne wants to merge 15 commits into
Conversation
Commit a team baseline for AI agents working in docs-content, replacing the previous personal-and-gitignored-only setup. - AGENTS.md: canonical guidance, read by Cursor/Codex/Copilot. Routes to the contribute-docs guide rather than restating it. Covers repo purpose and scope, core principles, repo layout, style, build/validate, and what not to do. - CLAUDE.md: symlink to AGENTS.md so Claude Code reads the same file. - AI.md: norms for contributing to docs with AI (own what you submit, verify facts against source, keep it reviewable). - .gitignore: un-ignore the committed AGENTS.md and CLAUDE.md; keep per-contributor AGENTS.local.md / CLAUDE.local.md / GEMINI.md ignored. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
florent-leborgne
marked this pull request as draft
July 30, 2026 11:34
- Tighten the foreword and remove em dashes / semicolons from the file's own prose (without adding an avoid-em-dash rule, which would contradict the Elastic style guide that permits them). - Correct publish speed: minutes plus a cache refresh, not hours. - Clarify the URL-to-path mapping is a rule of thumb for finding files, not for writing links; point to the docs-builder link syntax. - Expand repo scope: narrative docs for Stack v9, Serverless, ECE v4, ECK v3+, Elastic Cloud Hosted, and Elastic tools. Sharpen "what's not here": API refs in kibana/elasticsearch-specification; legacy content (v8 and earlier) in code repos on older AsciiDoc branches. - Core principles: verify at HEAD and confirm statements hold for earlier v9 minors; place content once in its most correct home; keep multi-page content consistent; don't assume existing content is already correct. - Reframe validation as a pre-PR checklist (no claim that sweeps are automated): content type, applies_to/cumulative, style/Vale, accuracy. - Add an optional Tooling section pointing to the elastic-docs-skills repo and the elastic-docs MCP. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- docset.yml: exclude AGENTS.md, AI.md, CLAUDE.md from the docs build.
docs-builder rejects uppercase filenames, which failed `build / build`.
- Fix Vale Elastic.DirectionalLanguage warning ("listed above").
- Broaden "what's not here": all reference docs that live next to the
code they describe (API references are one example), not just APIs.
- Drop the "a new page is the last resort" framing.
- Reference skills granularly: skill as the fast path, contribute-docs
guides as the deeper reference for doubt. Thread docs-applies-to-tagging
and docs-content-type-checker into the principles, add a skill catalog
table, and name skills in the pre-PR checklist.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
🔍 Preview links for changed docs |
Contributor
✅ Elastic Docs Style Checker (Vale)No issues found on modified lines! The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale. |
Release notes and changelog pages render via the {changelog} directive
from source entries. Flag them as generated in the repo layout table and
add a "what not to do" rule to correct the source, not the rendered page.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
theletterf
reviewed
Jul 30, 2026
theletterf
left a comment
theletterf
left a comment
Member
There was a problem hiding this comment.
Good first version, thanks for opening this! Let's review together in a call before releasing.
Not all release notes share one generation path, so drop the specific
{changelog}-directive claim. Keep it generic: release notes are produced
from code changes and are not part of regular docs edits.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
State the skill-first, contribution-guide-as-fallback policy once at the top instead of repeating the pairing in every principle, the PR checklist, and a third column of the skills table. This cuts tokens the file spends on every agent load and gives agents one clear escalation rule. - Skills table drops the per-row "deeper reference" column (Task | Skill). - Principles and PR checklist reference concepts and link the deep guide where judgment is heavy, without re-naming the skill each time. - Add the concrete local commands: `docs-builder serve`, and `docs-builder` with no argument for a full error-surfacing build. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Reduce "What not to do" to only the items the core principles don't already state (release notes, screenshots, restructuring). Removes the four don'ts that echoed principles, and the triple-statement of "verify labels at HEAD". - Trim the "place content once" bullet from five sentences to three. - Trim the legacy-version bullet tail. - Drop the "Finding a page from its URL" section. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add a links bullet to Writing and style: the docs-builder link syntax (including the cross-repo <repo>:// form) and the crosslink-validator skill. Recovers the reference dropped with the URL-mapping section. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Address review feedback (@theletterf): add the disclosure requirement and tighten alignment with the org guidelines, in public-safe language (no internal URLs, since this repo is public). - Add a "Disclose your use of AI" section: disclose in the PR (the template's Generative AI disclosure section) and in commits, even when verified. - State that AI-assisted changes need human technical review before merge. - Require approved tools only and no sensitive info in unapproved tools. - Add "keep PRs small enough to review" to the reviewable checklist. Held for the docs team's review call before merge. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Extend single-sourcing to the other tools that read their own named file: - GEMINI.md -> AGENTS.md (Gemini CLI), excluded in docset.yml like the other uppercase root files so docs-builder doesn't reject the filename. - .github/copilot-instructions.md -> ../AGENTS.md (GitHub Copilot); the .github tree isn't scanned by docs-builder, so no exclude needed. Cursor and Codex read AGENTS.md directly and need no symlink. Personal overrides stay ignored (AGENTS.local.md, CLAUDE.local.md, GEMINI.local.md). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
shainaraskas
left a comment
shainaraskas
left a comment
Member
There was a problem hiding this comment.
comments on agents.md. gonna review the other one too but keep getting pulled away so wanted to submit this
Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Co-authored-by: Florent LB <florent.leborgne@elastic.co>
florent-leborgne
marked this pull request as ready for review
July 30, 2026 17:42
Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>
The old wording made agents refuse to add screenshots outright. Reframe: don't fabricate or auto-generate them, but suggest which ones to add or update (and which matter most), and add one when a suitable image is provided or available. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Drop "or available" / "or already available" so an agent adds a screenshot when one is provided, without going looking for one. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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
3 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 a shared, committed baseline for AI agents working in
docs-content. Today the repo gitignores all agent files (AGENTS.md,CLAUDE.md,.cursor, and so on), so every contributor keeps their own local copy and nothing is shared. This PR commits a team baseline instead. It follows the established pattern inelastic/kibana, the leading Elastic repo for AI practice, which pairs anAGENTS.mdwith anAI.md.👀 ----do reviewers read pr descriptions?----- 👀
The guidance is for now intentionally generic and links to the various places where we have AI helpers defined, whether it's skills hosted in a different repo, tools, or detailed contribution guidelines.
It does not gives hard/strict rules for most things, instead think of it more as a pointer to the right resources/considerations for content contribs.
👀 -----if they do, they can stop here the rest is noise---- 👀
What's in it:
AGENTS.md— the canonical guidance. Read directly by Cursor and Codex; other tools read it through the symlinks below. A lean router (~1,300 words): it points to thecontribute-docs/guide rather than restating it, and adds only repo mechanics that aren't already published. Covers what this repo is, what belongs here vs. what lives in code repos, core principles (verify atHEADincluding across v9 minors, canonical-home-first, place content once, cumulative docs, don't assume existing content is correct), repo layout, style, a pre-PR checklist, tooling, and a short "what not to do" list.AGENTS.md— so every tool reads the same file with no duplication:CLAUDE.md(Claude Code)GEMINI.md(Gemini CLI).github/copilot-instructions.md(GitHub Copilot)AI.md— norms for contributing to docs with AI, aligned with Elastic's Docs & AI guidelines: own what you submit, verify facts against product source atHEAD(guarding against the model inventing labels), disclose AI use in pull requests and commits, use approved tools only, and keep changes reviewable with human technical review before merge.docset.yml— excludes the uppercase agent files (AGENTS.md,AI.md,CLAUDE.md,GEMINI.md) from the docs build, which requires lowercase filenames..gitignore— un-ignores the committed agent files and their symlinks; keeps per-contributor overrides (AGENTS.local.md,CLAUDE.local.md,GEMINI.local.md,.cursor) ignored, so personal guidance still loads on top locally.Ownership: the docs leads own these files and keep them current.
Follow-ups (not in this PR): hooks as guardrails (for example, enforce "don't hand-edit generated release notes", or run Vale on edited files) and a lightweight feedback loop for reporting when the guidance is wrong or missing.
Generative AI disclosure
Tool(s) and model(s) used: Claude Code (Claude Opus 4.8)