docs: correct Agent Skills and Hooks pages against shipped behavior

[tembo]

Documentation-only. Both repo-level configuration pages described behavior that does not match the current implementation, in ways that fail silently — users following the docs today get skills that are never discovered and hook commands that never run.

Every claim below was verified against source in the tembo/monorepo checkout. No behavior was inferred.

Docs updated

features/agent-skills.mdx (rewritten)

Issue	Before	Now
Skill layout	Listed only dotfile dirs (.claude/, .codex/, …)	Documents the required <dotdir>/skills/<skill-name>/SKILL.md layout
Cursor path	.cursor/	.cursor/rules/<skill-name>/SKILL.mdc
Missing agents	—	Adds .agents/ (Amp, Pi)
Frontmatter	Example had none, so it would be skipped	Documents required name/description + constraints
Roadmap	"We're building first-party skills and planning mode"	Removed — both shipped
Managed skills	"loaded automatically"	Documents SKILL.md requirement, sandbox path, Cursor conversion, and that all workspace skills load into every session
Built-in skills	Undocumented	Table of the 7 shipped skills

features/hooks.mdx (rewritten)

• prePush never runs. It still parses, but has zero live call sites — the only invocations are commented-out legacy code. Previously documented as a working hook with a lint/test/build example.
• && chaining silently truncates. The page previously stated "Shell features (piping, redirects, &&) are supported". The exec wrapper emits exec <command> as the final line of a bash script, so exec npm ci && npm run codegen runs only npm ci and drops the rest with no error. Replaced with the correct guidance (separate array entries, or an explicit bash -c). Pipes and redirects do work and are documented as such.
• postClone is skipped on snapshot resume, which was entirely undocumented.
• Malformed .tembo.json silently disables all hooks — validation is all-or-nothing and falls back to defaults. Added to troubleshooting with the common string-instead-of-array mistake.
• Documents the tembo.nix dev shell interaction (flake.nix is temporarily swapped and restored) and that hook failures are non-fatal.

Codepaths covered

• apps/api/src/agent/sandbox/temboConfig.ts — .tembo.json schema, parse fallback, runHook, prepareHookEnvironment
• apps/api/src/agent/worker/tasks/agent_run/index.ts + worker/sandboxTask.ts — postClone call site and didResumeFromSnapshot() skip condition
• apps/api/src/agent/sandbox/sandboxExecWrapper.ts — exec wrapper (the && truncation)
• apps/api/src/agent/worker/skills.ts — repo skill discovery regexes and frontmatter validation
• packages/agent-runtime/src/runtime/harness/*/definition.ts + registry.ts — per-agent skillDir/entryFilename
• packages/agent-runtime/src/runtime/skills/index.ts + apps/api/src/agent/sandbox/utils.ts — built-in skills and managed-skill materialization

Validation

• mintlify broken-links passes site-wide
• Frontmatter present on both pages; both already in docs.json nav (no nav changes)
• && truncation reproduced directly in bash against a replica of the generated wrapper script
• Branch is even with origin/main; merge dry-run reports no conflicts

Knowledge gaps addressed

Both pages now describe failure modes that are invisible at runtime: a skill in the wrong directory or missing frontmatter, a prePush block that no-ops, a && chain that half-executes, and a typo'd .tembo.json that disables everything. None surfaced an error to the user before.

---

⚠️ Suspected product bug found while verifying — deliberately not documented

In the live agent_run task, TemboConfig.loadFromSandbox reads .tembo.json from sandbox.getCwd(), which is still the default /workspace — agent_run uses setupGit + tembo-refresh-repos and never calls cloneRepo, which is the only thing that would setCwd to the repo directory. Repos live at /workspace/<repo-name>/.

If that reading is right, a .tembo.json committed at a repo root is never found during normal sessions — only the golden-snapshot build path (services/hypervisor/qemu/prepare.ts) sets cwd per-repo and would pick it up. This looks like a regression from the solve_issue → agent_run migration rather than intended behavior, so I left the "repository root" guidance in place instead of documenting a likely bug. Worth confirming with the owning engineer; if it is a bug, the hooks page needs no further change once fixed.

Also noted, out of scope for this PR: features/rule-files.mdx describes a nine-file precedence list that no code in the monorepo implements (discovery is delegated to each agent CLI), and features/max.mdx is orphaned from docs.json navigation.

Want tembo to make any changes? Add a comment with @tembo and i'll get back to work!

      

---

Note

Low Risk
Mintlify MDX documentation only; no application code or runtime behavior changes.

Overview
Documentation-only update to features/agent-skills.mdx and features/hooks.mdx so they match how Tembo actually loads skills and runs hooks—addressing silent failures when users follow the old guidance.

Agent Skills now documents three skill sources (repo, managed, built-in), per-agent directory layouts (including Cursor SKILL.mdc and .agents/ for Amp/Pi), required frontmatter and indexing rules, managed-skill sandbox paths and workspace-wide loading, a table of seven built-in skills, and removes outdated “coming soon” planning-mode copy.

Hooks reframes hooks as sandbox setup (postClone only in practice): prePush is documented as non-executing (back-compat only), with examples no longer suggesting lint/test on pre-push. New sections cover when postClone runs (including snapshots), skip on snapshot resume, &&/||/; chaining pitfalls vs separate array entries or bash -c, non-fatal failures, tembo.nix / flake.nix swap during hooks, and troubleshooting for invalid .tembo.json (all-or-nothing validation).

^{Reviewed by Cursor Bugbot for commit c8e0363. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tembo	🟢 Ready	View Preview	Aug 7, 2026, 8:20 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[tembo]

Requesting review from @benja who has experience with the following files modified in this PR:

• features/hooks.mdx
• features/agent-skills.mdx