企业官网建设流程全解析

• AI 插件
• 开发工具
• 插件系统

本文基于plugins/plugin-dev插件开发工具包中的 command-development 技能文档（SKILL.md）编写，系统讲解 Claude Code 中 Slash 命令（斜杠命令）的完整开发流程。你将掌握命令的文件格式、YAML frontmatter 配置、$ARGUMENTS/位置参数、@文件引用、!Bash 执行、命令组织与命名空间，以及专属于插件的${CLAUDE_PLUGIN_ROOT}变量与组件集成方案，最终能够编写出可复用、可分发、带输入校验的高质量命令。

Claude Code 的 Slash 命令本质上是"以 Markdown 文件形式存在、由 Claude 在交互会话中执行"的高频提示词模板。理解命令结构、frontmatter 选项与动态特性，是打造强大可复用工作流的基础。本指南以官方插件开发工具包（plugin-dev）中 command-development 技能为骨架，并结合其参考文档与完整示例（simple-commands.md、plugin-commands.md）逐层深入。

格式说明：.claude/commands/目录属于传统（legacy）格式。新技能建议采用.claude/skills/<name>/SKILL.md目录格式，两者加载方式完全一致，区别仅在于文件布局。详见 skill-development 技能。

命令基础：写给 Agent 的指令

什么是 Slash 命令

Slash 命令是一个包含提示词的 Markdown 文件，用户通过/command-name触发，Claude 将文件内容作为指令执行。命令带来的核心价值：

• 可复用性：定义一次，反复使用
• 一致性：标准化常见工作流
• 可共享：在团队或项目间分发
• 高效性：快速访问复杂提示词

关键认知：命令是写给 Claude 的指令，而非写给用户的说明

当用户输入/command-name时，命令内容会变成 Claude 的指令。因此命令必须以"对 Claude 的指示"而非"对用户的消息"来撰写。

正确写法（对 Claude 的指令）：

Review this code for security vulnerabilities including: - SQL injection - XSS attacks - Authentication issues Provide specific line numbers and severity ratings.

错误写法（对用户的消息）：

This command will review your code for security issues. You'll receive a report with vulnerability details.

第一个示例告诉 Claude 该做什么；第二个示例告诉用户"会发生什么"但并未指示 Claude。开发命令时务必采用第一种写法。

命令存放位置

命令按作用域分为三类，在/help中通过标签区分：

文件格式：从最简命令到 frontmatter

命令是带.md扩展名的 Markdown 文件，目录结构如下：

.claude/commands/ ├── review.md # /review 命令 ├── test.md # /test 命令 └── deploy.md # /deploy 命令

最简命令（无需任何 frontmatter）：

Review this code for security vulnerabilities including: - SQL injection - XSS attacks - Authentication bypass - Insecure data handling

带 YAML frontmatter 的命令：

--- description: Review code for security issues allowed-tools: Read, Grep, Bash(git:*) model: sonnet --- Review this code for security vulnerabilities...

仓库中的 example-plugin 提供了一个可直接对照的example-command.md示例，而 plugin-dev 的 create-plugin.md 工作流命令（/plugin-dev:create-plugin）本身就是一个完整命令的范本——它使用数组形式的allowed-tools列出Read、Write、Grep、Glob、Bash、TodoWrite、AskUserQuestion、Skill、Task等工具，并通过$ARGUMENTS接收可选的插件描述参数。

YAML Frontmatter 字段详解

以下字段的完整规范可参见 frontmatter-reference.md，该文档包含每个字段的类型、默认值、适用场景与验证清单。

description

• 用途：在/help中展示的简短描述
• 类型：字符串
• 默认值：命令提示词的第一行
• 最佳实践：清晰、可行动的描述，建议 60 字符以内

--- description: Review pull request for code quality ---

好的描述以动词开头（Review、Deploy、Generate）、具体说明命令行为；避免"This command reviews PRs"这类冗余表述，也避免过于模糊或过长。

allowed-tools

• 用途：指定命令可以使用的工具
• 类型：字符串或字符串数组
• 默认值：继承自会话权限

--- allowed-tools: Read, Write, Edit, Bash(git:*) ---

支持的模式：

• Read, Write, Edit—— 指定具体工具
• Bash(git:*)—— 仅允许 git 命令
• Bash(npm:*)、Bash(docker:*)—— 按命令前缀过滤
• *—— 全部工具（极少需要）

数组形式：

allowed-tools: - Read - Write - Bash(git:*)

