update-schema-docs

name

update-schema-docs

description

Detect schema.py changes and update front-matter-spec.md, architecture.md, and the public docs site (docs/index.md, docs/getting-started.md) with examples and documentation. Use when schema.py has been modified as part of a feature to ensure documentation stays synchronized with the schema source of truth. Automatically generates usage examples, updates field descriptions, flags architecture changes that need manual review, and flags docs-site landing/onboarding copy that should mention new user-facing capabilities. Trigger on schema changes during feature development, or when asked to 'update docs for schema changes', 'sync schema documentation', 'add examples for new config fields', or 'update the docs site for this feature'.

update-schema-docs — Schema-driven documentation synchronization

This skill ensures docs/front-matter-spec.md, docs/architecture.md, and the public docs site's landing/onboarding pages (docs/index.md, docs/getting-started.md) stay synchronized when src/azure_functions_agents/config/schema.py changes. docs/front-matter-reference.md is already auto-generated (via eng/scripts/generate_config_reference.py), but spec, architecture, and docs-site pages require intelligent example generation and contextual updates.

When to use

Use this skill during Phase 5 (Docs) of the medium+ feature pipeline when:

• schema.py has been modified (new fields, models, or validation logic)
• New public configuration surface was added
• After implementing config-related features
• When asked to synchronize documentation with schema changes

What this skill does

1. Detect changes: Compare current schema.py against the last commit or baseline to identify added/modified fields and models.
2. Update front-matter-spec.md:
   • Add usage examples for new fields
   • Update existing examples if field semantics changed
   • Add validation examples for new constraints
   • Ensure Examples section coverage matches the reference
3. Review architecture.md:
   • Flag if new models suggest pipeline stage changes
   • Check if module map needs updates
   • Verify configuration precedence rules still hold
4. Sync the docs site landing pages:
   • If the change introduces a new user-facing capability (new trigger type, new frontmatter field a typical user would reach for, new model provider), check whether docs/index.md's feature bullet list or docs/getting-started.md's walkthrough should mention it
   • Skip this step for internal-only or low-level schema changes (e.g. tightened validation, refactors) that don't change what a new user sees
5. Generate PR checklist: List all doc changes made + items needing human review

Prerequisites

• schema.py changes committed or staged
• Understanding of what the schema change enables (from the FRD)
• eng/scripts/generate_config_reference.py already run (reference up to date)

Workflow

Step 1: Analyze schema changes

1. Read the current src/azure_functions_agents/config/schema.py

2. Identify what changed:

   • New models (e.g., new trigger types, new capabilities)
   • New fields on existing models (e.g., GlobalConfig, AgentSpec)
   • Changed field types or validators
   • New Pydantic constraints or defaults

3. Categorize changes by impact:

   • Agent frontmatter surface: affects AgentSpec → needs examples in spec
   • Global config surface: affects GlobalConfig → needs global examples
   • Trigger surface: affects trigger models → needs trigger examples
   • Structural: new pipeline stage or module → needs architecture review

Step 2: Update front-matter-spec.md

For each new or changed field:

1. Locate the relevant section:

   • Agent fields → ### Agent Front Matter examples
   • Global fields → ### Global Configuration examples
   • Trigger fields → ### Triggers or ### Advanced Examples

2. Generate usage examples:

   • Start from the field's type, description, and default in schema.py
   • Create realistic YAML examples showing:
     • Basic usage (most common case)
     • Edge cases (if validation is complex)
     • Integration with related fields
   • Follow existing example style (concise, commented, realistic values)

3. Add validation examples if needed:

   • If the field has custom validators (e.g., CRON expressions, URL patterns)
   • Show valid and invalid examples with explanations

4. Cross-reference to the reference:

   • Link to front-matter-reference.md#<section> for full API details
   • Ensure the spec focuses on how to use, reference on what exists

Step 3: Review architecture.md

1. Check if module map needs updates:

   • New models in schema.py may indicate new modules in config/, discovery/, etc.
   • Verify the module map in §3 reflects reality
   • If discovery logic changed, update the discovery stage description

2. Check if pipeline stages changed:

   • New configuration may affect discover → translate → register → execute flow
   • Document new capabilities or constraints in the relevant stage

3. Check configuration precedence:

   • If new global/agent/env interactions exist, update §4 precedence rules
   • Ensure the precedence diagram (if present) is still accurate

Step 4: Sync docs-site landing pages

1. Decide if this change is docs-site-worthy:

   • New trigger type, new top-level frontmatter field, new model provider, or any change that adds a bullet-worthy capability → yes
   • Internal refactors, stricter validation, or field renames with no new capability → no, skip

2. Update docs/index.md (if worthy):

   • Add a concise bullet to the feature list matching the existing bullet style (bold lead-in, em dash, one sentence)

3. Update docs/getting-started.md (if worthy and walkthrough-relevant):

   • Only touch the quickstart steps if the new capability changes the minimal path to a working agent (e.g. a new required config file, a new provider env var). Don't pad the walkthrough with optional features.

4. Cross-check README.md: the docs site and README duplicate the same feature bullet list — if you update one, flag (or update) the other so they don't drift.

Step 5: Generate PR checklist

Create a checklist of:

• front-matter-reference.md updated (auto-generated via script)
• front-matter-spec.md examples added for: <list new fields>
• architecture.md module map verified
• docs/index.md and docs/getting-started.md checked (updated / not applicable)
• Human review needed for: <list architectural concerns>
• Validation examples added for: <list complex validators>

Example: Adding a new agent field

Scenario: AgentSpec gained a new field retry_policy: RetryPolicyConfig | None = None

