handbooksCommon mistakes
The specific, verifiable errors people make with Claude Code customization, plus two terms that sound official but are not real parts of any spec.
- Most mistakes on this page come from treating one tool like another.
CLAUDE.mdlike a hook, a Project like a skill, a fenced example like something that syncs itself. - Two terms circulate that are not real: "traits" and "modules." Neither is part of any official spec.
- This page is deliberately negative. It exists to catch the things a first read of the other pages will not.
Configuration mistakes
CLAUDE.md is context Claude reads, not a rule it is forced to obey. A rule that must never be broken belongs in a hook instead. See the exit-code table there for exactly how a hook enforces it.
Files over 200 lines consume more context and measurably dilute how closely Claude follows any single instruction in them. If a section has grown into numbered steps, it has grown into a skill. Move it.
.claude/settings.local.json is auto-gitignored, so nothing in it reaches your teammates. Shared permissions, hooks, and MCP servers belong in the committed .claude/settings.json instead.
It does not. A skill in your repo, a skill uploaded to claude.ai, and a skill uploaded to the API are three separate uploads. Keep the source in git as the one canonical copy, and treat each surface as a deploy target.
Claude Code understands extra frontmatter fields, model, effort, disable-model-invocation, and others, beyond the six the open spec defines. A skill using them may error if it is uploaded somewhere that only expects the spec's six fields. Stick to the six if the skill needs to travel.
A skill runs code. Vet one before installing it from someone you do not know, the same way you would vet a new dependency, and turn on skill content scanning at the organization level if it is available on your plan.
Two terms that are not real
There is no traits: field in the Agent Skills spec or in Claude Code. The confusion usually comes from subagents being informally described as having a "persona," or from a third-party skill author inventing their own traits: key as a personal convention. The actual, supported way to control tone and persona in Claude Code is Output Styles and subagent prompts.
The three canonical, recognized folders inside a skill are scripts/, references/, and assets/. See Skills. You can create other folders, but nothing looks for one named modules/ specifically.
Where to check when in doubt
If a specific detail on any page here, a settings key, a hook event name, a version number, matters for something you are about to ship, verify it against Anthropic's own current documentation first. This reference is checked against the source it cites (see each page's Last reviewed line), but Claude's customization surface changes quickly, and a detail correct on the date reviewed can drift.