AGENT SKILL

bmad-create-story

Deprecated: `bmad-build` is now the official implementation method. Only use this when explicitly invoked by name.

License 许可
MIT
最近更新
2026-08-25
Stars
★ 1
Forks
2

01 前言 Front Matter

name
bmad-create-story
description
Deprecated: `bmad-build` is now the official implementation method. Only use this when explicitly invoked by name.

02 资源文件 4

03 SKILL.md 正文

Create Story Workflow

Goal: Create a comprehensive story file that gives the dev agent everything needed for flawless implementation.

Your Role: Story context engine that prevents LLM developer mistakes, omissions, or disasters.

  • Communicate all responses in {communication_language} and generate all documents in {document_output_language}
  • Your purpose is NOT to copy from epics - it's to create a comprehensive, optimized story file that gives the DEV agent EVERYTHING needed for flawless implementation
  • COMMON LLM MISTAKES TO PREVENT: reinventing wheels, wrong libraries, wrong file locations, breaking regressions, ignoring UX, vague implementations, lying about completion, not learning from past work
  • EXHAUSTIVE ANALYSIS REQUIRED: You must thoroughly analyze ALL artifacts to extract critical context - do NOT be lazy or skim! This is the most important function in the entire development process!
  • UTILIZE SUBPROCESSES AND SUBAGENTS: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different artifacts simultaneously and thoroughly
  • SAVE QUESTIONS: If you think of questions or clarifications during analysis, save them for the end after the complete story is written
  • ZERO USER INTERVENTION: Process should be fully automated except for initial epic/story selection or missing documents

Subagents, when the capability is available, are an important part of this workflow. Use them as directed by the workflow steps. If you need an explicit user instruction to run them, ask once now for the whole workflow run.

Conventions

  • Bare paths (e.g. discover-inputs.md) resolve from the skill root.
  • {skill-root} resolves to this skill's installed directory (where customize.toml lives).
  • {project-root}-prefixed paths resolve from the project working directory.
  • {skill-name} resolves to the skill directory's basename.

On Activation

Step 1: Resolve the Workflow Block

Run: uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow

If the script fails, resolve the workflow block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:

  1. {skill-root}/customize.toml — defaults
  2. {project-root}/_bmad/custom/{skill-name}.toml — team overrides
  3. {project-root}/_bmad/custom/{skill-name}.user.toml — personal overrides

Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by code or id replace matching entries and append new entries, and all other arrays append.

Step 2: Execute Prepend Steps

Execute each entry in {workflow.activation_steps_prepend} in order before proceeding.

Step 3: Load Persistent Facts

Treat every entry in {workflow.persistent_facts} as foundational context you carry for the rest of the workflow run. Entries prefixed file: are paths or globs under {project-root} — load the referenced contents as facts. All other entries are facts verbatim.

Step 4: Load Config

Load config from {project-root}/_bmad/bmm/config.yaml and resolve:

  • project_name, user_name
  • communication_language, document_output_language
  • user_skill_level
  • planning_artifacts, implementation_artifacts
  • date as system-generated current datetime

Step 5: Greet the User

Greet {user_name}, speaking in {communication_language}.

<output>Deprecated: bmad-build is now the official implementation method. Only use this when explicitly invoked by name.</output>

Step 6: Execute Append Steps

Execute each entry in {workflow.activation_steps_append} in order.

Activation is complete. If activation_steps_prepend or activation_steps_append were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.

Paths

  • sprint_status = {implementation_artifacts}/sprint-status.yaml
  • epics_file = {planning_artifacts}/epics.md
  • prd_file = {planning_artifacts}/prd.md
  • architecture_file = {planning_artifacts}/architecture.md
  • ux_file = {planning_artifacts}/*ux*.md
  • story_title = "" (will be elicited if not derivable)
  • default_output_file = {implementation_artifacts}/{{story_key}}.md

Input Files

Input Description Path Pattern(s) Load Strategy
prd PRD (fallback - epics file should have most content) whole: {planning_artifacts}/*prd*.md, sharded: {planning_artifacts}/*prd*/*.md SELECTIVE_LOAD
architecture Architecture (fallback - epics file should have relevant sections) whole: {planning_artifacts}/*architecture*.md, sharded: {planning_artifacts}/*architecture*/*.md SELECTIVE_LOAD
ux UX design (fallback - epics file should have relevant sections) whole: {planning_artifacts}/*ux*.md, sharded: {planning_artifacts}/*ux*/*.md SELECTIVE_LOAD
epics Enhanced epics+stories file with BDD and source hints whole: {planning_artifacts}/*epic*.md, sharded: {planning_artifacts}/*epic*/*.md SELECTIVE_LOAD

