feat: add script creation standards and cross-platform guidance

[bmadcode]

Summary

• Add script-standards.md reference to both agent builder and workflow builder, enforcing Python-first scripts, PEP 723 inline metadata, uv run invocation, and cross-platform portability (macOS/Linux/Windows)
• Update build processes to auto-load script standards when built skills include scripts, and require explicit user approval for external dependencies
• Add scripts-in-skills.md explanation doc covering why deterministic scripts improve skill quality, cost, and reliability
• Update script-opportunities references to recommend Python over bash for logic, limiting shell to safe commands (git, gh, uv run, etc.)

Test plan

• CI passes
• Verify new docs render correctly in explanation index
• Confirm both builder build-process files reference script-standards correctly

Summary by CodeRabbit

• Documentation
  • Added comprehensive guide on implementing deterministic scripts in skills, establishing Python as the default cross-platform language.
  • Established new script creation standards including PEP 723 metadata requirements and dependency management guidelines.
  • Updated script opportunity guidance to prioritize Python logic over Bash, limiting shell usage to safe commands only.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

This PR introduces comprehensive standards and documentation for deterministic script usage in skills. It adds a new "Scripts in Skills" explanation page, establishes cross-platform script creation standards for both agent-builder and workflow-builder skills, updates build processes to enforce dependency approval and reference these standards, and shifts the default scripting approach from Bash-first to Python-first with restricted shell access.

Changes

Cohort / File(s)	Summary
Explanation Documentation docs/explanation/index.md, docs/explanation/scripts-in-skills.md	Added new documentation page explaining deterministic scripts in skills, covering the determinism boundary, Python vs. Bash trade-offs, PEP 723 inline metadata, and graceful degradation behavior. Linked from the Design Patterns table.
Agent Builder Scripts Configuration skills/bmad-agent-builder/build-process.md, skills/bmad-agent-builder/references/script-opportunities-reference.md, skills/bmad-agent-builder/references/script-standards.md	Established Python-first scripting standard with restricted shell access (only safe commands: git, gh, uv run, package managers, mkdir -p). Added mandatory dependency approval step in build process and conditional loading of script-standards.md when scripts are included. New reference document defines PEP 723 metadata, shebangs, uv run invocation, graceful degradation, and standardized script interfaces.
Workflow Builder Scripts Configuration skills/bmad-workflow-builder/build-process.md, skills/bmad-workflow-builder/references/script-opportunities-reference.md, skills/bmad-workflow-builder/references/script-standards.md	Applied identical Python-first scripting standards and cross-platform script conventions as agent-builder. Updated build process for dependency approval and script-standards reference loading. Established consistent script packaging and interface requirements.

Possibly related PRs

• Refactor/flatten skill structure #30: Directly modifies script guidance and standards documentation with overlapping paths (script-standards.md, script-opportunities-reference.md, build-process.md).
• refactor: outcome-driven overhaul of builder and quality analysis pipeline #43: Updates script-related documentation for BMad skills with conceptual and file-level overlap in script standards, PEP 723, and uv run conventions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

---

🐰 Scripts now speak Python clear,
Bash takes a step back here,
PEP 723 metadata neat,
Cross-platform, complete!
Hopping toward standards most sweet. 🎉

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main changes: adding script creation standards documentation and cross-platform guidance. It directly reflects the core objective of establishing Python-first, PEP 723-compliant script standards across both builders.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch script-guidance

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[augmentcode]

🤖 Augment PR Summary

Summary: This PR strengthens guidance around using deterministic scripts inside skills, with an emphasis on cross-platform portability and predictable execution.

Changes:

• Adds a new explanation doc: Scripts in Skills, describing when to script vs prompt, and why Python is preferred over bash.
• Introduces script-standards.md references for both the agent builder and workflow builder, outlining PEP 723 metadata, shebang conventions, and uv run usage.
• Updates both builders’ build processes to auto-load script standards when scripts are part of the output.
• Updates script opportunity references to recommend Python-first logic and to avoid non-portable bash pipelines/utilities.
• Requires explicit user approval when scripts need external Python dependencies beyond the stdlib.

Technical Notes: The standards formalize PEP 723 inline metadata + uv run execution to enable cached, isolated dependency resolution and more deterministic skill behavior across macOS/Linux/Windows.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

[augmentcode]

In skills/bmad-agent-builder/references/script-standards.md line 13, listing mkdir -p as “works reliably across all environments” isn’t correct for Windows-native shells (PowerShell/cmd don’t support -p). This could cause generated skills to fail if they follow the “safe bash commands” list on Windows.

Severity: medium

Other Locations

• skills/bmad-workflow-builder/references/script-standards.md:13
• docs/explanation/scripts-in-skills.md:57

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[augmentcode]

In skills/bmad-agent-builder/references/script-standards.md line 65, the guidance uses python3 ... for stdlib-only scripts, but python3 isn’t a reliable command on Windows-native installs (often python or py). Since the doc claims native Windows support, these examples may break when followed verbatim.

Severity: medium

Other Locations

• skills/bmad-workflow-builder/references/script-standards.md:65
• docs/explanation/scripts-in-skills.md:63
• docs/explanation/scripts-in-skills.md:110
• skills/bmad-workflow-builder/references/script-standards.md:47
• skills/bmad-agent-builder/references/script-standards.md:47
• skills/bmad-workflow-builder/references/script-standards.md:77

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}