Claude frequently misconfigures Claude Code settings - Proposal to use Skill instead of agent delegation

Issue: Claude frequently misconfigures Claude Code settings - Proposal to use Skill instead of agent delegation

Problem Description

When users ask Claude to configure Claude Code settings (MCP servers, hooks, skills, etc.), Claude often provides incorrect file paths and configurations based on memory rather than consulting official documentation.

Example of the problem

User: "Where should I put my MCP server configuration?"

Claude's incorrect response:

~/.claude/settings.json  ❌ (wrong)

Correct answer (per official docs):

~/.claude.json           ✅ (user scope MCP config)
.mcp.json                ✅ (project scope MCP config)

This happens because Claude relies on potentially outdated training data rather than fetching current documentation.

Current Mechanism: claude-code-guide agent

Claude Code provides the claude-code-guide agent specifically for answering Claude Code-related questions. However, there are issues:

Problem 1: Agent is not proactively triggered

Claude does not automatically use claude-code-guide when discussing Claude Code configuration. Users must explicitly request it, which defeats the purpose of having a specialized agent.

Problem 2: Information loss through delegation

Even when claude-code-guide is used, the information flow is:

User Question → Main Claude → Delegate to claude-code-guide agent → Agent fetches docs → Agent summarizes → Returns to Main Claude → Main Claude rephrases → User

Each step introduces potential for:

• Information loss: Key details may be omitted in summarization
• Misinterpretation: Main Claude may misunderstand the agent's response
• Context loss: The agent doesn't have full conversation context

Proposed Solution: Use a Skill instead

Skills are automatically triggered based on description keywords and inject knowledge directly into the main Claude's context, eliminating the delegation problem.

Why Skill is better for this use case

| Aspect | Agent (current) | Skill (proposed) |
|--------|-----------------|------------------|
| Triggering | Must be explicitly called | Auto-triggered by keywords |
| Information flow | Delegated → summarized → returned | Direct injection into main context |
| Context awareness | Separate context | Full conversation context |
| Accuracy | May lose details in transfer | No information loss |

Example Skill: claude-config-guide

We've created a working example that addresses this issue:

---
name: claude-config-guide
description: |
  Query Claude Code configuration, file locations, MCP settings, and official documentation.
  Use this skill proactively when the conversation involves:
  - Claude Code settings, configuration, config, settings
  - MCP server setup, mcp.json, mcpServers
  - ~/.claude.json, .mcp.json, settings.json locations
  - hooks, slash commands, skills configuration
  - Claude Code features, API, SDK questions
allowed-tools: WebFetch, Read, Glob, Grep
---

# Claude Config Guide

This Skill helps you query correct Claude Code configuration information.

## Execution Steps (IMPORTANT!)

**You MUST WebFetch official documentation - never answer from memory!**

### Step 1: Query the documentation sources

**Two primary documentation sources:**

| Source | URL | Purpose |
|--------|-----|---------|
| Claude Code CLI docs | https://code.claude.com/docs/en/claude_code_docs_map.md | CLI configuration, MCP, hooks, skills |
| Claude API/SDK docs | https://platform.claude.com/llms.txt | API reference, Agent SDK, platform features |

### Step 2: Based on the question type, WebFetch the corresponding doc

**Claude Code CLI documentation:**

| Question Type | Documentation URL |
|---------------|-------------------|
| MCP config | https://code.claude.com/docs/en/mcp.md |
| Settings | https://code.claude.com/docs/en/settings.md |
| Hooks | https://code.claude.com/docs/en/hooks.md |
| Skills | https://code.claude.com/docs/en/skills.md |
| Commands | https://code.claude.com/docs/en/slash-commands.md |

**Claude API/SDK documentation:**

| Question Type | Documentation URL |
|---------------|-------------------|
| Agent SDK | https://platform.claude.com/docs/en/agent-sdk/overview.md |
| Claude API | https://platform.claude.com/llms.txt (index) |
| MCP connector (API) | https://platform.claude.com/docs/en/agents-and-tools/mcp-connector.md |

### Step 3: Parse and respond
Extract relevant information from WebFetch results and answer the user directly.

## Why not use a sub-agent?

Sub-agent responses require paraphrasing, which may cause information loss.
**Fetch the docs yourself for more direct and accurate information.**

How this Skill works

1. Auto-triggered: When conversation mentions "Claude Code config", "MCP settings", "hooks", etc.
2. Direct action: Main Claude executes WebFetch itself (no delegation)
3. Fresh data: Always fetches current documentation, not relying on training data
4. Full context: Main Claude can correlate docs with full conversation history

Recommendation

Consider either:

1. Include a similar Skill in Claude Code by default - Ship a claude-config-guide Skill that auto-triggers for configuration questions

1. Improve the agent triggering mechanism - Make claude-code-guide agent proactively triggered when configuration topics are detected

1. Add self-documentation fetching to system prompt - Instruct Claude to always WebFetch official docs before answering configuration questions

Environment

• Claude Code version: Latest
• OS: macOS
• Model: claude-opus-4-5-20250514

Related

• The claude-code-guide agent exists but is underutilized
• Users must work around this by creating custom Skills