Actions:

1. Analyze: New optional field on AgentSpec, type is a nested model

2. Update front-matter-spec.md:

   ---
   name: Resilient Agent
   description: Agent with automatic retry logic
   retry_policy:
     max_attempts: 3
     backoff_multiplier: 2
     initial_delay_ms: 1000
   trigger:
     type: http_trigger
     args:
       route: resilient
   ---
   

   Add to ### Agent Front Matter examples with commentary explaining retry behavior

3. Review architecture.md:

   • Check if runner stage (§3.4) mentions retry logic
   • If RetryPolicyConfig is in a new module, add to module map
   • No pipeline stage changes needed (execution detail)

4. Checklist:

   • front-matter-reference.md updated
   • front-matter-spec.md: added retry_policy example under Agent Front Matter
   • architecture.md: verified runner stage mentions retry (update if not)
   • docs/index.md, docs/getting-started.md: not applicable (advanced/optional field, not quickstart-worthy)
   • Human review: decide if retry belongs in runner or client_manager

Example: Adding a new trigger type

Scenario: New CosmosDbTrigger model added to schema.py

Actions:

1. Analyze: New trigger model → new public surface in trigger.type

2. Update front-matter-spec.md:

   ---
   name: Cosmos Change Feed Agent
   description: Responds to Cosmos DB document changes
   trigger:
     type: cosmosdb_trigger
     args:
       database_name: my-database
       container_name: my-container
       connection: CosmosDbConnection
       lease_container_name: leases
   ---
   

   Add to ### Triggers section with explanation of change feed behavior

3. Update docs/triggers.md (if it exists):

   • Add detailed CosmosDB trigger documentation
   • Explain lease container, change feed continuation, etc.

4. Review architecture.md:

   • Discovery stage: verify it mentions trigger discovery from schema
   • Registration stage: confirm it handles new binding type
   • Module map: ensure registration/triggers.py is listed

5. Checklist:

   • front-matter-reference.md updated (auto via TRIGGER_TYPES dict in script)
   • front-matter-spec.md: added cosmosdb_trigger example
   • docs/triggers.md: added detailed CosmosDB section
   • architecture.md: verified trigger registration flow

Output format

When this skill completes, provide:

1. Summary of changes made:

   Schema changes detected:
   - Added field: AgentSpec.retry_policy (optional, nested config)
   - Modified field: GlobalConfig.timeout (type widened to int | str)
   
   Documentation updates:
   - front-matter-spec.md: Added retry_policy example (line 245)
   - front-matter-spec.md: Updated timeout example to show string format (line 89)
   - architecture.md: Verified runner stage docs (no changes needed)
   - docs/index.md, docs/getting-started.md: not applicable (advanced field, not quickstart-relevant)
   

2. PR checklist (markdown, ready to paste):

   ## Documentation Updates (Schema Changes)
   
   - [x] `front-matter-reference.md` regenerated via `generate_config_reference.py`
   - [x] `front-matter-spec.md` examples added for: `retry_policy`
   - [x] `front-matter-spec.md` timeout example updated to show string support
   - [x] `architecture.md` module map verified (no changes needed)
   - [x] `docs/index.md` / `docs/getting-started.md` checked (not applicable)
   - [ ] **Human review:** Retry logic placement (runner vs client_manager?)
   

3. Architectural concerns (if any):

   ⚠️ Human review needed:
   - New RetryPolicyConfig model suggests retry logic in the runner.
     Does this conflict with MAF's built-in retry? Check AgentClient docs.
   - If retry is per-request, should it live in client_manager instead?
   

Guardrails

• Do not auto-generate prose sections of architecture.md — only verify module map and flag inconsistencies. Design decisions require human judgment.
• Match the existing example style in front-matter-spec.md — concise, realistic, focused on common use cases.
• Link liberally — examples in spec should reference the reference for complete API details.
• Favor explicit over exhaustive — one good example > ten variations.
• This skill complements, does not replace, human review — complex architectural implications still need human sign-off in the FRD Decisions log.

Integration with AGENTS.md Phase 5

This skill is invoked during Phase 5 (Docs) of the medium+ pipeline, after eng/scripts/generate_config_reference.py has been run. The workflow becomes:

1. Run generate_config_reference.py → updates front-matter-reference.md
2. Run this skill → updates front-matter-spec.md examples, reviews architecture.md, and syncs docs/index.md / docs/getting-started.md when the change adds a new user-facing capability
3. Human reviews the PR checklist and architectural concerns
4. Commit documentation updates alongside implementation

Files touched

• Input (read):

  • src/azure_functions_agents/config/schema.py (detect changes)
  • docs/front-matter-reference.md (understand new API surface)
  • docs/frds/<NNNN>-<slug>.md (understand intent of schema changes)

• Output (write):

  • docs/front-matter-spec.md (add/update examples)
  • docs/triggers.md (if trigger surface changed)
  • docs/index.md (if a new user-facing capability warrants a feature bullet)
  • docs/getting-started.md (if the new capability changes the minimal quickstart path)

• Output (review/flag):

  • docs/architecture.md (flag inconsistencies, suggest updates)
  • README.md (flag if user-facing quickstart examples need updates)

Success criteria

• Every new field in schema.py has at least one usage example in front-matter-spec.md
• Existing examples updated if field semantics changed
• Architecture.md module map matches reality
• docs/index.md and docs/getting-started.md checked for every schema change that adds a new user-facing capability (bullet added or explicitly deemed not applicable)
• Clear PR checklist with human review items flagged
• No "orphaned" documentation (examples for removed fields)