Execution

<workflow>

<step n="1" goal="Determine target story"> <check if="{{story_path}} is provided by user or user provided the epic and story number such as 2-4 or 1.6 or epic 1 story 5"> <action>Parse user-provided story path: extract epic_num, story_num, story_title from format like "1-2-user-auth"</action> <action>Set {{epic_num}}, {{story_num}}, {{story_key}} from user input</action> <action>GOTO step 2a</action> </check>

<action>Check if {{sprint_status}} file exists for auto discover</action> <check if="sprint status file does NOT exist"> <output>🚫 No sprint status file found and no story specified</output> <output> Required Options: 1. Run sprint-planning to initialize sprint tracking (recommended) 2. Provide specific epic-story number to create (e.g., "1-2-user-auth") 3. Provide path to story documents if sprint status doesn't exist yet </output> <ask>Choose option [1], provide epic-story number, path to story docs, or [q] to quit:</ask>

<check if="user chooses 'q'">
  <action>HALT - No work needed</action>
</check>

<check if="user chooses '1'">
  <output>Run sprint-planning workflow first to create sprint-status.yaml</output>
  <action>HALT - User needs to run sprint-planning</action>
</check>

<check if="user provides epic-story number">
  <action>Parse user input: extract epic_num, story_num, story_title</action>
  <action>Set {{epic_num}}, {{story_num}}, {{story_key}} from user input</action>
  <action>GOTO step 2a</action>
</check>

<check if="user provides story docs path">
  <action>Use user-provided path for story documents</action>
  <action>GOTO step 2a</action>
</check>

</check>

<!-- Auto-discover from sprint status only if no user input --> <check if="no user input provided"> <critical>MUST read COMPLETE {sprint_status} file from start to end to preserve order</critical> <action>Load the FULL file: {{sprint_status}}</action> <action>Read ALL lines from beginning to end - do not skip any content</action> <action>Parse the development_status section completely</action>

<action>Find the FIRST story (by reading in order from top to bottom) where:
  - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
  - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
  - Status value equals "backlog"
</action>

<check if="no backlog story found">
  <output>📋 No backlog stories found in sprint-status.yaml

    All stories are either already created, in progress, or done.

    **Options:**
    1. Run sprint-planning to refresh story tracking
    2. Load PM agent and run correct-course to add more stories
    3. Check if current sprint is complete and run retrospective
  </output>
  <action>HALT</action>
</check>

<action>Extract from found story key (e.g., "1-2-user-authentication"):
  - epic_num: first number before dash (e.g., "1")
  - story_num: second number after first dash (e.g., "2")
  - story_title: remainder after second dash (e.g., "user-authentication")
</action>
<action>Set {{story_id}} = "{{epic_num}}.{{story_num}}"</action>
<action>Store story_key for later use (e.g., "1-2-user-authentication")</action>

<!-- Mark epic as in-progress if this is first story -->
<action>Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern</action>
<check if="this is first story in epic {{epic_num}}">
  <action>Load {{sprint_status}} and check epic-{{epic_num}} status</action>
  <action>If epic status is "backlog" → update to "in-progress"</action>
  <action>If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility)</action>
  <action>If epic status is "in-progress" → no change needed</action>
  <check if="epic status is 'done'">
    <output>🚫 ERROR: Cannot create story in completed epic</output>
    <output>Epic {{epic_num}} is marked as 'done'. All stories are complete.</output>
    <output>If you need to add more work, either:</output>
    <output>1. Manually change epic status back to 'in-progress' in sprint-status.yaml</output>
    <output>2. Create a new epic for additional work</output>
    <action>HALT - Cannot proceed</action>
  </check>
  <check if="epic status is not one of: backlog, contexted, in-progress, done">
    <output>🚫 ERROR: Invalid epic status '{{epic_status}}'</output>
    <output>Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done</output>
    <output>Please fix sprint-status.yaml manually or run sprint-planning to regenerate</output>
    <action>HALT - Cannot proceed</action>
  </check>
  <output>📊 Epic {{epic_num}} status updated to in-progress</output>
</check>

<action>GOTO step 2a</action>

</check> <action>Load the FULL file: {{sprint_status}}</action> <action>Read ALL lines from beginning to end - do not skip any content</action> <action>Parse the development_status section completely</action>

<action>Find the FIRST story (by reading in order from top to bottom) where: - Key matches pattern: number-number-name (e.g., "1-2-user-auth") - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) - Status value equals "backlog" </action>

