docs: add AEO cross-link audit skill

[rachaelrenk]

Summary

Adds the docs-side aeo_crosslink_audit skill for the recurring AEO cross-link audit pilot.

This is the companion docs PR to the Buzz snapshot workflow:

• Buzz PR: https://github.com/warpdotdev/buzz/pull/81
• Initial smoke-test output PR: Add internal cross-links for agent scheduling, monitoring, and triggers #176
• Latest smoke-test output PR using this updated skill: docs: add AEO cross-links for agents and orchestration #178

Changes

• Add .agents/skills/aeo_crosslink_audit/SKILL.md.
• Define the pilot scope: agents, cloud agents, and orchestration docs.
• Document source inputs: Peec snapshot, Google Search Console, and existing docs.
• Add self-review gates for link relevance, target existence, natural language, scope control, and no-change reports.
• Define PR and no-change report requirements for scheduled audit runs.
• Add link-quality guidance from PR Automated SEO fixes: improve docs link anchors #169 so the audit checks for descriptive anchors, contextual link intros, natural destination-page phrasing, redirect avoidance, and link-stuffing risks.
• Add link-density guardrails so the audit avoids over-linking pages, adding noisy related-link lists, or justifying links only through AEO/search coverage.
• Add style_lint --changed and internal broken-link checks to the recommended validation flow before opening audit PRs.

Validation

• Checked the skill file for trailing whitespace and final newline.
• Ran git diff --check.
• Added PR Automated SEO fixes: improve docs link anchors #169 link-quality rules to the skill and included style_lint --changed and check_for_broken_links --internal-only in the audit validation instructions.
• Validated the updated skill with a cloud smoke test that consumed the Buzz Peec snapshot and opened docs PR docs: add AEO cross-links for agents and orchestration #178.
• Earlier end-to-end smoke test opened docs PR Add internal cross-links for agent scheduling, monitoring, and triggers #176.

Co-Authored-By: Oz oz-agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 4, 2026 6:17pm

[oz-for-oss]

@rachaelrenk

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR adds .agents/skills/aeo_crosslink_audit/SKILL.md, a narrow scheduled-agent skill for finding small, source-grounded internal cross-link improvements across Agents, Cloud Agents, and orchestration docs. The scope and no-change reporting path are clear, and there is no approved spec context to compare against for implementation drift.

Concerns

• The link-quality gate should account for anchors or an explicit link-checking step, not only file existence.
• Security: the Google Search Console credential instruction should explicitly tell agents not to print or log the secret and to use a restricted temporary file if a client library requires a file path.

Security

• The only security finding is a documentation-process hardening suggestion around handling the GSC service account secret.

Verdict

Found: 0 critical, 0 important, 2 suggestions

Approve with nits

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz