fabrico-creating-prompts

name	fabrico-creating-prompts
description	Create custom slash commands (.claude/commands/*.md) for Claude Code. Provides templates, guidelines, and a structured process for building command files that trigger specific workflows, optionally delegating to the right subagent. Use when creating, reviewing, or updating .claude/commands/*.md files.

Creating Prompts

Creates well-structured custom slash commands for Claude Code. Enforces a consistent pattern across all commands and ensures clear separation between command files, subagent definitions, and skills.

Core Design Principles

A slash command (`.claude/commands/*.md`) defines WHAT workflow to execute. It must NOT define WHO the agent is.

• Command = workflow trigger, workflow steps, tool configuration, expected outcome (.claude/commands/*.md files)
• Subagent = behavior, personality, responsibilities, and problem-solving approach (.claude/agents/*.md files)
• Skills = reusable domain knowledge, step-by-step processes, templates (.claude/skills/<name>/SKILL.md files)

A command routes work to a subagent (via the Task tool) and configures the workflow context. The subagent's role, personality, and behavioral guidelines are defined exclusively in the subagent file. The command must never redefine, override, or contradict the subagent's identity.

A slash command is a **workflow trigger**. It must:

• Optionally DELEGATE to a specific subagent via the Task tool (subagent_type: <subagent-name>) when the workflow has a clear owner
• Describe the workflow steps Claude should follow for this specific task
• Define the expected outcome of the workflow
• Optionally restrict tools via the allowed-tools frontmatter field
• Optionally pick a model via the model frontmatter field (otherwise the command inherits the session model)

A command must NOT:

• Define or alter a subagent's personality, tone, or behavioral traits
• Duplicate instructions that belong in skills
• Duplicate coding standards or guidelines that belong in CLAUDE.md memory files
• Contain generic instructions that are not specific to the workflow

All structured content inside the command body MUST use XML-like tags for explicit structure. This ensures reliable parsing across all model tiers.

Use Markdown only for inline formatting (bold, code blocks, tables, lists) within XML sections.

A command should only describe what is necessary for the specific workflow it triggers. Delegate domain knowledge to skills, coding standards to `CLAUDE.md` memory, and behavioral guidelines to subagents.

Creation Process

Use the checklist below and track your progress (the TodoWrite tool is useful here):

Creation progress:
- [ ] Step 1: Define the command's purpose
- [ ] Step 2: Decide whether to delegate to a subagent (and pick a model)
- [ ] Step 3: Determine tool requirements
- [ ] Step 4: Identify required skills
- [ ] Step 5: Design the workflow steps
- [ ] Step 6: Define output expectations
- [ ] Step 7: Assemble the command file using the template
- [ ] Step 8: Validate the command file

Step 1: Define the command's purpose

Answer these questions before writing anything:

• What specific workflow does this command trigger? (e.g., research a task, implement a feature, run e2e tests)
• What is the expected outcome? (e.g., a research document, implemented code, test suite)
• What inputs does the workflow require? (e.g., Jira ID, plan file, feature description) — these arrive via $ARGUMENTS (or $1, $2, …)
• Does this command extend or depend on another command?
• What makes this workflow distinct from existing commands?

Step 2: Decide whether to delegate to a subagent (and pick a model)

Decide if the workflow has a clear specialist owner:

• Review existing subagents in .claude/agents/ to find one whose role aligns with the workflow
• If a subagent fits, the command should delegate to it via the Task tool (subagent_type: <subagent-name>) — add the delegation directive as the first line of the body. The command should not redefine the subagent's capabilities.
• If the workflow is generic and needs no specialist, omit delegation and write the steps for the main thread to follow.
• Optionally set the model: frontmatter field (opus, sonnet, or haiku) when the workflow's complexity warrants a specific tier; otherwise omit it and inherit the session model.

Step 3: Determine tool requirements

Decide if the command should restrict the tools Claude may use:

• By default, a command inherits the full Claude Code toolset (including all configured MCP servers). Omit allowed-tools unless you need to restrict.
• If the workflow should be limited to a specific set (e.g., a read-only review command), list them in the allowed-tools frontmatter field (e.g., Read, Grep, Glob, Bash).
• To allow a specific MCP server's tools, reference them by their mcp__<server>__* names (e.g., mcp__context7__*, mcp__figma__*, mcp__playwright__*).

Step 4: Identify required skills

Determine which skills the workflow depends on:

• Review existing skills in .claude/skills/ to find relevant ones
• Each referenced skill provides domain knowledge the workflow relies on; reference it so Claude loads it before starting the workflow
• List skills with a brief explanation of why they are needed for THIS workflow
• Do not reference skills that are not directly used in the workflow steps

Step 5: Design the workflow steps

Outline the workflow as a numbered sequence:

• Each step should be a clear, actionable instruction
• Steps should reference skills and tools where appropriate
• Include decision points and branching logic if the workflow is not purely linear
• Include handoffs to other subagents (via the Task tool) or follow-up slash commands if the workflow spans multiple specializations
• Keep steps focused on WHAT to do, not HOW to think about it (the subagent's personality handles the how)

Step 6: Define output expectations

Specify the expected deliverables of the workflow:

• File name conventions and output locations
• Document structure or template to follow (reference skill templates where applicable)
• Summary format if the workflow produces a report
• Success criteria — how to know the workflow is complete
• This step is optional if the workflow outcome is self-evident (e.g., implemented code)

Step 7: Assemble the command file using the template

Use the ./prompt.template.md template to assemble the final command file. Place the file in .claude/commands/ with a descriptive kebab-case filename and the fabrico- prefix (e.g., fabrico-research.md, fabrico-implement-ui.md). The command is then invoked with its slash form (e.g., /fabrico-research, /fabrico-implement-ui). Commands can also be scoped globally by placing them in ~/.claude/commands/.

Step 8: Validate the command file

Verify the command file against this checklist:

• YAML frontmatter is valid and parseable
• description field is present and concise (shown in the / menu)
• argument-hint field (if present) describes what the user passes
• If the command delegates, the delegation directive names an existing subagent in .claude/agents/ and uses the Task tool (subagent_type: <subagent-name>)
• allowed-tools field (if present) lists only the tools the workflow needs
• model field (if present) is one of opus, sonnet, haiku
• All skills referenced in Required Skills section exist in .claude/skills/
• XML-like tags are properly opened and closed
• No subagent personality or behavioral instructions are embedded (those belong in .claude/agents/*.md)
• No coding standards or guidelines are embedded (those belong in CLAUDE.md)
• No skill content is duplicated (reference skills, don't copy them)
• Workflow steps are clear, sequential, and actionable
• The command is distinct from existing commands and does not duplicate their workflows
• If the command extends another command, the dependency is explicitly stated

Command File Structure Reference

Frontmatter Fields

Field	Required	Description
description	Yes	A short description of what the command does. Shown in the / menu.
argument-hint	No	Hint text shown in the / menu to guide the user on what to provide (e.g., [Jira ID or task description]).
allowed-tools	No	A comma-separated list of tools the command is permitted to use. If omitted, the command inherits the full Claude Code toolset (including MCP servers). Reference MCP tools as mcp__<server>__*.
model	No	The model used when running the command (opus, sonnet, or haiku). If omitted, the command inherits the current session model.

Delegation, not an agent: field. Claude Code commands do not have an agent frontmatter field. To route a workflow to a specialist, put a delegation directive at the top of the command body that launches the subagent with the Task tool (subagent_type: <subagent-name>). See the template for the exact wording.

Body Sections

Section	Required	Purpose
Delegation directive	No	First line of the body when the workflow has a subagent owner: launch it via the Task tool.
Goal statement	Yes	1-2 paragraphs describing what the command accomplishes and the expected outcome.
<prerequisites>	No	Dependencies on other commands or files that must be completed first.
<input-requirements>	No	Describes what context or inputs the workflow needs to start (often arriving via $ARGUMENTS).
Required Skills	Yes	Skills to load before starting the workflow, with brief rationale for each.
Workflow	Yes	Numbered steps defining the workflow sequence.
<output-specification>	No	File naming, document structure, summary format, or success criteria.
<handoff>	No	Follow-up subagent (via the Task tool) or slash command to run at the end of the workflow.
<constraints>	No	Workflow-specific limitations, anti-patterns, or scope boundaries.

XML Syntax Guidelines

All body content in the command file must use XML-like tags for structure. Rules:

1. Every section uses a matching opening and closing tag: <section-name> ... </section-name>
2. Tags use lowercase-kebab-case naming
3. Nesting is allowed for sub-sections
4. Markdown formatting (bold, lists, tables, code blocks) is used inside XML tags for content
5. Avoid XML attributes for structural content — use nested tags or Markdown content instead. Exception: identifier attributes (e.g., <tool name="...">) are acceptable when they improve readability.

Arguments Reference

Slash commands receive the user's input through argument placeholders that Claude Code substitutes at runtime. Use them to make commands operate on dynamic input:

Placeholder	Description
$ARGUMENTS	The full argument string the user passed after the slash command (e.g., everything after /fabrico-research).
$1, $2, $3, …	Individual positional arguments, split on whitespace. Use these when the command expects multiple discrete inputs.

Place a brief line like The request: $ARGUMENTS near the top of the body when the command clearly operates on user input. Use the argument-hint frontmatter field to tell the user what to provide.

Note on dynamic editor context. Unlike VS Code prompt variables, Claude Code commands do not resolve ${file}/${selection}/${workspaceFolder}-style editor variables. To reference workspace files, name the path directly in the workflow (Claude reads it with the Read tool), or have the user pass it as an argument. You can also embed shell output by prefixing a body line with ! to run a Bash command and inline its result, or reference a file's contents with @path/to/file.

Connected Skills

• fabrico-creating-agents - to understand subagent patterns and ensure commands don't overlap with subagent responsibilities
• fabrico-creating-skills - to ensure this skill's own structure follows the canonical skill creation requirements
• fabrico-technical-context-discovering - to understand existing command patterns and project conventions before creating a new one
• fabrico-codebase-analysing - to analyze existing commands and identify patterns to follow
• fabrico-creating-instructions - to understand when coding standards belong in CLAUDE.md memory files rather than command definitions