Debug a setup that is not doing what you expect

The steps

One step at a time. When a step’s check matches, tick it and the next one opens.

1. 01

   Step 1 of 5: Build the broken practice folder

   A script writes a small folder with three planted mistakes, next to your project.

   TerminalCopy

   Run: $ node scripts/make-broken-setup.mjs

   Run: $ cd ../acme-broken-setup

   – What happens: Nothing in your project changes.

   scripts/make-broken-setup.mjs · JavaScriptCopy

   // Day 47: builds a small practice folder whose Claude Code setup has three
   // planted mistakes, so you can find them with Claude Code's own checks.
   //
   //   node scripts/make-broken-setup.mjs [folder]
   //
   // It writes only to the folder you name, by default ../acme-broken-setup
   // (next to this project), and refuses to touch a folder that already exists.
   // Nothing in this project changes, so the mistakes never reach your real
   // setup or a later kit. Tested by test/broken-setup.test.js.
   import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
   import path from 'node:path';
   import { fileURLToPath } from 'node:url';
   
   const root = path.resolve(fileURLToPath(new URL('..', import.meta.url)));
   const target = path.resolve(process.argv[2] ?? path.join(root, '..', 'acme-broken-setup'));
   
   if (existsSync(target)) {
     console.error(`${target} already exists. Delete it, or pass another folder name.`);
     process.exit(1);
   }
   
   // The answers are in the Day 47 lesson, not here, so the folder can't give
   // them away. Each file below holds one mistake.
   const files = {
     'README.md': [
       '# Broken setup (practice)',
       '',
       'Three things in this folder\'s Claude Code setup are wrong on purpose.',
       'Start Claude Code here and use the checks from Day 47 of the',
       'HorizonLux 52-Day Claude Code Challenge to find and fix them:',
       'https://horizonlux.com/resources/claude-code-challenge',
       '',
     ].join('\n'),
   
     '.claude/settings.json': [
       '{',
       '  "hooks": {',
       '    "SessionStart": [',
       '      {',
       '        "hooks": [',
       '          {',
       '            "type": "command",',
       '            "command": "node",',
       '            "args": ["-e", "console.log(\'The practice hook ran, so the hooks in this folder loaded.\')"]',
       '          }',
       '        ]',
       '      }',
       '    ],',
       '  }',
       '}',
       '',
     ].join('\n'),
   
     '.claude/skills/release-notes.md': [
       '---',
       'description: Writes short release notes from the commits since the last tag. Use when the user asks for release notes or a changelog entry.',
       '---',
       '',
       'Write release notes for the changes since the last git tag.',
       'Group them under Added, Changed and Fixed, one line per change.',
       '',
     ].join('\n'),
   
     '.claude/.mcp.json': [
       '{',
       '  "mcpServers": {',
       '    "claude-code-docs": {',
       '      "type": "http",',
       '      "url": "https://code.claude.com/docs/mcp"',
       '    }',
       '  }',
       '}',
       '',
     ].join('\n'),
   };
   
   for (const [rel, text] of Object.entries(files)) {
     const file = path.join(target, ...rel.split('/'));
     mkdirSync(path.dirname(file), { recursive: true });
     writeFileSync(file, text);
   }
   
   console.log(`Created ${target}`);
   console.log('Three things in its Claude Code setup are wrong. Open a terminal there and follow Day 47.');
   

   No peeking: the mistakes are in this file.

   Check it worked

   The script prints Created with the new folder’s path.

   It worked — next step Not yet
2. 02

   Step 2 of 5: Find the broken settings file

   Start Claude Code in the practice folder and read what it reports.

   In order:

   1. You

      You run claude here

   2. File

      Claude Code reads .claude/settings.json

   3. Claude

      A Settings Error dialog opens

      Fix it with Claude, exit, or continue without the file.

   Choose to exit. Run claude doctor in your terminal: it reports invalid settings files without starting a session. Delete the comma after the last ] in .claude/settings.json, then start claude again.

   Check it worked

   No dialog this time, and /hooks lists a SessionStart hook from project settings.

   If it didn’t work

   No Settings Error appears.

   Check you started claude inside acme-broken-setup, not in your project.

   It worked — next step Not yet Back
3. 03

   Step 3 of 5: Find the skill that never loads

   A skill needs its own folder with SKILL.md inside.

   In Claude Code

   You type: › /skills

   – What happens: release-notes is missing, though .claude/skills/release-notes.md exists.

   For macOS, Linux and WSL

   TerminalCopy

   mkdir -p .claude/skills/release-notes
   mv .claude/skills/release-notes.md .claude/skills/release-notes/SKILL.md

   For Windows

   PowerShellCopy

   New-Item -ItemType Directory .claude\skills\release-notes
   Move-Item .claude\skills\release-notes.md .claude\skills\release-notes\SKILL.md

   Check it worked

   Run /skills again. release-notes is listed.

   If it didn’t work

   It still isn’t listed.

   Run /reload-skills.

   It worked — next step Not yet Back
4. 04

   Step 4 of 5: Find the MCP server that never appears

   Project servers belong in .mcp.json at the folder root, not inside .claude.

   In Claude Code

   You type: › /mcp

   – What happens: claude-code-docs isn’t listed: Claude Code never reads .claude/.mcp.json.

   For macOS, Linux and WSL

   TerminalCopy

   mv .claude/.mcp.json .mcp.json

   For Windows

   PowerShellCopy

   Move-Item .claude\.mcp.json .mcp.json

   Exit Claude Code, move the file, start claude again and approve the server.

   Check it worked

   /mcp lists claude-code-docs as connected.

   It worked — next step Not yet Back
5. 05

   Step 5 of 5: Keep the checks for next time

   Ask Claude Code what it loaded before you change any file.

   Is it loaded?

   • /context: everything in this session
   • /hooks, /skills, /mcp: one feature each, with its source

   Is it broken?

   • claude doctor: invalid settings files
   • /doctor: a checkup that asks before fixing
   • claude --safe-mode: your setup switched off, to compare

   Check it worked

   Start claude --safe-mode in the folder. /hooks shows no project hooks, proving the fixes came from your files.

   It worked — finish Not yet Back