Add documentation agent skills and voice references

[ryanycoleman]

Description

I'm proposing a set of Agent Skills for docs planning, authoring, and validation to assist our team and community contributors who want to maintain documentation for Strands. Of these, I'm most opinionated about the voice guide which dictates approaches for varying types of content.

Related Issues

Type of Change

• New content

Checklist

• I have read the CONTRIBUTING document
• My changes follow the project's documentation style
• I have tested the documentation locally using npm run dev
• Links in the documentation are valid and working

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Documentation Preview Ready

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-cms-834/docs/user-guide/quickstart/overview/

Updated at: 2026-05-22T19:45:18.305Z

[github-actions]

Assessment: Comment

This is a well-thought-out set of documentation agent skills and voice references. The five-layer voice guide, terminology lock, and skill delineation (writer/reviewer/auditor/planner) show strong editorial thinking.

Review Themes

• Scope clarity: The relationship between CLAUDE.md and the existing AGENTS.md needs clarification so contributors know which to follow. Both provide agent guidance with different scopes.
• Forward references: The docs-writer skill references a non-existent exemplars/ directory, and the cross-agent compatibility claim in CLAUDE.md may overstate current portability.
• Terminology coherence: "Skills" appears in the terminology lock as a banned synonym for "tools" (in SDK context), but this PR uses "skills" in the agentskills.io sense. A clarifying note would prevent confusion.
• Graceful degradation: Skills that depend on external tools (gh CLI, web access) should specify fallback behavior more explicitly.

The voice guide in particular is excellent reference material that will help maintain consistency across contributors.

[github-actions]

Assessment: Approve

The updated PR addresses all major feedback from the previous review. The .agents/ canonical location with symlinks for .claude/ and .kiro/ is a clean tool-agnostic architecture, and the AGENTS.md updates tie everything together well.

Remaining minor items

• Symlink portability: Windows users may need Developer Mode for symlinks to work. A one-line note in AGENTS.md would prevent confusion.
• Review log path: docs-reviewer references .claude/review-log.md which is tool-specific in an otherwise tool-agnostic skill set.
• Env var discoverability: The STRANDS_SDK_* env vars in code-verification.md are a nice addition but not discoverable from other docs yet.

None of these are blockers. The voice guide, terminology lock, and skill delineation are strong and ready to drive documentation consistency.

[github-actions]

Assessment: Approve

No new issues in this iteration. The env var removal simplifies code-verification.md and the skills table in AGENTS.md improves discoverability. The two minor items from the previous review (.claude/review-log.md path in docs-reviewer, Windows symlink note) remain open but are non-blocking and can be addressed in a follow-up.

This is ready to merge.

[github-actions]

Assessment: Approve

All previous feedback has been addressed. The Windows symlink note and the review-log path fix were the last two items — both resolved in this commit. No new issues identified.

Ready to merge. 🚢

[github-actions]

Assessment: Comment

The skills content has materially improved in this iteration — the expanded module listings in code-verification, the imports/body snippet pattern in mdx-authoring, and the "claim parity" check in docs-reviewer all strengthen the tooling. The tier reordering (local clones first) is pragmatic.

Key Issue

• Path resolution: All skills reference paths (src/content/docs/, .build/, src/config/navigation.yml) as repo-root-relative, but the site content now lives under site/. An agent discovering skills at the root will fail to find these paths. This needs a clear working-directory directive.

The content quality is high. The path issue is the only blocking concern — once agents know to operate from site/, everything else works.

[github-actions]

Assessment: Comment

The skills system is well-designed with clear separation of concerns and good cross-referencing. The path resolution issue from the previous review has been fully addressed. Two remaining schema-level inconsistencies could lead agents to produce invalid frontmatter.

Review Details

• Schema mismatch: The docs-writer template includes frontmatter fields (contentType, minSDKVersion, lastReviewed) that don't exist in the Zod schema — they'll be silently stripped at build time. The mdx-authoring.md reference is also missing two real schema fields (tags, sourceLinks) and one enum value (agent-extension).
• Discoverability: No AGENTS.md at the repo root means the development workflow guidance won't be auto-discovered by tools that look for it there. Skills are still discoverable via .claude/skills/.

The voice guide, terminology lock, and skill delineation are strong. The schema issues are the only items that would cause agents to produce incorrect output.

[github-actions]

Assessment: Approve

The latest commit resolves the path resolution issue from the previous review — all file references now correctly include the site/ prefix with a clear note in code-verification.md about working directory expectations. The content quality across all skills and references is high.

Minor item

• mdx-authoring.md line 82: The snippet path resolution description ("you can also write them relative to the repo root with the site/ prefix") could confuse an agent into double-nesting paths. See inline comment.

The skills framework is well-structured, the separation of concerns between writer/reviewer/auditor/planner is clear, and the voice guide provides strong editorial guidance. Ready to merge.