update-settings-schema

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