Add documentation agent skills and voice references#834
Conversation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Documentation Preview ReadyYour documentation preview has been successfully deployed! Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-cms-834/docs/user-guide/quickstart/overview/ Updated at: 2026-05-12T22:10:30.893Z |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
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
The voice guide in particular is excellent reference material that will help maintain consistency across contributors. |
Restructure skills/references under .agents/ as the canonical source, with .claude/ and .kiro/ directories holding symlinks back into .agents/. This lets edits flow through any tool's expected path while keeping a single underlying file. Folds the now-redundant CLAUDE.md content into AGENTS.md, drops the forward-referenced exemplars/ step from docs-writer, clarifies the "skills" terminology overlap (SDK tools vs. agentskills.io files), notes that src/config/navigation.yml is the authoritative navigation source for the Astro site (mkdocs.yml is legacy), and adds STRANDS_SDK_PYTHON / STRANDS_SDK_TYPESCRIPT env var overrides for users whose SDK clones live outside the .build/ default.
|
Assessment: Approve The updated PR addresses all major feedback from the previous review. The Remaining minor items
None of these are blockers. The voice guide, terminology lock, and skill delineation are strong and ready to drive documentation consistency. |
The env-var override in code-verification.md was over-engineered for a case nobody is hitting: contributors who don't run `npm run sdk:clone` and don't have `gh` available. Tier 1 (gh api) and Tier 2 (.build/sdk-*) already cover the realistic paths. Restore the skills-and-triggers table from the original CLAUDE.md so readers can see what each skill does without opening four SKILL.md files.
|
Assessment: Approve No new issues in this iteration. The env var removal simplifies This is ready to merge. |
- AGENTS.md: note that the symlinks need Developer Mode or core.symlinks=true on Windows; suggest working in .agents/ directly if they don't resolve. - docs-reviewer: point the optional review log at .agents/review-log.md rather than .claude/review-log.md, so the path is consistent for agents reaching the skill via any tool's symlink.
|
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. 🚢 |
|
My updates to this PR were scoped to
Items 2 + 3 were pursued to keep our tooling neutral. The full content of the skills themselves was not fully reviewed. My thought was to iterate on the skills in follow up PRs. i.e. we have usage cases and can make updates based on those cases. If other's want to do a deeper initial pass on the skills themselves, we can do that too. |
notowen333
left a comment
notowen333
left a comment
There was a problem hiding this comment.
Excited to add these skills and continue to iterate them. Left a first pass of comments
| gh api repos/strands-agents/sdk-typescript/contents/src/[path] | ||
| ``` | ||
|
|
||
| **Key Python modules:** |
There was a problem hiding this comment.
We can beef up this and below TS module section for better completeness
|
|
||
| ## Tier 2: Local SDK Clones | ||
|
|
||
| If `gh` is unavailable, check the local clones populated by `npm run sdk:clone`: |
There was a problem hiding this comment.
I think we'll be more efficient to check file system first and then fall back to GH
| <!-- NEEDS-VERIFICATION: [class/method] against SDK source --> | ||
| ``` | ||
|
|
||
| Additionally, list all unverified blocks in the PR description so reviewers know what to check. Do not leave verification comments as the only safeguard on merged pages. |
There was a problem hiding this comment.
We don't want to raise anything in the PR description that is unverified
|
|
||
| Mark snippet boundaries in source files: | ||
|
|
||
| ```typescript |
There was a problem hiding this comment.
this example is confusing because it mixes the mdx and the TS snippet which is in a separate file
| Informational content. | ||
| ::: | ||
|
|
||
| :::tip |
There was a problem hiding this comment.
we can add one liner guidance for the patterns of when to use each of these
|
|
||
| ### Step 5: Competitive comparison (optional) | ||
|
|
||
| If the topic is covered by competitor docs (LangChain, CrewAI, Anthropic, OpenAI), fetch their equivalent page and note: |
There was a problem hiding this comment.
I think we might want to flesh out the procedure required here. Also which kinds of docs would require using this step
| - **Register:** Is the tone appropriate for the content type? | ||
| - **Constraints:** Scan for banned phrases, em-dashes, passive voice, hedging. Apply type-aware overrides (passive in reference is fine; longer sentences in explanation are fine). | ||
| - **Authenticity:** Structural variety, visible editorial choices, concision. | ||
|
|
There was a problem hiding this comment.
Can add
Narrative flow Start with why the topic matters and what use-case problems it solves. Throughout, show how to implement using Strands SDK in a self-contained, concise way.
| For each code block: | ||
| - Structurally complete (Stripe principle): imports present, variables defined, copy-paste-ready without hunting for context. | ||
| - Self-explanatory (Deno principle): makes sense without surrounding prose; comments explain intent, not mechanics. | ||
| - Realistic variable names (no `foo`, `bar`, `my_var`). |
There was a problem hiding this comment.
replace:
self-documenting, concise variable names (no foo, ...)
| - Comments explain intent, not mechanics | ||
| - One concept per code block | ||
|
|
||
| ### Step 3b: Apply MDX formatting |
There was a problem hiding this comment.
Can add a step for writing code snippets in their own files and link to the snippet guide I suggested
|
|
||
| **Bidirectional streaming.** For real-time interfaces (voice, interactive), document both the input and output streams. Show the event loop pattern, not just the output consumption pattern. | ||
|
|
||
| ### Version sensitivity |
There was a problem hiding this comment.
I think it would be more confusing than helpful to have an assortment of version minimums scattered throughout the docs themselves.
I'm OK to add the corresponding frontmatter for future use cases like 1.0/2.0, but would remove the directive to inline version requirements in prose
|
Note: I am finding really nice use of |
|
For automatic tagging system... me and @zastrowm spent some time reviewing what can be achieved in the automatic related page generation and decided it's better to curate links per page to ensure the best links and avoid erroneous links. So, we'll want to add some content in these skills to add a "Explore Next/See Also" (or some other verbiage) section. |
2 participants
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
Checklist
npm run devBy submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.