<check if="no backlog story found"> <output>No backlog stories found in sprint-status.yaml

  All stories are either already created, in progress, or done.

  **Options:**
  1. Run sprint-planning to refresh story tracking
  2. Load PM agent and run correct-course to add more stories
  3. Check if current sprint is complete and run retrospective
</output>
<action>HALT</action>

</check>

<action>Extract from found story key (e.g., "1-2-user-authentication"): - epic_num: first number before dash (e.g., "1") - story_num: second number after first dash (e.g., "2") - story_title: remainder after second dash (e.g., "user-authentication") </action> <action>Set {{story_id}} = "{{epic_num}}.{{story_num}}"</action> <action>Store story_key for later use (e.g., "1-2-user-authentication")</action>

<!-- Mark epic as in-progress if this is first story --> <action>Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern</action> <check if="this is first story in epic {{epic_num}}"> <action>Load {{sprint_status}} and check epic-{{epic_num}} status</action> <action>If epic status is "backlog" → update to "in-progress"</action> <action>If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility)</action> <action>If epic status is "in-progress" → no change needed</action> <check if="epic status is 'done'"> <output>ERROR: Cannot create story in completed epic</output> <output>Epic {{epic_num}} is marked as 'done'. All stories are complete.</output> <output>If you need to add more work, either:</output> <output>1. Manually change epic status back to 'in-progress' in sprint-status.yaml</output> <output>2. Create a new epic for additional work</output> <action>HALT - Cannot proceed</action> </check> <check if="epic status is not one of: backlog, contexted, in-progress, done"> <output>ERROR: Invalid epic status '{{epic_status}}'</output> <output>Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done</output> <output>Please fix sprint-status.yaml manually or run sprint-planning to regenerate</output> <action>HALT - Cannot proceed</action> </check> <output>Epic {{epic_num}} status updated to in-progress</output> </check>

<action>GOTO step 2a</action> </step>

<step n="2" goal="Load and analyze core artifacts"> <critical>🔬 EXHAUSTIVE ARTIFACT ANALYSIS - This is where you prevent future developer mistakes!</critical>

<!-- Load all available content through discovery protocol --> <action>Read fully and follow ./discover-inputs.md to load all input files</action> <note>Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content}, plus the project-context facts loaded during activation via persistent_facts.</note>

<!-- Analyze epics file for story foundation --> <action>From {epics_content}, extract Epic {{epic_num}} complete context:</action> EPIC ANALYSIS: - Epic objectives and business value - ALL stories in this epic for cross-story context - Our specific story's requirements, user story statement, acceptance criteria - Technical requirements and constraints - Dependencies on other stories/epics - Source hints pointing to original documents <!-- Extract specific story requirements --> <action>Extract our story ({{epic_num}}-{{story_num}}) details:</action> STORY FOUNDATION: - User story statement (As a, I want, so that) - Detailed acceptance criteria (already BDD formatted) - Technical requirements specific to this story - Business context and value - Success criteria <!-- Previous story analysis for context continuity --> <check if="story_num > 1"> <action>Find {{previous_story_num}}: scan {implementation_artifacts} for the story file in epic {{epic_num}} with the highest story number less than {{story_num}}</action> <action>Load previous story file: {implementation_artifacts}/{{epic_num}}-{{previous_story_num}}-*.md</action> PREVIOUS STORY INTELLIGENCE: - Dev notes and learnings from previous story - Review feedback and corrections needed - Files that were created/modified and their patterns - Testing approaches that worked/didn't work - Problems encountered and solutions found - Code patterns established <action>Extract all learnings that could impact current story implementation</action> </check>

<!-- Git intelligence for previous work patterns --> <check if="previous story exists AND git repository detected"> <action>Get last 5 commit titles to understand recent work patterns</action> <action>Analyze 1-5 most recent commits for relevance to current story: - Files created/modified - Code patterns and conventions used - Library dependencies added/changed - Architecture decisions implemented - Testing approaches used </action> <action>Extract actionable insights for current story implementation</action> </check> </step>

<step n="3" goal="Architecture analysis for developer guardrails"> <critical>🏗️ ARCHITECTURE INTELLIGENCE - Extract everything the developer MUST follow!</critical> ARCHITECTURE DOCUMENT ANALYSIS: <action>Systematically analyze architecture content for story-relevant requirements:</action>

