[georgewallace]

Proof of concept for testing only. Please don't review or merge.

Adds an {agent-prompt} directive. A docs page can offer a prompt that readers paste into an AI coding agent, which then does the page's steps and reports what it did. The prompt stays out of the page: readers see a compact card with a Review prompt button and a Copy prompt button.

Affects: Authoring, Site UI

Prompt summary: Build a directive that gives readers a copyable prompt for their AI coding agent without cluttering the page. Say clearly that it needs an agent that can run commands, make the compact inline card the version readers see, track how readers use it, and add a sample page like the other directives.

Why

A page can show readers how to do a task, but it cannot give their AI coding agent a reviewed set of instructions. Readers write their own, and the results vary. Showing the instructions on the page would clutter it.

What

The card and the dialog

The card shows a label, a title, a one-line description, Review prompt with the character count, and Copy prompt. Review prompt opens a dialog with the full text and a second copy button. The default description tells readers to use an AI coding agent that can run commands. The prompt lives in a fenced code block inside the directive and is copied exactly as written. A directive without that block fails the build.

Exports

The prompt is left out of the LLM (.md) and plain text renderings of the page.

Telemetry

The script sends agent_prompt_viewed, agent_prompt_review_opened, agent_prompt_copied and agent_prompt_copy_failed through the existing logger. Events carry the title, the prompt length, the block's position and whether the control was the card or the dialog. The prompt text is never sent.

The sample page

docs/syntax/agent-prompt.md shows the live output and the Markdown source in tabs, like the other directive pages. It lists the properties and gives guidance for writing a prompt that works.

Out of scope: Earlier mock-ups also had a sidebar card and page-actions links. They are not in this PR; only the inline card ships. The Markdown export also drops the method and path line of Console code blocks. This PR does not change that.

Verify

dotnet test --project tests/Elastic.Markdown.Tests/
cd src/Elastic.Documentation.Site && npm test
dotnet run --project src/tooling/docs-builder -- serve -p docs
# open http://localhost:3000/syntax/agent-prompt

Check on the preview

• Agent prompt syntax page — the compact card, the Review prompt dialog, and the line about coding agents that can run commands.
• Agent skill syntax page — control page: unchanged.

🤖 Generated with Claude Code

[github-actions]

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4659/

Sample changed pages:

• docs/syntax/agent-prompt.md