From 455572ddef9c6aba78b21b3839c64b83ae97df8c Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 4 Jun 2026 09:46:35 -0600 Subject: [PATCH 1/4] docs: add AEO cross-link audit skill Co-Authored-By: Oz --- .agents/skills/aeo_crosslink_audit/SKILL.md | 139 ++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 .agents/skills/aeo_crosslink_audit/SKILL.md diff --git a/.agents/skills/aeo_crosslink_audit/SKILL.md b/.agents/skills/aeo_crosslink_audit/SKILL.md new file mode 100644 index 00000000..bea9143b --- /dev/null +++ b/.agents/skills/aeo_crosslink_audit/SKILL.md @@ -0,0 +1,139 @@ +--- +name: aeo_crosslink_audit +description: Run a narrow AEO cross-link audit for Warp docs using Peec, Google Search Console, and existing docs. Use for recurring or scheduled agents that should identify high-confidence internal cross-linking improvements for agents, cloud agents, and orchestration docs. +--- + +# AEO cross-link audit + +Identify small, high-confidence internal cross-linking improvements for the Warp docs. This skill is designed for a recurring Oz scheduled agent that audits one narrow topic area, opens a small PR when there are safe changes, or writes a no-change report when there are not enough high-confidence opportunities. + +## Scope + +Use this skill only for the pilot topic area: +- Agents +- Cloud agents +- Orchestration + +The audit should focus on one improvement type: +- Internal cross-links between existing docs pages + +Do not: +- Create new pages. +- Rewrite large sections. +- Make broad SEO or AEO recommendations. +- Add keyword-stuffed text. +- Force Peec or Google Search Console signals into docs when they do not support a useful reader journey. + +## Source data + +Use the smallest reliable set of source data needed to justify link changes: +- **Peec MCP** - Review recent prompts, recommendations, source URLs, and query vocabulary related to agents, cloud agents, and orchestration. +- **Google Search Console** - When available, use the environment's `GSC_SERVICE_ACCOUNT_CREDENTIALS_JSON` secret to inspect recent queries and pages related to agents, cloud agents, and orchestration. +- **Docs repo** - Search existing pages under `src/content/docs/` for relevant source pages, link targets, and related terminology. + +If Peec or Google Search Console data is unavailable, say what could not be verified and proceed only with repo-grounded recommendations. Do not invent source signals. + +## Workflow + +1. **Gather source signals.** Use Peec MCP and Google Search Console data, when available, to identify relevant user language, prompts, recommendations, or pages. +2. **Search existing docs.** Look for pages under `src/content/docs/` that already mention or imply related concepts in agents, cloud agents, or orchestration. +3. **Identify link opportunities.** Find up to 5 internal cross-link opportunities where: + - The source page already mentions or implies the related concept. + - The target page exists. + - The link helps a reader continue a real workflow. + - The edit can be made with a small, natural copy change. +4. **Make only safe edits.** Add links with minimal surrounding copy changes. Preserve the existing page structure and voice. +5. **Run self-review.** Apply the quality gates in this skill before opening a PR or writing a no-change report. +6. **Open a PR or report no changes.** Open a PR only when there are at least 2 high-confidence link additions. Otherwise, write a no-change report in the Oz run output. + +## Self-review before opening a PR + +Before opening a PR, verify every proposed change: +- **Real signal** - Each link is backed by a Peec, Google Search Console, or existing-docs signal, not generic SEO advice. +- **Reader value** - Each link helps a developer understand or complete a real workflow. +- **Natural language** - The added link text reads naturally in context and is not keyword-stuffed. +- **Existing target** - Every internal link points to an existing file under `src/content/docs/`. +- **Navigation awareness** - Check `src/sidebar.ts` when a linked page is expected to appear in navigation. +- **Small scope** - The diff is limited to cross-linking and small copy changes needed to make links natural. +- **No broad rewrites** - Remove any edit that becomes a rewrite, strategy recommendation, or new content proposal. +- **No duplication** - Do not add links that create repetitive related-links lists or duplicate nearby links. + +Run: + +```bash +git diff --check +``` + +## PR requirements + +Open a PR only when there are at least 2 high-confidence link additions. + +Use this title format: + +```text +docs: add AEO cross-links for agents and orchestration +``` + +The PR body must include an AEO brief. Use `.agents/skills/aeo_brief/SKILL.md` as the format and include: +- **Goal** - Identify small internal cross-link improvements for agents, cloud agents, and orchestration docs. +- **Source signals** - Peec prompts/recommendations, Google Search Console queries/pages, or existing-docs signals that justified the links. +- **Pages touched** - Files edited and why. +- **Links added** - Source page, target page, and rationale for each link. +- **Open questions for human review** - Anything that affects product accuracy, terminology, or placement. + +Request review from docs and growth-docs reviewers where possible, including: +- Rachael +- Petra +- Hong Yi +- Danny +- Other active reviewers in `#growth-docs` + +## No-change report + +If there are fewer than 2 high-confidence link opportunities, do not open a PR. Write a no-change report in the Oz run output so reviewers can inspect it from the Oz web app Runs page and shared session history. + +Use this format: + +```text +## AEO cross-link audit no-change report + +**Topic area:** Agents, cloud agents, and orchestration. + +**Source signals reviewed:** +- [Peec prompt, recommendation, source URL, or query vocabulary.] +- [Google Search Console query, page, or trend.] +- [Existing-docs signal.] + +**Docs pages inspected:** +- `[path]` - [Why it was inspected.] + +**Candidate links rejected:** +- `[source path]` → `[target path]` - [Why this was not high-confidence.] + +**Why no PR was opened:** +- [Reason.] + +**Suggested prompt or skill improvement:** +- [One specific improvement for the next run.] +``` + +For the pilot, no-change reports stay in the Oz run output. If team input is needed, share the Oz run link manually in `#growth-docs`. + +## Human review expectations + +The human reviewer should be able to understand the PR or no-change report without replaying the full run. Optimize the output for quick review: +- Keep PRs small and focused. +- Explain the source signal behind each link. +- Flag any uncertainty directly. +- Avoid hiding product or terminology questions in the diff. + +## Future expansion boundaries + +Do not implement future expansion ideas in this pilot skill. If the audit finds opportunities outside internal cross-linking, mention them only as follow-up recommendations in the PR body or no-change report. + +Possible future phases include: +- Existing-doc improvements such as terminology additions, clearer headings, or better descriptions. +- New-guide recommendations using AEO briefs before drafting. +- Cross-linking across docs and marketing pages. +- Broader Peec content-gap integration with Buzz's `peec-content-gap` workflow. +- Lightweight trend reporting across scheduled runs. From c8b6e9c9ab090cadd153f2508a8414fab796228c Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 4 Jun 2026 10:18:43 -0600 Subject: [PATCH 2/4] docs: add link quality rules to AEO audit skill Co-Authored-By: Oz --- .agents/skills/aeo_crosslink_audit/SKILL.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/.agents/skills/aeo_crosslink_audit/SKILL.md b/.agents/skills/aeo_crosslink_audit/SKILL.md index bea9143b..78b8ec96 100644 --- a/.agents/skills/aeo_crosslink_audit/SKILL.md +++ b/.agents/skills/aeo_crosslink_audit/SKILL.md @@ -42,16 +42,30 @@ If Peec or Google Search Console data is unavailable, say what could not be veri - The target page exists. - The link helps a reader continue a real workflow. - The edit can be made with a small, natural copy change. -4. **Make only safe edits.** Add links with minimal surrounding copy changes. Preserve the existing page structure and voice. +4. **Make only safe edits.** Add links with minimal surrounding copy changes. Preserve the existing page structure and voice. Follow the link quality rules below when choosing anchor text and surrounding context. 5. **Run self-review.** Apply the quality gates in this skill before opening a PR or writing a no-change report. 6. **Open a PR or report no changes.** Open a PR only when there are at least 2 high-confidence link additions. Otherwise, write a no-change report in the Oz run output. +## Link quality rules + +When adding links, follow the link style guidance in `AGENTS.md` and validate with `style_lint`. + +- **Use descriptive anchors** - Link meaningful destination text, not generic phrases like "here," "this page," "learn more," "read more," or raw URLs. +- **Add context before the link when needed** - If the destination page is not obvious from the sentence, introduce why the reader should follow it. Do not drop a link into a sentence without explaining its relevance. +- **Use natural destination-page phrasing** - Prefer wording like "the Runs page in the Oz web app," "the Scheduled Agents guide," or "the Slack integration guide" when naming a destination. +- **Avoid redundant prefixes** - Do not add a bold term or label immediately before a link if the link text already provides the context. +- **Keep links reader-first** - The link should help a developer continue the task or understand the concept, not exist only for SEO/AEO coverage. +- **Avoid link stuffing** - Do not add multiple links to the same nearby destination or turn a paragraph into a dense cluster of links. +- **Resolve redirects** - Link directly to the final destination page when known. Do not add redirecting URLs or old paths. + ## Self-review before opening a PR Before opening a PR, verify every proposed change: - **Real signal** - Each link is backed by a Peec, Google Search Console, or existing-docs signal, not generic SEO advice. - **Reader value** - Each link helps a developer understand or complete a real workflow. - **Natural language** - The added link text reads naturally in context and is not keyword-stuffed. +- **Anchor quality** - Link text is descriptive and specific; no raw URL anchors or generic anchors like "here," "this page," "learn more," or "read more." +- **Link context** - The surrounding sentence explains why the destination is relevant when the link target is not obvious. - **Existing target** - Every internal link points to an existing file under `src/content/docs/`. - **Navigation awareness** - Check `src/sidebar.ts` when a linked page is expected to appear in navigation. - **Small scope** - The diff is limited to cross-linking and small copy changes needed to make links natural. @@ -61,6 +75,7 @@ Before opening a PR, verify every proposed change: Run: ```bash +python3 .agents/skills/style_lint/style_lint.py --changed git diff --check ``` From 9348a80935aeeaf3fce4ba1c51064ba02c6498e8 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 4 Jun 2026 10:23:48 -0600 Subject: [PATCH 3/4] docs: harden AEO audit validation guidance Co-Authored-By: Oz --- .agents/skills/aeo_crosslink_audit/SKILL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.agents/skills/aeo_crosslink_audit/SKILL.md b/.agents/skills/aeo_crosslink_audit/SKILL.md index 78b8ec96..4758b873 100644 --- a/.agents/skills/aeo_crosslink_audit/SKILL.md +++ b/.agents/skills/aeo_crosslink_audit/SKILL.md @@ -28,7 +28,7 @@ Do not: Use the smallest reliable set of source data needed to justify link changes: - **Peec MCP** - Review recent prompts, recommendations, source URLs, and query vocabulary related to agents, cloud agents, and orchestration. -- **Google Search Console** - When available, use the environment's `GSC_SERVICE_ACCOUNT_CREDENTIALS_JSON` secret to inspect recent queries and pages related to agents, cloud agents, and orchestration. +- **Google Search Console** - When available, use the environment's `GSC_SERVICE_ACCOUNT_CREDENTIALS_JSON` secret to inspect recent queries and pages related to agents, cloud agents, and orchestration. Never print, log, commit, or include the secret value in reports. If a GSC client requires a credentials file path, write the secret to a restricted temporary file, use it for the run, and remove it before finishing. - **Docs repo** - Search existing pages under `src/content/docs/` for relevant source pages, link targets, and related terminology. If Peec or Google Search Console data is unavailable, say what could not be verified and proceed only with repo-grounded recommendations. Do not invent source signals. @@ -67,6 +67,7 @@ Before opening a PR, verify every proposed change: - **Anchor quality** - Link text is descriptive and specific; no raw URL anchors or generic anchors like "here," "this page," "learn more," or "read more." - **Link context** - The surrounding sentence explains why the destination is relevant when the link target is not obvious. - **Existing target** - Every internal link points to an existing file under `src/content/docs/`. +- **Anchor and route validation** - If a link includes a heading anchor or route path, verify that the route and anchor resolve. Do not rely only on the target file existing. - **Navigation awareness** - Check `src/sidebar.ts` when a linked page is expected to appear in navigation. - **Small scope** - The diff is limited to cross-linking and small copy changes needed to make links natural. - **No broad rewrites** - Remove any edit that becomes a rewrite, strategy recommendation, or new content proposal. @@ -76,6 +77,7 @@ Run: ```bash python3 .agents/skills/style_lint/style_lint.py --changed +python3 .agents/skills/check_for_broken_links/check_links.py --internal-only git diff --check ``` From 569ed400db8fa88a574e42f125f7b91f733a8bc1 Mon Sep 17 00:00:00 2001 From: rachaelrenk Date: Thu, 4 Jun 2026 16:34:17 +0000 Subject: [PATCH 4/4] docs: add AEO cross-links for agents and orchestration Add 3 internal cross-links across agent platform pages to improve navigation between orchestration, scheduling, and trigger docs: - platform.mdx: link Warp Orchestrator section to multi-agent orchestration docs - orchestration/index.mdx: link 'scheduled' in Review swarm pattern to scheduled agents - scheduled-agents.mdx: link 'triggered cloud agents' to integrations and 'triggers' to triggers overview Backed by Peec prompt signals and GSC query data showing user interest in scheduling, triggering, and orchestrating agents with no internal links connecting these concepts. Co-Authored-By: Oz --- .../docs/agent-platform/cloud-agents/orchestration/index.mdx | 2 +- src/content/docs/agent-platform/cloud-agents/platform.mdx | 1 + .../agent-platform/cloud-agents/triggers/scheduled-agents.mdx | 4 ++-- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx b/src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx index 55477f3e..77df6335 100644 --- a/src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx @@ -88,7 +88,7 @@ The parent (the "writer") proposes a solution, then spawns a critic child to rev ### Review swarm (cloud → cloud) -A scheduled or webhook-triggered parent spawns one cloud child per open pull request to run reviews in parallel. Each child posts its findings as a comment and exits. The parent fans in the results and posts a summary back to the triggering system. +A [scheduled](/agent-platform/cloud-agents/triggers/scheduled-agents/) or webhook-triggered parent spawns one cloud child per open pull request to run reviews in parallel. Each child posts its findings as a comment and exits. The parent fans in the results and posts a summary back to the triggering system. ### DAG diff --git a/src/content/docs/agent-platform/cloud-agents/platform.mdx b/src/content/docs/agent-platform/cloud-agents/platform.mdx index a3e823d3..f825d2b9 100644 --- a/src/content/docs/agent-platform/cloud-agents/platform.mdx +++ b/src/content/docs/agent-platform/cloud-agents/platform.mdx @@ -90,6 +90,7 @@ The orchestrator: * Tracks lifecycle state (created → running → completed/failed) and associated metadata. * Exposes task lifecycle operations via the [Oz CLI](/reference/cli/) and a [REST API](/reference/api-and-sdk/) (create tasks, query history, and inspect status/outputs). * Powers SDKs (TypeScript/Python) for programmatic usage on top of the orchestrator API. +* Supports [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) for parent/child workflows, fan-out, and review swarms. #### When teams use the API/SDK diff --git a/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx b/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx index a703ecb3..a0d712ee 100644 --- a/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx @@ -300,6 +300,6 @@ Carefully review prompts and schedules before deploying them broadly, especially Scheduled Agents are best when work should happen on a predictable cadence. -If you want an agent to run in response to an event, such as a Slack mention, PR update, or issue change, use triggered cloud agents instead. +If you want an agent to run in response to an event, such as a Slack mention, PR update, or issue change, use [integrations](/agent-platform/cloud-agents/integrations/) to trigger cloud agents instead. -Many teams use both together: triggers for reactive workflows, and Scheduled Agents for proactive maintenance. +Many teams use both together: [triggers](/agent-platform/cloud-agents/triggers/) for reactive workflows, and Scheduled Agents for proactive maintenance.