claude plugin validate printed Validation passed and exited 0. The directory it was given contained one file, and that file was not an agent. The same bytes, one directory higher, produced a line that named the file and a warning that the file had no front matter.
The difference is the path you pass. On Claude Code 2.1.308 the command help says it validates a plugin or marketplace manifest, or the skills, agents, and commands in a directory. A directory whose last component is the lowercase word agents takes a shorter path. The process reports success, the JSON contents array is empty, and the file is not opened. Pass the plugin root and the same file is listed as an agent.
What was on disk
The binary was the npm-global Claude Code 2.1.308, commit 320f66eb8f83, on Linux x86_64. The run was 16 November 2026. No claude auth login was run. No session was started. --plugin-dir was not used. No model call was made. The directories were new and were not the operator’s Claude config directory.
The file under test was twelve characters and a newline:
not an agent
There was no --- block and no name field. Two parents held a copy of that file.
The first parent was a directory whose basename was exactly agents. The file sat directly in it, as broken.md.
The second parent was a plugin root. It had .claude-plugin/plugin.json with name gauge-plugin, version 1.0.0, a description, and an author object whose name was Probe. The broken file sat at agents/broken.md under that root. A third copy used the same layout without the author object, so the missing-author warning could be separated from the agent warning.
A fourth tree had no plugin.json. It had skills/gauge/SKILL.md with ordinary skill front matter, and the same broken file at agents/broken.md. That tree is the shape the validator calls a skills tree.
The agents directory
The command was claude plugin validate on the directory named agents. Human output was two lines that matter:
Validating components in: agents
✔ Validation passed
The exit code was 0. --json returned success: true, manifest: null, and contents: []. --strict did not change that. The JSON then had strict: true and the same empty contents array, and the exit code was still 0. Strict mode promotes warnings to errors. It cannot promote a warning the walk never produced.
--profile directory on that same path exited 1. The failure string was --profile directory needs a plugin folder. contents was still []. The profile flag is the catalog check described in the help: it fails the process when the plugin directory would refuse a submission, or when that check could not be made. On a path that is only an agents directory, the check cannot be made, and the note says none of the directory’s rules were checked. The agent file is still not named. A CI job that adds --profile directory and points it at agents/ will go red for the wrong reason, and it will still not have read the subagent.
The basename match is exact and case-sensitive. A directory named Agents, capital A, with the same broken file, exited 1. The error was No manifest found in directory, expecting .claude-plugin/marketplace.json or .claude-plugin/plugin.json. That path does not enter the agents shortcut, and it does not parse the markdown as an agent either. It looks for a manifest and stops.
Passing the markdown file itself is a third failure, also not an agent-schema check. claude plugin validate on broken.md exited 1 with Invalid JSON syntax: JSON Parse error: Invalid number. The file is being read as a plugin manifest. A front-matter error never appears.
The plugin root
claude plugin validate on the plugin root, with the author field set, printed Validating plugin manifest and then:
Validating agent: agents/broken.md
⚠ Found 1 warning:
❯ frontmatter: No frontmatter block found.
The exit code was 0. The summary line was Validation passed with warnings. The JSON contents array had one object. Its type was agent. The warning path was frontmatter. The message asked for a YAML block between --- delimiters.
The same invocation also printed plugin-directory findings: README_MISSING and LICENSE_MISSING as problems the catalog would refuse, and ICON_MISSING as a warning. The command then said those checks do not change the result below, and that --profile directory is how you fail on them. That sentence matched the exit code. The catalog findings were present, and the process still exited 0.
--strict on that root exited 1. The summary was Validation failed (--strict treats warnings as errors). With author set, the only component warning on the page was the missing front matter. Strict mode is useful on the plugin root, where the file is opened. It is not useful on the agents directory, where there is no warning to promote.
A plugin root that omitted author added a second warning, on the manifest, and still exited 0 without --strict. Do not read a missing-author warning as evidence that the agent file was skipped. In this run the agent line was printed in both roots. The author warning is a separate manifest note. The plugins reference, fetched the same morning, says a missing author is the sort of thing that produces Validation passed with warnings, and that --strict turns those warnings into failures.
skills and commands are not the same path
The help groups skills, agents, and commands in one sentence. The three directory names do not share the skip.
A directory named skills, containing broken/SKILL.md with the same no-front-matter body, exited 0 and listed the file. contents had one object, type skill, with the frontmatter warning. A directory named commands, containing broken.md with that body, listed type command and the same warning, and also exited 0. A missing front matter is a warning on those paths, so the exit code stays 0 unless you pass --strict. The file is still named. You can see that the walk happened.
Only the lowercase basename agents returned success with an empty contents array while a broken markdown file sat in the directory. A script that treats the three names as one flag will accept a broken subagent and will still report a broken skill.
A skills tree is a plugin root
The tree with skills/gauge/SKILL.md and no plugin.json was accepted as a plugin. Validating that parent printed Validating agent for agents/broken.md and the frontmatter warning. The directory note said the folder holds a skills tree, which Claude Code loads without a manifest, and that anything else in it, including agents/, is validated and loads with it. The exit code was 0, Validation passed with warnings.
That note describes the parent you passed. Validating the agents subdirectory of that same tree returned the empty success again: Validation passed, contents: [], exit 0. The sentence in the note does not make agents/ a valid target for this command. If you are standing in the subdirectory because that is the folder you edited, step up to the parent that holds skills/ or .claude-plugin/ before you trust the exit code.
The plugins reference says the manifest is optional and that Claude Code loads components it finds in the standard layout. It also says to run claude plugin validate against the plugin directory, and it calls that command the authoritative check for a manifest. Both of those sentences were true for the parent in this run. Neither sentence says that a path whose last component is agents skips the files. The help text is the sentence a script is likely to follow, and following it literally is how you get the unread pass.
Verify the file was opened
Pass the plugin root. Do not pass agents/, do not pass Agents/, and do not pass the markdown file.
After the run, look for a contents entry whose type is agent, or for the human line Validating agent. Those are the signs the file was opened. An exit code of 0 and an empty contents array, when the path ends in agents, is the unread case. On the plugin root, an empty contents array can also mean the files that were opened had nothing to report. A valid agent in an earlier probe produced contents: [] and exit 0 from the plugin root, with no Validating agent line. Empty contents is not proof the file was read. The known-bad file is the check. Put a markdown file with no front matter in agents/, validate the plugin root, and require the frontmatter warning. Then put the real file back.
Use --strict on the plugin root if a missing front matter should fail the job. Do not add --strict on the agents directory and treat a still-green exit as a stricter check. It is the same unread pass.
Use --profile directory only when the question is whether the catalog would refuse the submission. On 2.1.308 those findings do not change the component result unless you pass the flag, and the flag on an agents directory fails before it names the file. A missing README is not a substitute for the frontmatter warning, and the frontmatter warning is not a catalog decision.
This run did not start a session, so it does not show whether a later session would spawn the broken file, hide it, or warn at startup. The thing the exit code is being asked to prove, in a script that runs before that session, is whether validate opened the file. On this binary, that proof is the plugin-root report, not the success line from the directory named agents.
Documents read for this check
The help text is claude plugin validate --help from Claude Code 2.1.308. The manifest page is the plugins reference at https://code.claude.com/docs/en/plugins-reference, section “Validate the manifest”, fetched 16 November 2026. The exit-code sentence is the plugin commands reference at https://code.claude.com/docs/en/plugins/cli-reference, which says plugin subcommands exit 0 on success and 1 on failure. Neither page describes the basename shortcut measured here.