最佳实践：尽可能严格限制；Bash 务必使用命令过滤器（如git:*而非裸*）；仅在与会话权限不同时才声明。

model

• 用途：指定执行命令的模型
• 类型：字符串（sonnet、opus、haiku）
• 默认值：继承自会话

model: haiku

选型建议：haiku用于简单、公式化、高频调用的命令（追求速度）；sonnet用于标准工作流（速度与质量的平衡）；opus用于复杂分析、架构决策、深度代码理解等关键任务。仅在有明确需要时才指定，并建议用不同模型测试以找到最佳平衡。

argument-hint

• 用途：为自动补全（autocomplete）文档化期望参数，帮助用户理解命令接口、提升命令可发现性
• 类型：字符串
• 默认值：无

--- argument-hint: [pr-number] [priority] [assignee] ---

每个参数用方括号[]包裹，使用描述性名称（如[source-branch] [target-branch]），顺序须与位置参数一一对应。

disable-model-invocation

• 用途：阻止 SlashCommand 工具以编程方式调用该命令
• 类型：布尔值
• 默认值：false

--- disable-model-invocation: true ---

适用于：仅需人工判断的命令（如生产环境部署审批）、不可逆操作（如删除全部测试数据）、需要用户输入引导的交互式工作流。开启后命令仅能由用户手动输入/command触发，更安全但会限制 Claude 的自主性，应谨慎使用。

动态参数：$ARGUMENTS 与位置参数

使用 $ARGUMENTS 捕获全部参数

将全部参数作为单个字符串捕获：

--- description: Fix issue by number argument-hint: [issue-number] --- Fix issue #$ARGUMENTS following our coding standards and best practices.

用法与展开结果：

> /fix-issue 123 → Fix issue #123 following our coding standards... > /fix-issue 456 → Fix issue #456 following our coding standards...

使用位置参数 $1、$2、$3

逐个捕获参数：

--- description: Review PR with priority and assignee argument-hint: [pr-number] [priority] [assignee] --- Review pull request #$1 with priority level $2. After review, assign to $3 for follow-up.

> /review-pr 123 high alice → Review pull request #123 with priority level high. → After review, assign to alice for follow-up.

组合使用

混合位置参数与剩余参数：

Deploy $1 to $2 environment with options: $3

> /deploy api staging --force --skip-tests → Deploy api to staging environment with options: --force --skip-tests

高级参数处理

进阶模式见 advanced-workflows.md，包括：

• 可选参数带默认值：使用${1:-staging}、${2:-latest}形式
• 参数校验：用grep -w校验枚举值（如dev staging production）
• 参数转换：用case语句将简写d/dev、s/stg、p/prod展开为完整环境名

文件引用：@ 语法

单个文件引用

在命令中包含文件内容：

--- description: Review specific file argument-hint: [file-path] --- Review @$1 for: - Code quality - Best practices - Potential bugs

> /review-file src/api/users.ts

效果：Claude 在处理命令前会先读取src/api/users.ts的内容。

多个文件引用

Compare @src/old-version.js with @src/new-version.js Identify: - Breaking changes - New features - Bug fixes

静态文件引用

无需参数即可引用已知文件：

Review @package.json and @tsconfig.json for consistency Ensure: - TypeScript version matches - Dependencies are aligned - Build configuration is correct

最佳实践：使用清晰的项目相对路径；检查文件是否存在并优雅处理缺失；考虑使用 Glob 工具处理通配模式。

Bash 执行：动态收集上下文

命令可以内联执行 Bash 命令，在 Claude 处理提示词之前动态收集仓库状态、环境信息或项目上下文：

!`command here`

适用场景：包含动态上下文（git status、环境变量等）、收集项目/仓库状态、构建上下文感知的工作流。完整语法与多个可运行示例见 plugin-features-reference.md 中关于 Bash 执行的部分。

命令示例：

--- description: Show Git status allowed-tools: Bash(git:*) --- Current status: !`git status` Recent commits: !`git log --oneline -5`

注意：使用 Bash 执行时必须在allowed-tools中声明对应的 Bash 过滤器，否则会因权限不足而失败。

命令组织：扁平结构与命名空间

扁平结构

适合小型命令集（5–15 个命令，无清晰分类）：

.claude/commands/ ├── build.md ├── test.md ├── deploy.md ├── review.md └── docs.md

命名空间结构

按子目录组织命令，适合 15 个以上且有清晰分类的场景：

