Update Settings Schema Command

Update the custom JSON schema for Claude Code settings by researching official documentation, parsing the CHANGELOG, and merging discovered settings.

Arguments

Argument	Description
(none)	Full update: research, generate, validate, write
--dry-run	Show changes without writing
--validate-only	Validate current schema without updating
--diff	Show diff between current and generated
--sync-env-vars	Force sync environment variables from canonical docs

Workflow

Step 1: Load Current State

Read the current schema and extract version metadata:

Schema location: plugins/claude-ecosystem/skills/settings-management/references/claude-code-settings.schema.json
Extract: x-schema-version, x-claude-code-version, x-changelog-hash

Step 2: Extract Environment Variables

Run the env var extraction from canonical docs (stored in docs-management):

python plugins/claude-ecosystem/skills/settings-management/scripts/schema/extract_env_vars.py

This extracts 68+ environment variables from the settings.md documentation with:

• Full descriptions
• Category tags (authentication, model-config, provider, bash-behavior, etc.)
• Boolean flag detection (enum: ["0", "1"])
• Deprecation markers
• Version annotations (x-since)

Step 3: Research Sources (Parallel)

Invoke all three research sources in the SAME message:

1. docs-management skill - Query for settings documentation:

   Invoke docs-management skill with query: "settings.json available settings schema options table env hooks permissions sandbox"
   

2. claude-code-guide agent - Live web search:

   Spawn claude-code-guide subagent with prompt:
   "First WebFetch https://code.claude.com/docs/en/claude_code_docs_map.md to find relevant doc pages about settings configuration. Then WebFetch the settings.md page. Use WebSearch only if needed for additional context about new settings fields. Return a list of all settings fields with their types and descriptions."
   

3. Changelog fetch - Get latest CHANGELOG.md:

   WebFetch https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md
   Extract settings-related entries from v2.1.0 onwards.
   

Step 4: Merge and Deduplicate

Priority order for conflicting information:

1. Official docs (via docs-management) - highest priority
2. Web search (via claude-code-guide) - medium priority
3. Changelog (via WebFetch) - lowest priority

For each setting field:

• If in official docs: mark x-source: "official"
• If only in web search: mark x-source: "web"
• If only in changelog: mark x-source: "changelog"
• Add x-since: "version" for changelog-discovered fields

Step 5: Validate

Run the validation script:

python plugins/claude-ecosystem/skills/settings-management/scripts/schema/validate_schema.py --verbose

Schema must:

• Be valid JSON Schema draft-07
• Have all required x- metadata fields
• Pass example validation (if --check-examples)

Step 6: Write (unless --dry-run)

If validation passes and not --dry-run:

1. Update the schema file
2. Increment x-schema-version (patch version)
3. Update x-last-updated to today
4. Update x-changelog-hash with new hash
5. Update x-env-var-count with current env var count

Step 7: Report

Show summary:

Schema Update Summary
--------------------
Previous version: 1.0.0
New version: 1.1.0
Claude Code tracked: 2.1.9
Properties: 40 (+3 new)
  + plansDirectory (v2.1.9, changelog)
  + showTurnDuration (v2.1.7, changelog)
  + mcpToolSearch (v2.1.7, changelog)

Environment Variables: 68
  Categories: authentication (6), model-config (10), provider (6),
              bash-behavior (7), configuration (15), disable-flags (13),
              proxy (3), mcp (5), vertex-bedrock (5), tools (2)

Validation: PASSED
Written to: .../claude-code-settings.schema.json

What This Command Does NOT Do

• Does NOT modify SchemaStore directly (that requires a PR to SchemaStore repo)
• Does NOT scrape arbitrary web pages (only official Claude docs)
• Does NOT auto-commit changes (user must commit manually)

Mode-Specific Behavior

--validate-only

Skip research and write steps. Only validate current schema:

python .../validate_schema.py --verbose --check-examples

Report validation results and exit.

--dry-run

Execute full workflow but skip Step 5 (write). Show what would change.

--diff

Execute full workflow, generate new schema in memory, show diff:

+ Added: mcpToolSearch (string)
~ Modified: hooks.PreToolUse (added additionalContext note)
  x-schema-version: 1.0.0 -> 1.0.1
  x-last-updated: 2026-01-15 -> 2026-01-16

Related Commands

• /audit-settings - Audit settings.json files against this schema
• /list settings - List available settings fields

Related Files

File	Purpose
references/claude-code-settings.schema.json	The custom schema file with 68 env vars
scripts/schema/generate_schema.py	Schema generation and env var sync
scripts/schema/extract_env_vars.py	Extract env vars from canonical docs
scripts/schema/validate_schema.py	Standalone validator
.claude/ecosystem-health.yaml	Tracks schema version