feat(cli): embed the BAML agent skill

[codeshaunted]

Summary

• move the canonical BAML skill into the monorepo and embed it in baml-cli
• make baml agent install network-free and inject the binary canonical version into the installed skill frontmatter
• compare metadata.baml-toolchain-version with the active toolchain version; missing, malformed, or different metadata is outdated
• retain BoundaryML/baml-skill as legacy-only for older toolchains

Testing

• cargo check -p baml_cli
• cargo test -p baml_cli --lib agent_command::tests::
• cargo test -p baml_cli --lib skill_check::tests::
• cargo test -p baml_cli --lib commands::tests::
• cargo test -p baml_cli --test agent_install_e2e --test skill_warning_e2e
• cargo test -p baml_cli --test exit_code_e2e run_valid_project_outputs_only_program_output -- --exact
• cargo test -p baml_release
• cargo clippy -p baml_cli --all-targets -- -D warnings
• repository pre-commit hooks

Summary by CodeRabbit

• New Features

  • baml agent install now installs the bundled baml-core skill without network access.
  • Added comprehensive BAML guidance covering syntax, LLM functions, schemas, testing, concurrency, and workflows.
  • Skill checks now validate installed toolchain versions locally and warn when skills are missing or outdated.
  • Existing skills are archived before replacement.

• Documentation

  • Added guidance for maintaining and distributing bundled skills.

• Bug Fixes

  • Improved installation reliability in offline environments.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
beps	Ready	Preview	Aug 29, 2026 1:05am
promptfiddle2	Ready	Preview	Aug 29, 2026 1:05am

[github-actions]

⏭️ Performance benchmarks were skipped

Perf benchmarks (CodSpeed) are opt-in on pull requests — they no longer run on every push. They always run automatically after merge to canary/main.

To run them on this PR, do any of the following, then push a commit (or re-run CI):

• Add RUN_CODSPEED=1 to the PR description, or
• Include run-perf or /perf in the PR title or any commit message.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b5e67eb7-285f-400b-9393-5d3df2a5e902

📥 Commits

Reviewing files that changed from the base of the PR and between 1445fda and 8823662.

⛔ Files ignored due to path filters (1)

• baml_language/crates/baml_cli/src/snapshots/baml_cli__help_command__tests__root_concise_help.snap is excluded by !**/*.snap

📒 Files selected for processing (1)

• .gitattributes

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The CLI now embeds a versioned baml-core agent skill. Installation renders the toolchain version into the skill and writes it directly. Skill checks parse local frontmatter and compare its version without remote downloads or provenance caches.

Changes

Embedded BAML agent skill

Layer / File(s)	Summary
Embedded skill asset and contracts skills/*, baml_language/crates/baml_cli/Cargo.toml, baml_language/crates/baml_cli/src/agent_command.rs	The repository adds the baml-core skill guide with a toolchain-version placeholder. Archive dependencies, archive-loading types, and the --source option are removed.
Embedded installation flow baml_language/crates/baml_cli/src/agent_command.rs	baml agent install renders and installs the bundled skill directly. Replaced skills remain in baml-old_skills. Commit provenance handling is removed.
Local skill status and command wiring baml_language/crates/baml_cli/src/skill_check.rs, baml_language/crates/baml_cli/src/commands.rs, baml_language/crates/baml/src/main.rs	Skill status now compares parsed baml-toolchain-version frontmatter with baml_version::CANONICAL_VERSION. Authoring commands run the check synchronously. Related documentation comments are updated.
Local status and installation validation baml_language/crates/baml_cli/tests/*	Tests cover rendered content, missing and stale skills, matching skills, parent-path lookup, archived skills, isolated HOME, and installation behavior.
Embedded skill documentation skills/README.md, .gitattributes	The README documents embedded compilation and the legacy skill repository. Skill files use LF line endings.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 88236

This PR embeds the BAML agent skill and updates installation and freshness behavior without any identified merge-blocking risk; it is ready to merge after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant CLI as baml-cli
  participant Check as skill_check::check
  participant Filesystem
  participant Installer as AgentInstallArgs

  CLI->>Check: check before init, run, generate, or pack
  Check->>Filesystem: read SKILL.md frontmatter
  Filesystem-->>Check: baml-toolchain-version
  Check-->>CLI: report missing or outdated skill
  CLI->>Installer: run agent install
  Installer->>Filesystem: write rendered baml-core SKILL.md

Loading

Suggested reviewers: sxlijin

Poem

A rabbit checks the versioned guide
A bundled skill is placed inside
Old skills rest away
Fresh frontmatter leads the way
No remote archive needs a ride

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 52.17% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 46 functions across 8 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: embedding the BAML agent skill in the CLI.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 52.17% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 46 functions across 8 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/toolchain-owned-skill

---

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.}

[github-actions]

Binary size checks passed

✅ 7 passed

	Artifact	Platform	File	Gzip	Gated on	Baseline	Delta	Status
✅	baml-cli	Linux	🔒 72.6 MB	27.4 MB	file	72.9 MB	-237.2 KB (-0.3%)	OK
✅	packed-program	Linux	🔒 28.6 MB	10.9 MB	file	28.6 MB	+19.2 KB (+0.1%)	OK
✅	baml-cli	macOS	🔒 63.2 MB	25.0 MB	file	63.3 MB	-182.2 KB (-0.3%)	OK
✅	packed-program	macOS	🔒 25.8 MB	10.2 MB	file	25.8 MB	+38.5 KB (+0.1%)	OK
✅	baml-cli	Windows	🔒 82.8 MB	27.8 MB	file	83.0 MB	-251.2 KB (-0.3%)	OK
✅	packed-program	Windows	🔒 30.9 MB	10.7 MB	file	30.9 MB	-23.9 KB (-0.1%)	OK
✅	bridge_wasm	WASM	22.2 MB	🔒 5.7 MB	gzip	5.7 MB	+13.0 KB (+0.2%)	OK

🔒 = the size this artifact is GATED on (ceiling + delta). Binaries gate on file size (installed binary); WASM gates on gzip (download size). The other size is shown for information only.

---

Generated by cargo size-gate · workflow run