Add shared agent guidance (AGENTS.md, CLAUDE.md, AI.md) by florent-leborgne · Pull Request #7655 · elastic/docs-content

florent-leborgne · 2026-07-30T11:00:56Z

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 in elastic/kibana, the leading Elastic repo for AI practice, which pairs an AGENTS.md with an AI.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 agent operational baseline (~935 words). Read directly by Cursor and Codex; other tools read it through the symlinks below. A lean router that points to the README and contribute-docs/ rather than restating them. Covers how the file is used (and that it defers to your local setup), core principles (verify at HEAD including across relevant minors, canonical-home-first, place content once, cumulative docs, don't assume existing content is correct), writing and style, a pre-PR checklist, tooling, and a short "what not to do" list.
README.md — expanded with the repo orientation moved out of AGENTS.md (what this repo is, what belongs here vs. code repos, the repository layout), plus a "start here" pointer to the contribution guide and building/previewing locally with docs-builder. Links back to AGENTS.md and AI.md.
Symlinks to 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 at HEAD (guarding against the model inventing labels), disclose AI use in pull requests and commits, use approved tools only, and keep changes reviewable (human technical review before merge, small atomic commits).
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.

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

Did you use a generative AI (GenAI) tool to assist in creating this contribution?

Yes
No

Tool(s) and model(s) used: Claude Code (Claude Opus 4.8)

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>

github-actions · 2026-07-30T11:01:42Z

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

Review docs changes (docs-review). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

- 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>

github-actions · 2026-07-30T13:11:13Z

🔍 Preview links for changed docs

github-actions · 2026-07-30T13:11:14Z

✅ 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

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>

@theletterf

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

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>

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>

theletterf

🚀

florent-leborgne · 2026-08-03T09:19:53Z

@theletterf before we merge this i'll check with the docs team that they all have renamed any files they had locally with either of these names

leemthompo · 2026-08-03T11:00:53Z

@@ -0,0 +1,37 @@
+# Contributing to docs with AI


We have an entire existing contributing to docs subsection, should we be crosslinking from there?

yeah good point, done. On your broader point about Give the contribution guidance one clear home, probably, but that's not for this PR. @theletterf do you know if we plan to make this human-facing AI guidance public?

Not opposed to this content being public, but we have the broader problem of where do we want docs contribution guidelines to live. They must be rendered somewhere, and MCP accessible, so that it can also serve as a foundation for agentic skills.

I understand we wanted to get this section out of the nav and into an island, but we're still a bit far from there. Do you have a preference in that sense?

no preference as long as we can single source as much as possible

leemthompo · 2026-08-03T11:25:11Z

A few ideas hit me reading this, in two broad buckets:

Give the contribution guidance one clear home

We already have a substantial contribute-docs/ section, while the new human-facing AI guidance lives in a root-level AI.md that is excluded from the published docset. Could the canonical AI contribution guidance live under contribute-docs/ and be linked from the existing contributor landing page? The root AI.md could then be a short pointer for agents and tools. This would also clarify the responsibilities: the contribution guide owns policy and deeper guidance, while AGENTS.md provides a concise operational baseline.

Develop this to be clearer about how agents should collaborate through the full PR lifecycle.

The writing and verification guidance is strong, but a few important Git and review practices seem underdeveloped. Here are some practices I try to use for sanity, and they become more important the bigger the PR and the more review comments they attract.

These are just suggestions, take anything you think might be helpful:

Make small, atomic commits, with each commit representing one coherent change.
Pull and review every new inline and standalone PR comment. Treat resolved threads as complete unless they are reopened.
Classify each unresolved comment as:
- Actionable: The requested change is clear and supported by the source of truth.
- Needs confirmation: The suggestion depends on unverified behavior, an SME answer, or a product or information architecture decision.
- Follow-up: The point is valid but belongs outside the current PR.
- No-op: Praise, observations, questions already answered, or suggestions that don’t require a change.
For each comment addressed by a change, reply with a short explanation of what changed and a link to the exact commit URL
Resolve a thread only when the feedback has been fully addressed. Leave it open when it still needs confirmation, an owner, an information architecture decision, or follow-up work. No-op comments generally don’t need a reply.

- AGENTS.md: rename "Before you open a PR" to "When you open a PR" and add a foreword note that these are conventions, not instructions to push or open PRs, and never override your own tool settings (e.g. approval before push). Addresses reviewer concern about the guidance implying agents should open PRs. - AI.md: link the overall contribution guide from the intro, matching the pointer AGENTS.md already has. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Extend the foreword note so it covers not just tool settings but the contributor's own local instructions: follow them when they conflict with this file, and flag the difference so we can reconcile it. Turns silent precedence into a visible reconciliation loop and keeps this file current. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

florent-leborgne · 2026-08-03T12:53:18Z

@leemthompo

Give the contribution guidance one clear home

Yes. Deferring this to the folks working on that guidance. Right now it's only internal so a light version of it is what we can do at this point.

how agents should collaborate through the full PR lifecycle

I don't know if we want iteration and review processes described there, I don't think we're ready to do that and would rather consider a review skill/workflow rather than broad agent guidance.

theletterf · 2026-08-03T13:06:00Z

@leemthompo About:

Develop this to be clearer about how agents should collaborate through the full PR lifecycle.

We should test this a bit before adding it. I say we merge the lightest version and then iterate.

leemthompo · 2026-08-03T13:46:32Z

Deferring this to the folks working on that guidance. Right now it's only internal so a light version of it is what we can do at this point.

what's the line between that guidance and this guidance?
FLB: They're the same thing I think, just one is internal so until it's not, we can at least have something smol here - so the line is public vs private.

Ownership: the docs leads own these files and keep them current.

OK so docs leads own the shared agent guidance, but not the general contribution guidance of which the former is a subset?
FLB: This line snuck into the description from i don't know where, maybe the fact that this PR has a codeowner review request :D I removed it

natasha-moore-elastic · 2026-08-03T16:19:18Z

+- **Style compliance**: apply the [Vale](contribute-docs/vale-linter.md) recommendations where relevant.
+- **Accuracy against the product code**: labels, defaults, and behavior verified at `HEAD`.
+
+Preview locally with `docs-builder serve`, or run `docs-builder` with no argument for a full build that surfaces errors ([build locally](contribute-docs/locally.md)). Run Vale on changed files. When you move, rename, or delete a page that has already been published, add the redirect in `redirects.yml`. For AI-assisted contributions specifically, read [`AI.md`](AI.md).


I'm wondering how this will work in practice: are we saying that agents should automatically run docs-builder serve or docs-builder whenever they draft content? What if a contributor already has a local build running?

by doing this in their sandbox they can detect new warnings/errors before considering the change ready for review, so it is an automatic way to ensure it's not going to create a PR that fails CI.
If there's already a local build running, it'll find that the port is occupied and either restart it, or do it on another port

In practice this is likely the type of things you'd see in your agent chat

@natasha-moore-elastic

Same issue @natasha-moore-elastic flagged for accept-docs-quest: crosslink-validator isn't in elastic/elastic-docs-skills, so drop it from the Tooling table and the links bullet. Verified the remaining nine table skills all exist in the public repo. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

@leemthompo

Addresses review feedback (@leemthompo): - Move "what this repo is", "what belongs here", and the repo layout from AGENTS.md to README.md (human-facing, more discoverable, excluded from the docset). AGENTS.md keeps a concise "About this repo" pointer, so it reads as the agent operational baseline. README links back to AGENTS.md and AI.md for AI-assisted contributions. - Replace the vague "keep PRs small enough to review" line in AI.md with concrete commit hygiene: small, atomic commits, one coherent change each. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Add a "start here" line to the Contribute section linking the contribution guide and the local build/preview setup with docs-builder, so new contributors know where to begin. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

florent-leborgne requested a review from a team as a code owner July 30, 2026 11:00

florent-leborgne marked this pull request as draft July 30, 2026 11:34

florent-leborgne and others added 2 commits July 30, 2026 14:20

github-actions Bot deployed to docs-preview July 30, 2026 13:13 View deployment

theletterf reviewed Jul 30, 2026

View reviewed changes

Comment thread AI.md

Comment thread CLAUDE.md

github-actions Bot deployed to docs-preview July 30, 2026 13:29 View deployment

github-actions Bot deployed to docs-preview July 30, 2026 13:42 View deployment

github-actions Bot deployed to docs-preview July 30, 2026 13:53 View deployment

florent-leborgne and others added 2 commits July 30, 2026 16:02

github-actions Bot deployed to docs-preview July 30, 2026 14:11 View deployment

github-actions Bot deployed to docs-preview July 30, 2026 14:28 View deployment

florent-leborgne commented Jul 30, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Apply suggestion from @florent-leborgne

b582b2c

github-actions Bot deployed to docs-preview July 30, 2026 14:48 View deployment

github-actions Bot deployed to docs-preview July 30, 2026 15:00 View deployment

shainaraskas reviewed Jul 30, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Comment thread AGENTS.md Outdated

shainaraskas reviewed Jul 30, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

shainaraskas reviewed Jul 30, 2026

View reviewed changes

Comment thread AI.md Outdated

shainaraskas reviewed Jul 30, 2026

View reviewed changes

Comment thread AI.md

Update AGENTS.md

87da3d0

Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>

github-actions Bot deployed to docs-preview July 30, 2026 18:05 View deployment

florent-leborgne and others added 2 commits July 30, 2026 20:08

Narrow screenshot guidance to provided images only

12356ac

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>

github-actions Bot deployed to docs-preview July 30, 2026 18:15 View deployment

theletterf approved these changes Aug 3, 2026

View reviewed changes

theletterf enabled auto-merge (squash) August 3, 2026 09:10

Merge branch 'main' into add-shared-agent-guidance

7a8f8f5

florent-leborgne disabled auto-merge August 3, 2026 09:18

github-actions Bot deployed to docs-preview August 3, 2026 09:18 View deployment

leemthompo reviewed Aug 3, 2026

View reviewed changes

florent-leborgne and others added 2 commits August 3, 2026 14:31

github-actions Bot deployed to docs-preview August 3, 2026 12:41 View deployment

leemthompo reviewed Aug 3, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

leemthompo reviewed Aug 3, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

natasha-moore-elastic reviewed Aug 3, 2026

View reviewed changes

Apply suggestion from @florent-leborgne

ec0a8ab

github-actions Bot deployed to docs-preview August 3, 2026 17:03 View deployment

github-actions Bot deployed to docs-preview August 3, 2026 17:18 View deployment

github-actions Bot deployed to docs-preview August 3, 2026 17:37 View deployment

github-actions Bot deployed to docs-preview August 3, 2026 17:54 View deployment

Uh oh!

Conversation

florent-leborgne commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Generative AI disclosure

Uh oh!

github-actions Bot commented Jul 30, 2026

Elastic Docs AI PR menu

Uh oh!

github-actions Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions Bot commented Jul 30, 2026

✅ Elastic Docs Style Checker (Vale)

Uh oh!

theletterf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

theletterf left a comment

Choose a reason for hiding this comment

Uh oh!

florent-leborgne commented Aug 3, 2026

Uh oh!

leemthompo Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

florent-leborgne Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

theletterf Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

florent-leborgne Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

leemthompo commented Aug 3, 2026

Uh oh!

florent-leborgne commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

theletterf commented Aug 3, 2026

Uh oh!

Uh oh!

Uh oh!

leemthompo commented Aug 3, 2026 • edited by florent-leborgne Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

natasha-moore-elastic Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

florent-leborgne Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

florent-leborgne Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

florent-leborgne commented Jul 30, 2026 •

edited

Loading

github-actions Bot commented Jul 30, 2026 •

edited

Loading

florent-leborgne commented Aug 3, 2026 •

edited

Loading

leemthompo commented Aug 3, 2026 •

edited by florent-leborgne

Loading

florent-leborgne Aug 3, 2026 •

edited

Loading