Ak Dev Sync Docs From Branch

Sync Documentation From Branch Changes

Use this skill when a feature branch or bugfix branch is functionally ready and you need to align Agent Kernel documentation with what actually changed.

This skill is for documentation maintenance driven by code diff, not for implementing the feature itself.

Goal

Read the branch delta, infer what user-facing and contributor-facing documentation changed, then update the relevant docs across the repository.

Required documentation surfaces covered by this skill:

1. ak-py/README.md
2. docs website content under docs/ — update existing pages, add pages, remove obsolete pages, and adjust intro/getting-started/reference sections as needed, including the React landing and features pages (docs/src/pages/index.tsx, docs/src/pages/features.tsx) whose hard-coded inventories drift silently when only markdown is updated
3. README files under ak-deployment/
4. example README files when an example was added or changed, plus docs-site references to those examples
5. root README.md
6. root DEVELOPER_GUIDE.md

When to Use This Skill

Use this skill when all of the following are true:

1. The developer is on a feature or bugfix branch.
2. The implementation is already done or nearly done.
3. There are new commits on the branch and/or uncommitted local changes.
4. The branch changes behavior, setup, APIs, integrations, deployment flows, examples, capabilities, or contributor workflows in ways documentation should reflect.

Do not use this skill as the first step of a feature. Use it near the end, before merge or PR finalization.

Step 1: Determine the Comparison Base

Find the correct baseline branch first.

Preferred order:

1. The PR target branch if it is known.
2. The upstream tracking branch for the current branch.
3. origin/develop.
4. develop.

For this repository, prefer origin/develop or develop as the default base branch unless the PR target or upstream tracking branch says otherwise.

Use Git to identify the merge base between the current branch and that baseline.

Minimum evidence to gather:

• current branch name
• merge base commit
• commits since merge base
• staged changes
• unstaged changes

If the baseline is ambiguous, state the assumption you are using and continue.

Step 2: Read the Branch Delta

Inspect both committed and uncommitted work.

Required diff inputs:

1. Committed changes on the branch
   • commits since merge base
   • file list and diff summary
2. Current local changes
   • staged diff
   • unstaged diff

Pay special attention to changes in:

• ak-py/src/agentkernel/
• ak-py/README.md
• ak-deployment/
• examples/
• docs/
• root README.md
• root DEVELOPER_GUIDE.md
• tests, examples, and Terraform modules that imply docs drift

Step 3: Map Code Changes to Documentation Impact

Classify the branch delta into these buckets:

1. Root-level product docs drift

   • project overview, supported features, installation, quick start, contributor guidance
   • update README.md and DEVELOPER_GUIDE.md as needed

2. Package-level docs drift

   • Python package install, CLI, skills, APIs, framework support, configuration
   • update ak-py/README.md

3. Docs website drift

   • new capabilities, changed setup steps, outdated examples, missing pages, obsolete pages
   • update or add/remove pages under docs/

4. Deployment docs drift

   • Terraform modules, module inputs, deploy flows, packaging changes, environment setup
   • update relevant ak-deployment/**/README.md files

5. Example docs drift

   • example added, removed, renamed, or behavior changed
   • update example README files and docs-site references to those examples

Step 4: Required Documentation Surfaces

You must evaluate all of these surfaces before deciding no documentation work is needed:

Root Docs

• README.md
• DEVELOPER_GUIDE.md

Package Docs

• ak-py/README.md

Docs Website

• pages under docs/docs/
• related docs metadata such as sidebars or linked overview pages when needed
• intro/getting-started/reference/example pages that are affected by the branch change
• the What's New tip at the top of docs/docs/intro.md when the branch ships a headline capability
• the React landing and features pages (next subsection): these are not generated from markdown, so a new framework, integration, provider, transport, or capability is invisible there until its entry is added by hand

Docs-Site Landing and Features Pages (React)

The landing page (docs/src/pages/index.tsx) and the features page (docs/src/pages/features.tsx) enumerate the product surface in hard-coded data, so a new framework, integration, provider, transport, or capability is invisible there until its entry is added by hand. On the landing page the inventories live in three component data files, not in index.tsx itself:

index.tsx itself still holds the WhatsNewBanner text, the hero's Agent Skills block (the two install commands only; there is no per-skill list on the landing page any more), and the clouds list in Deployment. Read the current data before editing and confirm identifiers with grep -n "const " docs/src/pages/index.tsx docs/src/components/*/data.tsx.

Rules for these pages:

• Keep counts and names in sync with the code and with docs/docs/ (a "six providers" hint or "4 SDKs" highlight goes stale the moment a backend is added).
• Every third-party integration (a vendor, a protocol, a managed service) gets a marquee tile; built-ins such as in_memory, local_subprocess, or env do not. href points at the docs page; a page that exists only in the unreleased docs takes the /docs/next/... path with a comment to drop next after the release.
• Logo, in this order: an existing asset under docs/static/img/integrations/; a Simple Icons glyph from react-icons/si (confirm the export exists, since Simple Icons has dropped the AWS, Microsoft, Slack, and OpenAI marks); otherwise the vendor's own SVG or PNG saved under docs/static/img/integrations/. Set mono: true for a black-on-transparent mark and wide: true for a wordmark.
• A marquee tile name is an identifier: ArchitectureOverview picks chips by it, so a rename there without the matching pick() change fails the static build.
• FLOW_WORDS in the architecture data and the labels in FEATURE_TABS are the same six words; change both or neither.
• Follow the existing entry shape exactly; do not restyle or restructure a section to add one entry.
• The other persona pages (docs/src/pages/developer.tsx, ai-engineer.tsx, business-leader.tsx, use-cases.tsx) carry their own feature groups; grep them for the old name or count whenever an inventory changes.
• Verify with the docs build, which also fails on broken internal links: cd docs && npm ci && NODE_OPTIONS=--max-old-space-size=8192 npm run build.