Upstream spec

Upstream spec

What the published Claude Code and Agent Skills documentation describes, and how much of it claudelint reads.

Verified against Claude Code v2.1.270; documentation pages carried markers up to v2.1.269.

The claudelint column answers one question: does anything in the linter read this? A no is not a bug on its own — it means no rule needs the field yet, and the reason says which rule or phase would change that. A — means claudelint has no opinion about the section at all.

This page is generated from internal/upstream/digest.json and internal/upstream/acknowledged.json. A weekly job re-extracts the digest from upstream, so a row here is what the documentation said the last time anyone looked.

Tools

The built-in tools a skill, command, or agent may name in allowed-tools, disallowed-tools, or tools.

Tool	claudelint	Reason
Agent	yes	—
Artifact	yes	—
AskUserQuestion	yes	—
Bash	yes	—
CronCreate	yes	—
CronDelete	yes	—
CronList	yes	—
Edit	yes	—
EndConversation	yes	—
EnterPlanMode	yes	—
EnterWorktree	yes	—
ExitPlanMode	yes	—
ExitWorktree	yes	—
Glob	yes	—
Grep	yes	—
LSP	yes	—
ListAgents	yes	—
ListMcpResourcesTool	yes	—
Monitor	yes	—
NotebookEdit	yes	—
PowerShell	yes	—
PushNotification	yes	—
Read	yes	—
ReadMcpResourceTool	yes	—
RemoteTrigger	yes	—
ReportFindings	yes	—
ScheduleWakeup	yes	—
SendFeedback	yes	—
SendMessage	yes	—
SendUserFile	yes	—
ShareOnboardingGuide	yes	—
Skill	yes	—
TaskCreate	yes	—
TaskGet	yes	—
TaskList	yes	—
TaskOutput	yes	—
TaskStop	yes	—
TaskUpdate	yes	—
TodoWrite	yes	—
ToolSearch	yes	—
WaitForMcpServers	yes	—
WebFetch	yes	—
WebSearch	yes	—
Workflow	yes	—
Write	yes	—

Tools that upstream renamed or removed are no longer in the table above. claudelint still recognizes them, and reports them with their replacement rather than as typos — see Deprecated and removed tools.

Hooks

Hook events, handler types, and the fields a handler entry may carry.

Events

Event	claudelint	Reason
ConfigChange	yes	—
CwdChanged	yes	—
DirectoryAdded	yes	—
Elicitation	yes	—
ElicitationResult	yes	—
FileChanged	yes	—
InstructionsLoaded	yes	—
MessageDisplay	yes	—
Notification	yes	—
PermissionDenied	yes	—
PermissionRequest	yes	—
PostCompact	yes	—
PostModelSwitch	yes	—
PostToolBatch	yes	—
PostToolUse	yes	—
PostToolUseFailure	yes	—
PreCompact	yes	—
PreModelSwitch	yes	—
PreToolUse	yes	—
SessionEnd	yes	—
SessionStart	yes	—
Setup	yes	—
Stop	yes	—
StopFailure	yes	—
SubagentStart	yes	—
SubagentStop	yes	—
TaskCompleted	yes	—
TaskCreated	yes	—
TeammateIdle	yes	—
UserPromptExpansion	yes	—
UserPromptSubmit	yes	—
WorktreeCreate	yes	—
WorktreeRemove	yes	—

Handler types

Type	claudelint	Reason
agent	yes	—
command	yes	—
http	yes	—
mcp_tool	yes	—
prompt	yes	—

Handler fields

Grouped as the documentation groups them: common fields apply to every handler, the rest to one type.

agent:

Field	Required	Type	claudelint	Reason
model	no	—	no	prompt and agent handler field; agents/model-policy covers agent frontmatter, not hook handlers (OQ4).
prompt	yes	—	yes	—

command:

Field	Required	Type	claudelint	Reason
args	no	—	yes	—
async	no	—	yes	—
asyncRewake	no	—	no	command handler field paired with async; hooks/async-rewake has no rule yet (OQ4).
command	yes	—	yes	—
shell	no	—	yes	—

