feat: add aeo_new_guide_recommendations skill

[rachaelrenk]

Summary

Adds the aeo_new_guide_recommendations skill and its run log, implementing the Notion task: AEO automation: new-guide recommendations.

This is the upstream content-planning complement to the aeo_crosslink_audit skill. Where the crosslink audit finds missing links between existing pages, this skill finds missing or underserved topics and recommends whether to create a new guide, update an existing page, or avoid a topic — without drafting content.

What this adds

.agents/skills/aeo_new_guide_recommendations/SKILL.md
A bi-weekly scheduled agent skill that:

• Checks Peec snapshot freshness (same 14-day gate as crosslink audit)
• Reads the prior run log to detect repeat topic recommendations
• Extracts source signals from the Peec snapshot (prompts, query clusters, action recommendations, visibility gaps) for agents, cloud agents, orchestration, and Oz
• Compares against existing docs to identify missing or underserved topics
• Produces 3–5 AEO briefs per run using the aeo_brief format (recommendation, source signals, vocabulary map, content scope, existing docs to touch, open questions)
• Writes an Oz run report (no docs-content PR — output lives in the run)
• Writes a run log entry via a perpetual chore/aeo-new-guide-rec-log PR (same pattern as crosslink audit)
• Posts a Slack notification to #growth-docs

.agents/logs/aeo_new_guide_recommendation_runs.md
Initialized empty run log with header and format reference.

Design decisions

Question	Decision
Output format	Oz run repo
Topic areas	Agents, cloud agents, orchestration, Oz
Cadence	Bi-weekly
Re-evaluation	Surface new topics each run; flag repeats if a topic appeared in a prior log entry

Environment secrets needed (when deploying as a scheduled agent)

• SLACK_BOT_TOKEN
• GROWTH_DOCS_SLACK_CHANNEL_ID

These match the crosslink audit's existing environment setup.

Not in scope

• Drafting content
• Creating or editing docs pages
• Opening docs-content PRs
• Scheduling the Oz agent (separate step after this skill is reviewed)

---

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

Warp conversation: https://staging.warp.dev/conversation/a9c3a6a9-83c7-48a5-a74a-345345460680

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jul 9, 2026 9:37pm

[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 a new recurring AEO new-guide recommendation skill and initializes its run log. The review found two workflow correctness issues in the skill instructions: the scope forbids PR creation while the required log workflow depends on a persistent log PR, and the newly included Oz scope is not backed by the configured Peec snapshot sources. No approved spec context was available, and no security-specific findings were identified.

Concerns

• The skill tells agents not to open a PR even though step 7 requires creating or updating the long-lived run-log PR.
• Oz is listed as a required pilot/output topic, but the source data instructions still point to a snapshot described as covering only agents, cloud agents, and orchestration.

Verdict

Found: 0 critical, 2 important, 0 suggestions

Request changes

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

Powered by Oz