docs(claude): clarify .claude/ markdown exception#1223
Merged
John-David Dalton (jdalton) merged 1 commit intomainfrom Apr 17, 2026
Merged
docs(claude): clarify .claude/ markdown exception#1223John-David Dalton (jdalton) merged 1 commit intomainfrom
John-David Dalton (jdalton) merged 1 commit intomainfrom
Conversation
The old policy text read as if every .md under .claude/ was banned, but the Claude harness actually reads files like `SKILL.md`, `agents/*.md`, `commands/*.md`, and `hooks/*/README.md` as its own configuration. We've been checking those in all along. Updates the Documentation Policy section so the stated rule matches what we actually do: harness-config markdown under .claude/agents, .claude/commands, .claude/hooks, .claude/skills is allowed. Ad-hoc analysis/session notes dropped under .claude/ are still disallowed, same as before.
Bill Li (billxinli)
approved these changes
Apr 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Small policy fix to CLAUDE.md.
The old "Documentation Policy" text read as if every
.mdfile under.claude/was forbidden, but the Claude harness actually reads a bunch of them as config (agent definitions, command metadata,SKILL.mdentrypoints, skill references). Those have been checked in all along, and we want them to be — so the stated policy and the checked-in files disagreed.This PR rewrites the section so the rule matches reality:
.claude/agents,.claude/commands,.claude/hooks,.claude/skillsis allowed.claude/are still disallowed, same as beforePure doc change; no code touched.
Test plan
grepof .claude/*.md files matches the carve-out described in the new textNote
Low Risk
Documentation-only change with no runtime/code impact; risk is limited to potential policy interpretation changes.
Overview
Updates
CLAUDE.md’s Documentation Policy to explicitly allow markdown files under.claude/agents/,.claude/commands/,.claude/hooks/, and.claude/skills/as Claude harness configuration, while continuing to forbid ad-hoc analysis/session notes in.claude/and keeping the rest of the “no doc sprawl” rule unchanged.Reviewed by Cursor Bugbot for commit 276a40c. Configure here.