AnthropicClaude Certified Architect – Foundations2026-103.2 Create and configure custom slash commands and skills
Author SKILL.md and keep command files working
Completed by the knowledge check
Learning objective
Author SKILL.md with frontmatter and recognize that .claude/commands/ files still work and create equivalent slash commands.
Core idea
A Claude Code skill has two layers: metadata that configures invocation and execution, and Markdown instructions that describe the work. Put the metadata in YAML frontmatter at the beginning of SKILL.md. Put the procedure after the closing frontmatter marker. A well-written procedure cannot compensate for metadata that Claude Code never parses.
Custom command files remain supported. .claude/commands/team-review.md and .claude/skills/team-review/SKILL.md both create /team-review. You do not need to replace a working single-file command just to keep its slash invocation. Anthropic recommends skills for new workflows because they support accompanying files and skill-specific capabilities. Keep one authoritative procedure for each invocation.
This lesson covers the file interface. The scope decision is in 3.2.1; argument handling, forked execution, and tool permissions are in 3.2.3 through 3.2.5.
How it works
Put frontmatter at the first line
Claude Code recognizes frontmatter only when the opening --- is the first line of the file. A heading, comment, or introductory sentence before it makes the markers part of the skill’s content instead. If the YAML between the markers does not parse, the skill can still load with no fields set. Loading is therefore weaker evidence than observing the intended configuration.
A minimal project skill at .claude/skills/team-review/SKILL.md can look like this:
---
name: team-review
description: Review a service change against the team's checklist.
argument-hint: "[change-scope]"
disable-model-invocation: true
---
Review $ARGUMENTS against the team's service-change checklist.
If the change scope is missing, ask for it before reviewing.
Report each finding with its file, evidence, and recommended fix.The frontmatter describes the saved workflow. The body gives Claude an actionable assignment. The input placeholder belongs in the body, where Claude Code substitutes invocation arguments; the hint only communicates the expected input. See 3.2.3 for that distinction.
name is optional and defaults to the directory name for a skill. Keeping the directory and explicit name identical makes the invocation easier to locate. description is recommended: it states what the skill does and when it applies. If omitted, Claude Code uses the first non-empty line of the Markdown content. That fallback is not a reason to omit an intentionally written description.
Recognize the configuration responsibilities
The fields this unit depends on serve different responsibilities:
| Field | Responsibility | Lesson that owns the detail |
|---|---|---|
name | Identify the command shown in the slash menu | 3.2.2 |
description | Describe the work and when Claude should apply it | 3.2.2 |
argument-hint | Display expected invocation arguments | 3.2.3 |
context: fork | Run the skill as an isolated subagent task | 3.2.4 |
allowed-tools | Pre-approve listed tools for the invoking turn | 3.2.5 |
disallowed-tools | Remove listed tools while the skill is active | 3.2.5 |
Claude Code accepts all the fields in its frontmatter reference, but claude.ai skill uploads, the Skills API, and packaging with package_skill.py accept only name, description, license, compatibility, metadata, and allowed-tools. Other fields, such as argument-hint, context, or disable-model-invocation, cause packaging or upload to fail with a hard unexpected-key error. This boundary also applies when you upload a personal skill to your claude.ai account for Cowork or cloud sessions.
Two additional fields control who can invoke the workflow. disable-model-invocation: true prevents Claude from loading it automatically, while leaving direct user invocation available. user-invocable: false hides it from the slash menu and prevents direct /name invocation while allowing Claude to use it. These fields are not synonyms.
For a review that a developer should explicitly request, the sample uses disable-model-invocation: true. For reference knowledge that Claude should apply when relevant, user-invocable: false can fit better. Neither setting validates the body or turns its prose into an enforced policy. See 3.2.6 for the loading decision.
Keep command compatibility precise
A command file takes its invocation name from the filename without the extension. .claude/commands/team-review.md therefore creates /team-review. Claude Code documents custom commands as merged into skills and explicitly preserves existing command files.
Command files accept the same frontmatter fields except name and paths. Do not copy a skill’s name into a command file and expect it to rename the invocation. Rename the command file when that is the intended change. Likewise, do not assume every skill field is portable merely because both formats accept frontmatter.
A skill with the same name as a command file takes precedence. During migration, leaving both files present does not create two interchangeable choices in the slash menu: the skill wins. Move the intended instructions into the skill and avoid letting the command file become a misleading second source of truth.
Use supporting files intentionally
A skill directory can contain reference material, examples, and scripts beside SKILL.md. Link relevant supporting files from the skill’s instructions and say when Claude should read them. The purpose is to keep the main assignment clear while making detailed evidence available for the task that needs it.
Supporting material is not automatically equivalent to putting every line in the skill body. The skills documentation recommends keeping SKILL.md under 500 lines and moving detailed reference material to separate files. That is an authoring recommendation, not a hard acceptance limit. A concise body should still explain the task, evidence to consult, and result to return.
Key distinctions and trade-offs
Metadata versus instructions: Frontmatter controls documented behavior. The body tells Claude what outcome to produce. A field name mentioned in prose does not set that field.
Single file versus directory: An existing command file can keep serving a contained saved procedure. Prefer a directory-based skill for new workflows, following Anthropic’s recommendation; it gives the procedure room for supporting assets. Both can expose the same slash invocation.
User-only versus model-only invocation: disable-model-invocation: true and user-invocable: false control different actors. Choose based on who should initiate the work, not on whether the workflow is important.
Moving to a skill can improve organization, but format migration is not itself a correctness improvement. The gain comes from a clearer contract, useful supporting material, and deliberate invocation settings.
Architecture / decision scenario
A code-generation team already commits .claude/commands/team-review.md. Its checklist grows to include separate service and storage references. The team decides to use .claude/skills/team-review/SKILL.md and place the detailed checklists beside it.
The author puts YAML at the file’s first line, writes a description, keeps the name team-review, and links the supporting checklists from the body. She sets disable-model-invocation: true because the team wants developers to initiate this review explicitly. The visible invocation remains /team-review.
A teammate initially adds a heading before the opening marker. The file still looks readable, but Claude Code treats the supposed frontmatter as content. The fix is to restore the marker to the first line and verify the intended invocation behavior. The team also removes the obsolete competing command representation from its maintained workflow rather than assuming both files will run.
Common exam traps
- Treating
.claude/commands/files as unsupported. - Putting a heading before the opening frontmatter marker.
- Assuming a skill that loads must have valid parsed frontmatter.
- Using command-file
namefrontmatter to rename its slash invocation. - Confusing
disable-model-invocationwithuser-invocable. - Maintaining a skill and command with the same name as two independent selectable procedures.
What to remember
Start SKILL.md with parseable YAML, then write the task in Markdown. Existing command files keep their slash invocations; skills add a directory for supporting material. Choose one authoritative representation and assign each field its documented responsibility.
Knowledge check
A skill sets disable-model-invocation: true and worked as intended. A teammate then adds a # Team review heading above the opening ---, leaving the YAML itself unchanged. The skill still loads, but Claude now starts it on its own. What explains this?
--- follows a heading, so the block becomes skill content--- is the file’s first line; otherwise the markers and fields become part of the skill’s text and configure nothing. The YAML did not change, so this is not a parse failure, and restating a field in prose never sets it. A skill that loads is therefore weak evidence that its configuration applied.A team keeps its single-file command at .claude/commands/deploy-check.md and wants developers to invoke it as /release-check. It does not want to convert the command to a skill. What change achieves this?
name: release-check to the command file’s frontmatter.claude/commands/release-check.mdrelease-check the first non-empty line of the command bodyname and paths , so a name field does not rename the command. The first non-empty line is only the fallback for a missing description .A team adds a release skill that tags and publishes a build. A developer must decide when it runs; Claude must never start it because a conversation mentions releases. Developers should still be able to type /release. Which frontmatter setting fits?
user-invocable: falsecontext: forkargument-hint: "[release-version]"disable-model-invocation: truedisable-model-invocation: true stops Claude from loading the skill on its own while leaving direct /release invocation available. user-invocable: false does the opposite — it hides the skill from the slash menu and leaves Claude able to invoke it. Forking changes where the skill runs, and a hint only shows expected input.A team has moved its review procedure to .claude/skills/team-review/SKILL.md but left the old .claude/commands/team-review.md in place. A developer adds a new check to the command file. When anyone runs /team-review, the new check never appears. Why?
name: team-review to register its invocationReferences
- Anthropic, Extend Claude with skills
- Anthropic, Commands reference