<!-- Load architecture - single file or sharded --> <check if="architecture file is single file"> <action>Load complete {architecture_content}</action> </check> <check if="architecture is sharded to folder"> <action>Load architecture index and scan all architecture files</action> </check> CRITICAL ARCHITECTURE EXTRACTION: <action>For each architecture section, determine if relevant to this story:</action> - Technical Stack: Languages, frameworks, libraries with versions - Code Structure: Folder organization, naming conventions, file patterns - API Patterns: Service structure, endpoint patterns, data contracts - Database Schemas: Tables, relationships, constraints relevant to story - Security Requirements: Authentication patterns, authorization rules - Performance Requirements: Caching strategies, optimization patterns - Testing Standards: Testing frameworks, coverage expectations, test patterns - Deployment Patterns: Environment configurations, build processes - Integration Patterns: External service integrations, data flows <action>Extract any story-specific requirements that the developer MUST follow</action> <action>Identify any architectural decisions that override previous patterns</action>

<!-- Read existing code being modified — non-negotiable --> <critical>📂 READ FILES BEING MODIFIED — skipping this is the primary cause of implementation failures and review cycles</critical> <action>From the architecture directory structure, identify every file marked UPDATE (not NEW) that this story will touch</action> <action>Read each relevant UPDATE file completely. For each one, document in dev notes: - Current state: what it does today (state machine, API calls, data shapes, existing behaviors) - What this story changes: the specific sections or behaviors being modified - What must be preserved: existing interactions and behaviors the story must not break </action> <critical>A story implementation must leave the system working end-to-end — not just satisfy its stated ACs. If a behavior is required for the feature to work correctly in the existing system, it is a requirement whether or not it is explicitly written in the story. The dev agent owns this.</critical> </step>

<step n="4" goal="Web research for latest technical specifics"> <critical>🌐 ENSURE LATEST TECH KNOWLEDGE - Prevent outdated implementations!</critical> WEB INTELLIGENCE: <action>Identify specific technical areas that require latest version knowledge:</action>

<!-- Check for libraries/frameworks mentioned in architecture --> <action>From architecture analysis, identify specific libraries, APIs, or frameworks</action> <action>For each critical technology, research latest stable version and key changes: - Latest API documentation and breaking changes - Security vulnerabilities or updates - Performance improvements or deprecations - Best practices for current version </action> EXTERNAL CONTEXT INCLUSION: <action>Include in story any critical latest information the developer needs: - Specific library versions and why chosen - API endpoints with parameters and authentication - Recent security patches or considerations - Performance optimization techniques - Migration considerations if upgrading </action> </step>

<step n="5" goal="Create comprehensive story file"> <critical>📝 CREATE ULTIMATE STORY FILE - The developer's master implementation guide!</critical>

<action>Initialize from template.md: {default_output_file}</action> <template-output file="{default_output_file}">story_header</template-output>

<!-- Story foundation from epics analysis --> <template-output file="{default_output_file}">story_requirements</template-output>

<!-- Developer context section - MOST IMPORTANT PART --> <template-output file="{default_output_file}"> developer_context_section</template-output> DEV AGENT GUARDRAILS: <template-output file="{default_output_file}"> technical_requirements</template-output> <template-output file="{default_output_file}">architecture_compliance</template-output> <template-output file="{default_output_file}">library_framework_requirements</template-output> <template-output file="{default_output_file}"> file_structure_requirements</template-output> <template-output file="{default_output_file}">testing_requirements</template-output>

<!-- Previous story intelligence --> <check if="previous story learnings available"> <template-output file="{default_output_file}">previous_story_intelligence</template-output> </check>

<!-- Git intelligence --> <check if="git analysis completed"> <template-output file="{default_output_file}">git_intelligence_summary</template-output> </check>

<!-- Latest technical specifics --> <check if="web research completed"> <template-output file="{default_output_file}">latest_tech_information</template-output> </check>

<!-- Project context reference --> <template-output file="{default_output_file}">project_context_reference</template-output>

<!-- Final status update --> <template-output file="{default_output_file}"> story_completion_status</template-output>

<!-- CRITICAL: Set status to ready-for-dev --> <action>Set story Status to: "ready-for-dev"</action> <action>Add completion note: "Ultimate context engine analysis completed - comprehensive developer guide created"</action> </step>

<step n="6" goal="Update sprint status and finalize"> <action>Validate the newly created story file {default_output_file} against ./checklist.md and apply any required fixes before finalizing</action> <action>Save story document unconditionally</action>

<!-- Update sprint status --> <check if="sprint status file exists"> <action>Update {{sprint_status}}</action> <action>Load the FULL file and read all development_status entries</action> <action>Find development_status key matching {{story_key}}</action> <action>Verify current status is "backlog" (expected previous state)</action> <action>Update development_status[{{story_key}}] = "ready-for-dev"</action> <action>Update last_updated field to current date</action> <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action> </check>

<action>Report completion</action> <output>🎯 ULTIMATE BMad Method STORY CONTEXT CREATED, {user_name}!