.claude/commands/ ├── ci/ │ ├── build.md # /build (project:ci) │ ├── test.md # /test (project:ci) │ └── lint.md # /lint (project:ci) ├── git/ │ ├── commit.md # /commit (project:git) │ └── pr.md # /pr (project:git) └── docs/ ├── generate.md # /generate (project:docs) └── publish.md # /publish (project:docs)

收益：按类别逻辑分组、命名空间显示在/help中、更易于查找相关命令。

最佳实践与常见模式

命令设计准则

1. 单一职责：一个命令只做一件事
2. 描述清晰：在/help中自解释
3. 显式依赖：需要时使用allowed-tools
4. 文档化参数：始终提供argument-hint
5. 命名一致：使用"动词-名词"模式（review-pr、fix-issue）

参数处理

在提示词中校验必填参数、建议默认值、说明期望格式、处理缺失或非法参数等边界情况。命令内置了条件语法$IF(...)：

--- argument-hint: [pr-number] --- $IF($1, Review PR #$1, Please provide a PR number. Usage: /review-pr [number] )

文档化命令

用 HTML 注释在命令中嵌入用法、依赖与示例，实现自文档化（完整模板见 documentation-patterns.md）：

--- description: Deploy application to environment argument-hint: [environment] [version] --- <!-- Usage: /deploy [staging|production] [version] Requires: AWS credentials configured Example: /deploy staging v1.2.3 --> Deploy application to $1 environment using version $2...

四个高频模式

Review 模式（结合 Bash 收集变更文件）：

--- description: Review code changes allowed-tools: Read, Bash(git:*) --- Files changed: !`git diff --name-only` Review each file for: 1. Code quality and style 2. Potential bugs or issues 3. Test coverage 4. Documentation needs Provide specific feedback for each file.

Testing 模式（执行指定文件测试）：

--- description: Run tests for specific file argument-hint: [test-file] allowed-tools: Bash(npm:*) --- Run tests: !`npm test $1` Analyze results and suggest fixes for failures.

Documentation 模式（结合文件引用）：

--- description: Generate documentation for file argument-hint: [source-file] --- Generate comprehensive documentation for @$1 including: - Function/class descriptions - Parameter documentation - Return value descriptions - Usage examples - Edge cases and errors

Workflow 模式（多步骤编排）：

--- description: Complete PR workflow argument-hint: [pr-number] allowed-tools: Bash(gh:*), Read --- PR #$1 Workflow: 1. Fetch PR: !`gh pr view $1` 2. Review changes 3. Run checks 4. Approve or request changes

更多可直接复制的完整命令（代码评审、安全审查、文档生成、git 状态汇总、部署、文件对比、代码解释、快速修复、技术调研共 10 个）见 simple-commands.md。

交互式命令：AskUserQuestion 集成

当简单的命令行参数无法承载复杂决策时（如需要在多个有取舍的选项中挑选、从列表多选、需要解释才能决策、交互式收集偏好），应在命令执行中使用AskUserQuestion 工具。完整指南见 interactive-commands.md。

工具参数结构：

{ questions: [ { question: "Which authentication method should we use?", header: "Auth method", // 短标签（最多 12 字符） multiSelect: false, // true 表示允许多选 options: [ { label: "OAuth 2.0", description: "Industry standard, supports multiple providers" }, { label: "JWT", description: "Stateless, good for APIs" }, { label: "Session", description: "Traditional, server-side state" } ] } ] }

关键要点：

• 用户始终可以选"Other"提供自定义输入（自动提供）
• multiSelect: true允许选择多个选项
• 每个问题 2–4 个选项（不要更多）
• 每次工具调用可问 1–4 个问题

交互式命令骨架（需要在allowed-tools中声明AskUserQuestion）：

--- description: Interactive setup command allowed-tools: AskUserQuestion, Write --- # Interactive Plugin Setup This command will guide you through configuring the plugin with a series of questions. ## Step 1: Gather Configuration Use the AskUserQuestion tool to ask: **Question 1 - Deployment target:** - header: "Deploy to" - question: "Which deployment platform will you use?" - options: - AWS (Amazon Web Services with ECS/EKS) - GCP (Google Cloud with GKE) - Azure (Microsoft Azure with AKS) - Local (Docker on local machine) **Question 2 - Environment strategy:** - header: "Environments" - question: "How many environments do you need?" - options: - Single (Just production) - Standard (Dev, Staging, Production) - Complete (Dev, QA, Staging, Production) **Question 3 - Features to enable:** - header: "Features" - question: "Which features do you want to enable?" - multiSelect: true - options: - Auto-scaling (Automatic resource scaling) - Monitoring (Health checks and metrics) - CI/CD (Automated deployment pipeline) - Backups (Automated database backups) ## Step 2: Process Answers Based on the answers received from AskUserQuestion: 1. Parse the deployment target choice 2. Set up environment-specific configuration 3. Enable selected features 4. Generate configuration files ## Step 3: Generate Configuration Create `.claude/plugin-name.local.md` with the answers... ## Step 4: Confirm and Next Steps Confirm configuration created and guide user on next steps.

交互式命令的设计准则：问题要具体、header 不超过 12 字符、选项描述要说明取舍、逻辑顺序自然、通过"渐进式披露"（先简单后详细）控制流程，并配合条件问题流、迭代收集、多选依赖选择等模式。判断标准是：简单的已知值用命令参数，需要解释的复杂选择用 AskUserQuestion。

插件专属特性：CLAUDE_PLUGIN_ROOT 与环境感知

自动发现与命名空间

插件命令从commands/目录自动发现，无需手动注册，加载时即可用，并在/help中以(plugin:plugin-name)标签展示：

plugin-name/ ├── commands/ │ ├── foo.md # /foo (plugin:plugin-name) │ ├── bar.md # /bar (plugin:plugin-name) │ └── utils/ │ └── helper.md # /helper (plugin:plugin-name:utils) └── plugin.json

子目录会形成命名空间，如commands/review/security.md显示为/security (plugin:plugin-name:review)。命名建议：使用描述性动作名称、避免泛化名（test、run）、可用插件名前缀保证唯一性、多词名用连字符。插件命令的命名与发现机制详见 plugin-features-reference.md。

${CLAUDE_PLUGIN_ROOT} 环境变量

插件命令可以访问${CLAUDE_PLUGIN_ROOT}，它解析为插件目录的绝对路径，用于：可移植地引用插件文件、执行插件脚本、加载插件配置、访问插件模板。

基本用法：

--- description: Analyze using plugin script allowed-tools: Bash(node:*) --- Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1` Review results and report findings.

常见模式：

# 执行插件脚本 !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh` # 加载插件配置 @${CLAUDE_PLUGIN_ROOT}/config/settings.json # 使用插件模板 @${CLAUDE_PLUGIN_ROOT}/templates/report.md # 访问插件资源 @${CLAUDE_PLUGIN_ROOT}/docs/reference.md

为什么必须用它：跨所有安装环境工作、系统间可移植、无需硬编码路径、对多文件插件必不可少。反面教材：@./templates/foo.md是相对当前目录而非插件根目录，会破坏可移植性；@/home/user/.claude/plugins/my-plugin/config.json这种硬编码路径在不同安装环境下必然失效。

插件命令模式

配置驱动模式（按环境加载配置）：

--- description: Deploy using plugin configuration argument-hint: [environment] allowed-tools: Read, Bash(*) --- Load configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json Deploy to $1 using configuration settings. Monitor deployment and report status.

模板驱动模式：

--- description: Generate docs from template argument-hint: [component] --- Template: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md Generate documentation for $1 following template structure.

多脚本模式：

--- description: Complete build workflow allowed-tools: Bash(*) --- Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh` Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh` Package: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh` Review outputs and report workflow status.

环境感知模式（根据$1是 prod 还是其他环境执行完整/基础检查集）以及 10 个完整的插件命令示例见 plugin-commands.md。

与插件组件集成：Agent、Skill、Hook 与多组件工作流

集成 Agent

命令可以启动插件 Agent 完成复杂任务（Agent 必须存在于plugin/agents/目录，Claude 通过 Task 工具启动）：

--- description: Deep code review argument-hint: [file-path] --- Initiate comprehensive review of @$1 using the code-reviewer agent. The agent will analyze: - Code structure - Security issues - Performance - Best practices Agent uses plugin resources: - ${CLAUDE_PLUGIN_ROOT}/config/rules.json - ${CLAUDE_PLUGIN_ROOT}/checklists/review.md

集成 Skill

命令可以通过点名技能名称触发插件技能（技能必须存在于plugin/skills/目录）：

--- description: Document API with standards argument-hint: [api-file] --- Document API in @$1 following plugin standards. Use the api-docs-standards skill to ensure: - Complete endpoint documentation - Consistent formatting - Example quality - Error documentation Generate production-ready API docs.

协调 Hook

• 命令可以准备状态供 Hook 处理
• Hook 在工具事件上自动执行
• 命令应文档化期望的 Hook 行为
• 引导 Claude 解读 Hook 输出

多组件工作流

组合脚本、Agent、Skill 与模板，实现端到端流水线（适用于复杂多步、需要多个插件能力、需要结构化输出的场景）：

--- description: Comprehensive review workflow argument-hint: [file] allowed-tools: Bash(node:*), Read --- Target: @$1 Phase 1 - Static Analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1` Phase 2 - Deep Review: Launch code-reviewer agent for detailed analysis. Phase 3 - Standards Check: Use coding-standards skill for validation. Phase 4 - Report: Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md Compile findings into report following template.

输入校验模式：让命令稳健可依赖

命令应在处理前校验输入与资源，完整模式见 plugin-features-reference.md。

参数校验（grep 枚举白名单）：

--- description: Deploy with validation argument-hint: [environment] --- Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"` If $1 is valid environment: Deploy to $1 Otherwise: Explain valid environments: dev, staging, prod Show usage: /deploy [environment]

文件存在性检查：

--- description: Process configuration argument-hint: [config-file] --- Check file exists: !`test -f $1 && echo "EXISTS" || echo "MISSING"` If file exists: Process configuration: @$1 Otherwise: Explain where to place config file Show expected format Provide example configuration

插件资源校验：

--- description: Run plugin analyzer allowed-tools: Bash(test:*) --- Validate plugin setup: - Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"` - Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"` If all checks pass, run analysis. Otherwise, report missing components.

错误处理（捕获失败并分析）：

--- description: Build with error handling allowed-tools: Bash(*) --- Execute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo "BUILD_FAILED"` If build succeeded: Report success and output location If build failed: Analyze error output Suggest likely causes Provide troubleshooting steps

最佳实践：尽早校验、提供有帮助的错误消息、建议纠正措施、优雅处理边界情况。

测试与发布前的质量保障

命令发布前应通过多级测试，完整策略见 testing-strategies.md：

1. 语法与结构验证：YAML frontmatter 有且仅有两个---标记、.md扩展名、文件位于正确目录，可编写validate-command.sh自动化
2. frontmatter 字段校验：model必须是sonnet/opus/haiku、description建议 60 字符内、allowed-tools格式正确
3. 手动调用：claude --debug启动、确认命令出现在/help、分别测试无参/有参调用、检查~/.claude/debug-logs/latest日志
4. 参数测试矩阵：无参、单参、多参、多余参数、含空格参数、空参数
5. 文件引用测试：存在/不存在/大文件/多文件引用
6. Bash 执行测试：允许的命令正常执行、被allowed-tools禁止的命令应被拦截
7. 集成测试：与 Hook 联动、命令序列状态流转、MCP 工具调用

常见故障排查（详见 SKILL.md 的 Troubleshooting 章节）：

面向市场分发的额外考量

命令若要在市场分发，还需考虑跨平台兼容、最小化依赖与未知用户的使用体验（详见 marketplace-considerations.md）：

• 跨平台：用case "$(uname)"检测 macOS/Linux/Windows，避免pbcopy等平台专属命令
• 依赖检查：用command -v检查 git、jq、node 等必需工具是否可用，缺失时给出安装指引
• 充分文档：在命令注释中记录 PURPOSE、USAGE、ARGUMENTS、EXAMPLES、REQUIREMENTS、TROUBLESHOOTING、CHANGELOG

总结

掌握 Slash 命令开发等于掌握了 Claude Code 工作流的"积木语言"：frontmatter 定义行为边界（allowed-tools控制安全、model控制成本与质量、argument-hint定义接口），$ARGUMENTS/$1传递输入，@引入上下文，!注入实时环境状态，${CLAUDE_PLUGIN_ROOT}保证插件内路径可移植，再叠加 Agent、Skill、Hook 与 AskUserQuestion，即可从单条提示词升级为完整的交互式、可校验、可分发的工作流系统。开发时遵循本技能的核心原则——单一职责、最小工具权限、始终文档化参数、尽早校验、充分测试——你的命令就能成为团队和社区可长期依赖的自动化资产。

如需进一步深入，可继续阅读 frontmatter-reference.md（字段完整规范）、plugin-features-reference.md（插件专属特性）、interactive-commands.md（交互模式）、advanced-workflows.md（多命令编排与状态管理），以及 examples 目录下的完整命令示例。

• AI 插件
• 开发工具
• 插件系统