AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载导读本文是claude-plugins-official仓库中 plugin-dev 技能体系 下关于Agent 系统提示词设计的完整实战指南主体内容源自 system-prompt-design.md。Claude Code 插件中的 Agent 是独立的自主子进程其 Markdown 文件正文即成为该 Agent 的系统提示词system prompt直接决定 Agent 能否在无人干预的情况下高质量完成复杂、多步骤任务。读完本文你将掌握一套经过验证的系统提示词核心结构、四类常见 Agent分析、生成、验证、编排的完整模板、写作风格与常见陷阱清单、长度取舍标准以及如何系统化地测试与迭代系统提示词并看到这些模式在仓库真实 Agent 中的落地形态。一、系统提示词在 Agent 架构中的位置在深入设计模式之前先明确系统提示词的定位。根据 agent-development/SKILL.md 的说明Agent 文件由两部分组成YAML frontmatter包含name标识符、description触发条件Agent 注册时被加载进上下文用于调度决策、model、color、可选的tools白名单。Markdown 正文即 Agent 的系统提示词是 Agent 行为的完整操作手册。从仓库的校验脚本validate-agent.sh可以确认这一设计脚本将 frontmatter 与正文分离后会检查正文SYSTEM_PROMPT是否使用第二人称You are/You will/Your、是否包含 responsibilities/process 等结构关键词、是否定义了 output 格式并约束正文长度在 20 至 10,000 字符之间。这意味着系统提示词的结构化程度是可被机器校验的硬性要求而非可选的写作风格偏好。二、核心结构每个 Agent 都应遵循的骨架system-prompt-design.md给出了一个适用于所有 Agent 的通用结构模板任何角色、任何领域的 Agent 都建议以此骨架为起点You are [specific role] specializing in [specific domain]. **Your Core Responsibilities:** 1. [Primary responsibility - the main task] 2. [Secondary responsibility - supporting task] 3. [Additional responsibilities as needed] **[Task Name] Process:** 1. [First concrete step] 2. [Second concrete step] 3. [Continue with clear steps] [...] **Quality Standards:** - [Standard 1 with specifics] - [Standard 2 with specifics] - [Standard 3 with specifics] **Output Format:** Provide results structured as: - [Component 1] - [Component 2] - [Include specific formatting requirements] **Edge Cases:** Handle these situations: - [Edge case 1]: [Specific handling approach] - [Edge case 2]: [Specific handling approach]模板的五个区块各有明确职责区块作用常见错误角色声明You are...建立专业身份与领域定位身份泛化如You are a helpful assistantCore Responsibilities明确主次责任边界责任模糊无法约束行为Process给出可执行的具体步骤序列只告诉做什么不告诉怎么做Quality Standards定义可度量的质量标准标准不可验证Output Format锁定输出结构与格式输出格式未定义结果千奇百怪Edge Cases覆盖异常与边界场景忽略错误场景Agent 遇到异常即崩溃这一结构与仓库中真实 Agent 的实现完全吻合。例如 pr-review-toolkit/agents/code-reviewer.md 就是按角色声明 → When to invoke → Review Scope → Core Review Responsibilities → Issue Confidence Scoring → Output Format的骨架组织的其中质量判定部分还细化为 0-100 的置信度评分区间是Quality Standards 具体化的典型范例。三、模式一分析型 AgentAnalysis Agents适用于分析代码、PR 或文档的 Agent。核心特征是输入是待分析对象输出是结构化结论与建议。You are an expert [domain] analyzer specializing in [specific analysis type]. **Your Core Responsibilities:** 1. Thoroughly analyze [what] for [specific issues] 2. Identify [patterns/problems/opportunities] 3. Provide actionable recommendations **Analysis Process:** 1. **Gather Context**: Read [what] using available tools 2. **Initial Scan**: Identify obvious [issues/patterns] 3. **Deep Analysis**: Examine [specific aspects]: - [Aspect 1]: Check for [criteria] - [Aspect 2]: Verify [criteria] - [Aspect 3]: Assess [criteria] 4. **Synthesize Findings**: Group related issues 5. **Prioritize**: Rank by [severity/impact/urgency] 6. **Generate Report**: Format according to output template **Quality Standards:** - Every finding includes file:line reference - Issues categorized by severity (critical/major/minor) - Recommendations are specific and actionable - Positive observations included for balance **Output Format:** ## Summary [2-3 sentence overview] ## Critical Issues - [file:line] - [Issue description] - [Recommendation] ## Major Issues [...] ## Minor Issues [...] ## Recommendations [...] **Edge Cases:** - No issues found: Provide positive feedback and validation - Too many issues: Group and prioritize top 10 - Unclear code: Request clarification rather than guessing该模式的关键设计要点多阶段流程Gather Context → Initial Scan → Deep Analysis → Synthesize → Prioritize → Generate Report先广后深、先收集后下结论避免 Agent 一上来就陷入细节。量化输出每个发现都要求file:line引用按 critical/major/minor 分级——这使结果可以被人类或下游流程直接消费。正面反馈平衡明确要求包含 Positive observations避免审查类 Agent 变成只会挑刺。仓库中的完整参考案例见 examples/complete-agent-examples.md 的 Example 1: Code Review Agentagents/code-reviewer.md它把 Deep Analysis 细化为 Code QualityDRY、复杂度、错误处理、Security注入、认证授权、输入校验、Best Practices命名、测试覆盖三个维度并把输出格式扩展为 Summary / Critical / Major / Minor / Positive Observations / Overall Assessment 六段式。四、模式二生成型 AgentGeneration Agents适用于创建代码、测试或文档的 Agent。核心特征是输入是需求与上下文输出是产物文件或内容。You are an expert [domain] engineer specializing in creating high-quality [output type]. **Your Core Responsibilities:** 1. Generate [what] that meets [quality standards] 2. Follow [specific conventions/patterns] 3. Ensure [correctness/completeness/clarity] **Generation Process:** 1. **Understand Requirements**: Analyze what needs to be created 2. **Gather Context**: Read existing [code/docs/tests] for patterns 3. **Design Structure**: Plan [architecture/organization/flow] 4. **Generate Content**: Create [output] following: - [Convention 1] - [Convention 2] - [Best practice 1] 5. **Validate**: Verify [correctness/completeness] 6. **Document**: Add comments/explanations as needed **Quality Standards:** - Follows project conventions (check CLAUDE.md) - [Specific quality metric 1] - [Specific quality metric 2] - Includes error handling - Well-documented and clear **Output Format:** Create [what] with: - [Structure requirement 1] - [Structure requirement 2] - Clear, descriptive naming - Comprehensive coverage **Edge Cases:** - Insufficient context: Ask user for clarification - Conflicting patterns: Follow most recent/explicit pattern - Complex requirements: Break into smaller pieces生成型 Agent 的两个容易被忽略的要点先看再写Generation Process 的第 2 步明确要求读取现有代码/文档/测试以了解既有模式这是保证生成产物符合项目惯例而不是凭空捏造的关键。质量护栏前置Follows project conventions (check CLAUDE.md) 被列为第一条质量标准——生成内容的合规性优先于正确性因为不合规的代码在项目里寸步难行。examples/complete-agent-examples.md 中的 Example 2: Test Generator Agent 是此模式的标准落地它要求先识别既有测试框架Jest/pytest、文件组织test/ 目录、*.test.ts、命名约定再按 happy path / boundary / error / edge 四类设计用例最终遵循 DAMP 原则Descriptive And Meaningful Phrases输出。五、模式三验证型 AgentValidation Agents适用于校验、检查或核实任务的 Agent。核心特征是有明确标准输出 PASS/FAIL 判定及违规明细。You are an expert [domain] validator specializing in ensuring [quality aspect]. **Your Core Responsibilities:** 1. Validate [what] against [criteria] 2. Identify violations and issues 3. Provide clear pass/fail determination **Validation Process:** 1. **Load Criteria**: Understand validation requirements 2. **Scan Target**: Read [what] needs validation 3. **Check Rules**: For each rule: - [Rule 1]: [Validation method] - [Rule 2]: [Validation method] 4. **Collect Violations**: Document each failure with details 5. **Assess Severity**: Categorize issues 6. **Determine Result**: Pass only if [criteria met] **Quality Standards:** - All violations include specific locations - Severity clearly indicated - Fix suggestions provided - No false positives **Output Format:** ## Validation Result: [PASS/FAIL] ## Summary [Overall assessment] ## Violations Found: [count] ### Critical ([count]) - [Location]: [Issue] - [Fix] ### Warnings ([count]) - [Location]: [Issue] - [Fix] ## Recommendations [How to fix violations] **Edge Cases:** - No violations: Confirm validation passed - Too many violations: Group by type, show top 20 - Ambiguous rules: Document uncertainty, request clarification验证型模式的设计哲学是宁可不出报告不可误报Quality Standards 中的 No false positives 与输出模板中的Validation Result: [PASS/FAIL]一锤定音式判定都是为了让验证结果具备高信任度。注意其判定规则是Pass only if [criteria met]——即默认不通过只有全部标准满足才放行这与 CI 门禁的语义一致。仓库中 pr-review-toolkit/agents/code-reviewer.md 的置信度评分机制0-100 分仅报告置信度 ≥ 80 的问题就是验证/审查模式控制误报率思想的工程化实现——它将可能误报的量化为数值阈值从而在保真度与召回率之间取得平衡。六、模式四编排型 AgentOrchestration Agents适用于协调多个工具或多个步骤的 Agent。核心特征是多阶段流水线 失败处理 进度汇报。You are an expert [domain] orchestrator specializing in coordinating [complex workflow]. **Your Core Responsibilities:** 1. Coordinate [multi-step process] 2. Manage [resources/tools/dependencies] 3. Ensure [successful completion/integration] **Orchestration Process:** 1. **Plan**: Understand full workflow and dependencies 2. **Prepare**: Set up prerequisites 3. **Execute Phases**: - Phase 1: [What] using [tools] - Phase 2: [What] using [tools] - Phase 3: [What] using [tools] 4. **Monitor**: Track progress and handle failures 5. **Verify**: Confirm successful completion 6. **Report**: Provide comprehensive summary **Quality Standards:** - Each phase completes successfully - Errors handled gracefully - Progress reported to user - Final state verified **Output Format:** ## Workflow Execution Report ### Completed Phases - [Phase]: [Result] ### Results - [Output 1] - [Output 2] ### Next Steps [If applicable] **Edge Cases:** - Phase failure: Attempt retry, then report and stop - Missing dependencies: Request from user - Timeout: Report partial completion编排型模式与前三种的核心差异在于失败处理是被显式建模的阶段失败 → 重试一次 → 汇报并停止Attempt retry, then report and stop防止 Agent 无限循环或静默吞掉错误缺少依赖 → 向用户请求而非自行假设超时 → 报告部分完成保留已完成阶段的成果。此外Progress reported to user与Final state verified两条质量标准强调了编排类任务的可观测性——用户需要知道流水线进行到哪一步以及最终状态是否被核实。七、写作风格指南语气、清晰性与可操作性无论采用哪种模式系统提示词的写作风格都有三条硬性纪律原文 中用 ✅/❌ 对照列出7.1 语气强制第二人称系统提示词是写给 Agent 本人看的必须用第二人称直接对它说话✅ You are responsible for... ✅ You will analyze... ✅ Your process should... ❌ The agent is responsible for... ❌ This agent will analyze... ❌ I will analyze...第一人称I will analyze...会让 Agent 把自身当作外部叙述者而非执行者第三人称The agent is...同样削弱指令的直接性。validate-agent.sh 会用正则检查正文是否包含You are|You will|Your不符合会给出警告——这是可自动化的风格约束。7.2 清晰性具体而非含糊✅ Check for SQL injection by examining all database queries for parameterization ❌ Look for security issues ✅ Provide file:line references for each finding ❌ Show where issues are ✅ Categorize as critical (security), major (bugs), or minor (style) ❌ Rate the severity of issues具体化的标准是指令必须能直接转化为工具调用和判定规则。比如把查找安全问题的位置升级为给出每个发现的 file:line 引用把评估严重性升级为按 critical(安全) / major(缺陷) / minor(风格) 分类。7.3 可操作性给出具体步骤而非抽象目标✅ Read the file using the Read tool, then search for patterns using Grep ❌ Analyze the code ✅ Generate test file at test/path/to/file.test.ts ❌ Create tests可操作指令的判据是每一步都绑定具体的工具Read / Grep或具体的产物路径。仓库中 feature-dev/agents/code-reviewer.md 就是这一纪律的例证——它用tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput显式声明可用的工具集合让流程中的每个动作都有落点。八、常见陷阱四条高频翻车点system-prompt-design.md用正反对照的方式列出了系统提示词最常见的四条失败模式陷阱 1责任描述模糊Vague Responsibilities**Your Core Responsibilities:** 1. Help the user with their code 2. Provide assistance 3. Be helpful为什么失败缺乏任何可约束行为的细节Agent 无从判断帮助的边界与深度。对照正确写法**Your Core Responsibilities:** 1. Analyze TypeScript code for type safety issues 2. Identify missing type annotations and improper any usage 3. Recommend specific type improvements with examples陷阱 2缺少过程步骤Missing Process StepsAnalyze the code and provide feedback.为什么失败Agent 不知道如何分析。对照正确写法——把分析过程拆成五步可执行动作**Analysis Process:** 1. Read code files using Read tool 2. Scan for type annotations on all functions 3. Check for any type usage 4. Verify generic type parameters 5. List findings with file:line references陷阱 3输出格式未定义Undefined OutputProvide a report.为什么失败Agent 不知道报告的格式、结构、粒度。对照正确写法**Output Format:** ## Type Safety Report ### Summary [Overview of findings] ### Issues Found - file.ts:42 - Missing return type on processData - utils.ts:15 - Unsafe any usage in parameter ### Recommendations [Specific fixes with examples]陷阱 4隐含忽略边界与错误场景系统提示词若只覆盖正常路径Agent 在面对异常输入、歧义需求、超大输入时只能随机应变。因此核心结构模板中的Edge Cases区块与三类模式中的 edge case 清单都应被视为必需而非可选。九、长度指南从最小可行到全面覆盖系统提示词的长度应与任务的复杂度匹配原文给出了三档参考档位字数应包含的内容最小可行 Agent~500 词起角色描述、3 条核心责任、5 步流程、输出格式标准 Agent~1,000-2,000 词详细角色与专长、5-8 条责任、8-12 步流程、质量标准、输出格式、3-5 个边界场景全面 Agent~2,000-5,000 词完整角色背景、全面责任、多阶段流程、扩展质量标准、多种输出格式、大量边界场景、提示词内嵌示例硬性上限避免超过 10,000 词——原文明确指出 Too long, diminishing returns。这与 agent-development/SKILL.md 的约束Keep under 10,000 characters以及 validate-agent.sh 对超过 10,000 字符的警告相互印证过长既消耗上下文窗口又稀释关键指令的权重。注意agent-development/SKILL.md 在验证规则中给出的是字符级约束system prompt 长度 20-10,000 字符推荐 500-3,000 字符与这里的词数指南互为补充——写作时可先按最小可行起步再向标准档扩充。十、测试与迭代系统提示词系统提示词不是写完就结束的原文给出了两轮测试清单与迭代闭环。10.1 完整性测试Completeness仅凭系统提示词Agent 能否独立处理以下场景典型任务执行已提及的边界场景错误场景需求不明确的情况大型/复杂输入空输入/缺失输入10.2 清晰性测试Clarity通读系统提示词并追问四个问题另一个开发者能否看懂这个 Agent 是做什么的流程步骤是否清晰可执行输出格式是否有歧义质量标准是否可度量10.3 基于测试结果的迭代循环实际运行 Agent 后按五步闭环改进定位 Agent 在哪些环节表现挣扎在系统提示词中补充缺失的指导澄清有歧义的指令为暴露出的边界场景补充流程步骤重新测试仓库为此提供了配套的验证与测试工具scripts/validate-agent.sh 校验文件结构与字段约束name 格式、description 长度、model/color 合法值、系统提示词结构与人称而 agent-development/SKILL.md 的 Testing Agents 一节则给出了测试触发与测试系统提示词的实操步骤用与 description 中示例相近的措辞验证 Claude 能正确加载 Agent再验证它是否按流程步骤执行并产出符合格式的结果。十一、仓库中的真实落地从模板到生产 Agent模板只有落到真实文件才具备参考价值。仓库中有多处直接践行了本文所述模式的 Agent可作为模式 → 实现的对照标本pr-review-toolkit/agents/code-reviewer.md完整的分析型 验证型混合体。它的description采用Use this agent when... Typical triggers include... 句式并指向正文的 When to invoke 区块正文严格按角色声明 → When to invoke3 个场景→ Review Scope → Core Review Responsibilities → Issue Confidence Scoring → Output Format组织质量标准被量化为置信度分档0-25 疑似误报 / 26-50 细枝末节 / 51-75 低影响 / 76-90 重要 / 91-100 关键并规定Only report issues with confidence ≥ 80——这是对模板中 No false positives 与 Prioritize 的工程化强化。feature-dev/agents/code-reviewer.md将责任范围显式化为三块Project Guidelines Compliance / Bug Detection / Code Quality并通过显式tools白名单限定工具边界是可操作性指令 最小权限工具组合的样例。agent-development/examples/complete-agent-examples.md四个可直接复制修改的生产级完整示例code-reviewer / test-generator / docs-generator / security-analyzer每个都包含 frontmatter When to invoke 流程 质量标准 输出格式 边界场景是把本文所有模式拼装成完整文件的成品样板间。agent-development/examples/agent-creation-prompt.md与 references/agent-creation-system-prompt.md**展示了如何用 AI 辅助生成 Agent——把需求描述交给 Claude产出identifier/whenToUse/systemPrompt三字段 JSON再转换为带 frontmatter 的 Agent 文件其中systemPrompt正是按本文的核心结构模板生成的。关于触发条件的更多写作细节description字段与 When to invoke 正文的职责分工、场景措辞的优劣对照、2-4 个触发场景的取舍、触发失灵时的排障步骤可进一步阅读 references/triggering-examples.md它与系统提示词设计是一枚硬币的两面——触发解决何时被调用系统提示词解决被调用后如何做好。十二、结论有效系统提示词的五个判据回顾全文一个有效的 Agent 系统提示词应当同时满足五个特质Specific具体清楚说明做什么what与怎么做howStructured结构化按角色、责任、流程、质量标准、输出格式、边界场景组织Complete完整同时覆盖正常路径与边界/错误场景Actionable可操作提供可直接执行的步骤绑定具体工具与产物路径Testable可测试质量标准可度量如 file:line 引用、严重性分级、置信度阈值从而可以被机器校验与回归测试。把这五个判据与第二至六节的核心结构模板、四类模式组合起来再配合第九至十节的长度与测试纪律你就能为任何领域写出可自主、高质量运行的 Claude Code 插件 Agent。以本文提供的模式为模板针对你的领域定制责任、流程与输出格式并基于 Agent 的真实表现持续迭代——这正是该参考文档给出的最终工作方式。赞分享AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载相关推荐Claude Code 插件 Agent 开发完全指南结构、触发条件与系统提示词实战Claude Code 插件 Agent 开发完全指南结构、触发条件与系统提示词实战 本篇指南基于 claude plugins official 官方插件仓AI 插件开发工具插件系统7步打造专业物理实验设计假设验证提示词模板完全指南7步打造专业物理实验设计假设验证提示词模板完全指南 物理实验设计是科学研究的核心技能而一个结构清晰的假设验证提示词模板能显著提升实验效率和准确性。本文将结合示例工程HelloAgents Code Agent 系统提示词设计构建类 Claude Code/Codex 的仓库内 CLI 编程助手HelloAgents Code Agent 系统提示词设计构建类 Claude Code/Codex 的仓库内 CLI 编程助手 导读 本文深入剖析 Da教程人工智能大模型AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考