common:

Field	Required	Type	claudelint	Reason
if	no	—	no	common conditional field; no rule evaluates hook conditions (OQ4).
once	no	—	no	common field; no rule reads it (OQ4).
statusMessage	no	—	no	common presentation field; no rule reads it (OQ4).
timeout	no	—	yes	—
type	yes	—	yes	—

http:

Field	Required	Type	claudelint	Reason
allowedEnvVars	no	—	no	http handler field; no rule reads it. A hooks/http-env-allowlist rule would, and gets its own IMPL (OQ4).
headers	no	—	no	http handler field; the secret-in-header check that would read it is security rule territory, not yet written (OQ4).
url	yes	—	yes	—

mcp_tool:

Field	Required	Type	claudelint	Reason
input	no	—	no	mcp_tool handler field; no rule validates the tool input shape (OQ4).
server	yes	—	yes	—
tool	yes	—	yes	—

prompt:

Field	Required	Type	claudelint	Reason
model	no	—	no	prompt and agent handler field; agents/model-policy covers agent frontmatter, not hook handlers (OQ4).
prompt	yes	—	yes	—

Timeout defaults

Seconds applied when a handler declares no timeout.

By type	Seconds
agent	60
command	600
http	600
mcp_tool	600
prompt	30

By event	Seconds
MessageDisplay	10
PostModelSwitch	30
PreModelSwitch	30
UserPromptSubmit	30

Skills and commands

Skills and commands share one documented frontmatter table. claudelint splits it across two parsers, so a field is marked read when either reads it.

Field	Required	Type	claudelint	Reason
agent	no	—	yes	—
allowed-tools	no	—	yes	—
argument-hint	no	—	yes	—
arguments	no	—	no	not parsed; no rule consumes it. A skills/arguments-valid rule would, and gets its own IMPL (OQ4).
background	no	—	no	not parsed; no rule consumes it (OQ4).
compatibility	no	—	no	not parsed; portable.limits records its 500-character cap for a future skills/portable-fields rule (OQ4).
context	no	—	yes	—
description	recommended	—	yes	—
disable-model-invocation	no	—	yes	—
disallowed-tools	no	—	yes	—
effort	no	—	no	not parsed on skills; agents/field-enums covers the agent spelling. Parse it when a skill rule needs it (OQ4).
hooks	no	—	no	not parsed on skills; hook contents are the hook rule package’s job (DESIGN-0005 non-goal).
license	no	—	no	not parsed; portable.allowed_fields records it for a future skills/portable-fields rule (OQ4).
metadata	no	—	no	free-form metadata; nothing to validate (OQ4).
model	no	—	yes	—
name	no	—	yes	—
paths	no	—	no	not parsed; no rule consumes it (IMPL-0004 out of scope, OQ4).
shell	no	—	no	not parsed; no rule consumes it (OQ4).
user-invocable	no	—	yes	—
when_to_use	no	—	yes	—

Documented string substitutions: $ARGUMENTS, $ARGUMENTS[N], $N, $name, ${CLAUDE_EFFORT}, ${CLAUDE_PLUGIN_DATA}, ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PROJECT_DIR}, ${CLAUDE_SESSION_ID}, ${CLAUDE_SKILL_DIR}.

Usable outside Claude Code: allowed-tools, compatibility, description, license, metadata, name.

Agents

Subagent frontmatter and the values its enum fields accept.

Field	Required	Type	claudelint	Reason
background	no	—	yes	—
color	no	—	yes	—
description	yes	—	yes	—
disallowedTools	no	—	yes	—
effort	no	—	yes	—
experimental	no	—	no	documented as experimental; DESIGN-0006 records field names only for experimental surfaces. Parse it when a rule needs it (IMPL-0005 OQ4).
hooks	no	—	yes	—
initialPrompt	no	—	yes	—
isolation	no	—	yes	—
maxTurns	no	—	yes	—
mcpServers	no	—	yes	—
memory	no	—	yes	—
model	no	—	yes	—
name	yes	—	yes	—
permissionMode	no	—	yes	—
skills	no	—	yes	—
tools	no	—	yes	—

