Agent-Skills.md

Agent Skills: Update Settings Schema Command

Update the custom Claude Code settings JSON schema with changelog-discovered and web-verified settings.

UncategorizedID: melodic-software/claude-code-plugins/update-settings-schema

Repository

melodic-software/claude-code-plugins
melodic-softwareLicense: MIT
417

Install this agent skill to your local

pnpm dlx add-skill https://github.com/melodic-software/claude-code-plugins/tree/HEAD/plugins/claude-ecosystem/skills/update-settings-schema

Skill Files

Browse the full folder contents for update-settings-schema.

Download Skill

Loading file tree…

plugins/claude-ecosystem/skills/update-settings-schema/SKILL.md

Skill Metadata

Name
update-settings-schema
Description
Update the custom Claude Code settings JSON schema with changelog-discovered and web-verified settings.

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 |