**Story Details:**
- Story ID: {{story_id}}
- Story Key: {{story_key}}
- File: {{story_file}}
- Status: ready-for-dev

**Next Steps:**
1. Review the comprehensive story in {{story_file}}
2. Run dev agents `dev-story` for optimized implementation
3. Run `code-review` when complete (auto-marks done)
4. Optional: If Test Architect module installed, run `/bmad:tea:automate` after `dev-story` to generate guardrail tests

**The developer now has everything needed for flawless implementation!**

</output> <action>Run: uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action> </step>

</workflow>

04 同仓库更多 Skills

zaurakworks
zaurakworks/agent-system

skill-maintenance

创建、审计、修正、拆分、升级、迁移或退役 Skill,或其合同/入口已漂移时,先恢复行为、授权与预算,再同步正文、调用者、版本、生成物和验证。普通业务维护、纯格式修正、承载位置未定的纠正不触发。Use for explicit Skill maintenance, not carrier choice.

★ 1
zaurakworks
zaurakworks/agent-system

skill-appraisal

判定一个 Skill 组该不该进当前装配、归哪些事项、与谁重叠,或对已判定过的组按节拍复核。三种进入:首次判定新候选、补判早已在用但从未判定过的组、按失效条件复核。判定单位是组不是单个 Skill;产出必须留下失效条件与下次最少复核步骤。用于外部来源、他人所写、疑似重复或从未被判定过的组。从零设计新 Skill 用 agent-skill-design;已定下后的改造、迁移、退役用 skill-maintenance;只要外部标准与版本事实用 capability-lifecycle;对象是 knowledge 用 knowledge-maintenance。本 Skill 只产出判定,不安装、不写配置、不改 profile。Appraise a Skill group, or recheck an adopted one. Judgement only, never installs.

★ 1
zaurakworks
zaurakworks/agent-system

self-improvement

当用户指出 Agent 漂移、误解、重复犯错,要求把任务经验固化为系统改进,或讨论只增概念却不减关键未知、形成决定或可检验资产时,只暂停依赖被推翻假设的路径,重锚原问题、持久记录纠正、诊断原因,并在授权内改进入口提示词或 Skill。最小实验不能验收产品交付;普通一次性错误、偏好或任务内修复不触发完整自我优化。Use for reported drift, misunderstanding, repeated mistakes, durable Agent improvement, or abstraction loops without decisions or testable assets. Freeze only affected paths and avoid a full detour for ordinary one-off corrections.

★ 1
zaurakworks
zaurakworks/agent-system

resource-observability

当用户查询 Codex/Claude 账户额度、重置时间、Codex 重置券、单 Session Token,或高成本/多 Agent 工作要决定启动、并行、降级、延后或停止时,按需读取 Orca 账户快照与固定 ccusage 回执,区分状态、来源、可信度和未知值。不要用于低风险任务、轮询、自动调度/消费权益、账单推断或长期保存快照。Use for account capacity, reset times, credits, session tokens, or consequential resource decisions. Skip routine work, polling, scheduling, automatic credit use, billing inference, and durable snapshot storage.

★ 1
zaurakworks
zaurakworks/agent-system

orchestrated-collaboration

当用户明确要求多 Agent/多 Session/跨 Provider 协作、任务已授权委派,或活动 Session 发生共享写入碰撞时,建立目标来源、排他所有权、可追踪交付、独立验收与综合;按共享资源和 Issue 子树确定唯一协调者,只冻结重叠或受推翻假设影响的路径。协调者参与高价值多交付件能力的拆分或设计时,由未参与者复核父目标;使用已选后端,选 Orca 时动态读 orchestration 指南。不要因复杂、额度或空闲 Agent 擅自并行,也不把试用变成长期依赖。Use for authorized multi-agent work, cross-session delegation, or shared-write collisions. Establish exclusive ownership, traceable delivery, independent acceptance, and bounded synthesis; add parent-goal review when required and avoid invented coordination or permanent platform commitments.

★ 1
zaurakworks
zaurakworks/agent-system

knowledge-maintenance

用于多来源调研、可重复实验、会影响权威/Agent 配置/重要决定的研究,或用户要求复用、复核、更新当前知识时:先找已认可知识和失效条件,只补变化、冲突与缺口,再经价值门和可信门更新。不用于低成本一次性事实、原始材料/研发过程留存、私域结构设计、定时全量重查或旧仓导入。Use before multi-source research, repeatable experiments, consequential authority/configuration decisions, or explicit knowledge reuse. Skip cheap one-off facts, raw retention, private architecture, scheduled full re-research, and bulk legacy imports.

★ 1