Enums

color:

Value	claudelint	Reason
blue	yes	—
cyan	yes	—
green	yes	—
orange	yes	—
pink	yes	—
purple	yes	—
red	yes	—
yellow	yes	—

effort:

Value	claudelint	Reason
high	yes	—
low	yes	—
max	yes	—
medium	yes	—
xhigh	yes	—

isolation:

Value	claudelint	Reason
HEAD	no	not a value: the docs describe worktree isolation in prose that mentions the HEAD commit, and the extractor takes every code span in the cell. agents/field-enums checks isolation directly against “worktree”.
worktree	yes	—

memory:

Value	claudelint	Reason
local	yes	—
project	yes	—
user	yes	—

model:

Value	claudelint	Reason
claude-opus-5	no	an example full model ID in the description cell, not an alias. artifact.IsValidModelRef already accepts any claude-* ID, so agents/field-enums passes it.
fable	yes	—
haiku	yes	—
inherit	yes	—
opus	yes	—
sonnet	yes	—

permissionMode:

Value	claudelint	Reason
acceptEdits	yes	—
auto	yes	—
bypassPermissions	yes	—
default	yes	—
dontAsk	yes	—
manual	yes	—
plan	yes	—

Plugins

The plugin manifest and where a plugin’s components live.

Field	Required	Type	claudelint	Reason
$schema	no	string	no	editor metadata, not a plugin property; plugin/manifest-fields has nothing to check on it.
agents	no	string|array	yes	—
author	no	object	no	metadata field; no rule consumes it (OQ4). plugin/manifest-fields would parse it when one does.
channels	no	array	no	experimental surface; field name recorded only, per DESIGN-0006 non-goals.
commands	no	string|array	yes	—
defaultEnabled	no	boolean	no	metadata field; no rule consumes it (OQ4).
dependencies	no	array	no	component field; a plugin/dependencies-resolvable rule would read it and gets its own IMPL (OQ4).
description	no	string	yes	—
displayName	no	string	no	metadata field; no rule consumes it (OQ4).
experimental.evals	no	string|array	no	experimental surface; field name recorded only, per DESIGN-0006 non-goals.
experimental.monitors	no	string|array	no	experimental surface; field name recorded only, per DESIGN-0006 non-goals.
experimental.themes	no	string|array	no	experimental surface; field name recorded only, per DESIGN-0006 non-goals.
homepage	no	string	no	metadata field; no rule consumes it (OQ4).
hooks	no	string|array|object	no	component path field; the hook rules lint hooks/hooks.json directly, so the manifest pointer needs no parse (OQ4).
keywords	no	array	no	metadata field; no rule consumes it (OQ4).
license	no	string	no	metadata field; no rule consumes it (OQ4).
lspServers	no	string|array|object	no	experimental surface; field name recorded only, per DESIGN-0006 non-goals.
mcpServers	no	string|array|object	no	component path field; the mcp rules lint .mcp.json and plugin-embedded servers directly (OQ4).
metadata	no	object	no	free-form metadata; nothing to validate (OQ4).
name	yes	string	yes	—
outputStyles	no	string|array	no	component path field; no rule consumes it (OQ4).
repository	no	string	no	metadata field; no rule consumes it (OQ4).
skills	no	string|array	yes	—
userConfig	no	object	no	component field; a plugin/user-config-valid rule would read it and gets its own IMPL (OQ4).
version	no	string	yes	—
workflows	no	string|array	no	component path field; no rule consumes it (OQ4).

Component locations

Component	Path
agents	agents/
commands	commands/
executables	bin/
hooks	hooks/hooks.json
lsp servers	.lsp.json
manifest	.claude-plugin/plugin.json
mcp servers	.mcp.json
monitors	monitors/monitors.json
output styles	output-styles/
settings	settings.json
skills	skills/
themes	themes/
workflows	workflows/

Marketplaces

The marketplace manifest, its plugin entries, and the source shapes a plugin entry may declare.

Field	Required	Type	claudelint	Reason
$schema	no	string	—	—
allowCrossMarketplaceDependenciesOn	no	array	—	—
description	no	string	—	—
metadata.pluginRoot	no	string	—	—
name	yes	string	—	—
owner	yes	object	—	—
plugins	yes	array	—	—
renames	no	object	—	—
version	no	string	—	—

Owner

Field	Required	Type	claudelint	Reason
email	no	string	—	—
name	yes	string	—	—
url	no	string	—	—

Plugin entries

Field	Required	Type	claudelint	Reason
author	no	object	—	—
category	no	string	—	—
defaultEnabled	no	boolean	—	—
description	no	string	—	—
displayName	no	string	—	—
homepage	no	string	—	—
keywords	no	array	—	—
license	no	string	—	—
metadata	no	object	—	—
name	yes	string	—	—
relevance	no	object	—	—
repository	no	string	—	—
source	yes	string|object	—	—
strict	no	boolean	—	—
tags	no	array	—	—
version	no	string	—	—

Source kinds

Kind	Required	Optional	claudelint
archive	url	sha256	yes
command	command	mode, timeout	yes
git-subdir	path, url	ref, sha	yes
github	repo	ref, sha	yes
npm	package	registry, version	yes
url	url	ref, sha	yes

Reserved names

Reserved for official Anthropic use. A manifest shipping one stops loading for every user.

Name	claudelint	Reason
agent-skills	yes	—
anthropic-agent-skills	yes	—
anthropic-marketplace	yes	—
anthropic-plugins	yes	—
claude-code-marketplace	yes	—
claude-code-plugins	yes	—
claude-community	yes	—
claude-for-financial-services	yes	—
claude-for-legal	yes	—
claude-plugins-community	yes	—
claude-plugins-official	yes	—
claude-tag-plugins	yes	—
financial-services-plugins	yes	—
first-party-plugins	yes	—
healthcare	yes	—
knowledge-work-plugins	yes	—
life-sciences	yes	—

MCP servers

The shape of one entry in .mcp.json or a plugin’s mcp.servers.

Field	Required	Type	claudelint	Reason
args	—	—	—	—
authServerMetadataUrl	—	—	—	—
callbackPort	—	—	—	—
clientId	—	—	—	—
command	—	—	—	—
env	—	—	—	—
headers	—	—	—	—
headersHelper	—	—	—	—
oauth	—	—	—	—
scopes	—	—	—	—
type	—	—	—	—
url	—	—	—	—
xaa	—	—	—	—

Transports

Transport	claudelint	Reason
http	yes	—
sse	yes	—
stdio	yes	—
ws	yes	—

Portable skills

The Agent Skills specification, which is narrower than the Claude Code superset above. claudelint does not enforce it yet; it is recorded so a future portability rule has something to read.

Name pattern: ^[a-z0-9-]+$

Allowed fields: allowed-tools, compatibility, description, license, metadata, name

Allowed by Anthropic’s own validator: allowed-tools, compatibility, description, license, metadata, name

Limits	Seconds
compatibility	500
description	1024
name	64

Documentation versus SchemaStore

Where the published documentation and the SchemaStore JSON schemas describe different things. The documentation wins: these are recorded, not enforced.

Topic	Source	Documented only	Source only
hooks.events	schemastore.plugin	DirectoryAdded, MessageDisplay, PostModelSwitch, PreModelSwitch	—
hooks.events	schemastore.settings	PostModelSwitch, PreModelSwitch	—
marketplace.sources	schemastore.marketplace	archive, command	—
plugins.manifest_fields	schemastore.plugin	defaultEnabled, displayName, experimental.evals, experimental.monitors, experimental.themes, metadata, workflows	monitors, settings, themes