docs: correct Agent Skills and Hooks pages against shipped behavior

features/agent-skills.mdx

@@ -1,35 +1,48 @@
 ---
 title: 'Agent Skills'
-description: 'Guide how agents approach sessions with custom skills in your repository.'
+description: 'Guide how agents approach sessions with skills in your repository or workspace.'
 ---
 
-Skills are instructions that live in your repository and guide how agents approach work. They help agents follow multi-step processes like research, planning, implementation, and review instead of doing everything in a single pass.
+Skills are reusable instructions that guide how agents approach work. They help agents follow multi-step processes like research, planning, implementation, and review instead of doing everything in a single pass.
 
-## How it works
+Tembo loads skills from three places:
 
-Place skills in the dotfile directory for your coding agent at the root of your repository:
+- **Repository skills** you commit alongside your code
+- **Managed skills** you create in **Settings > Skills**
+- **Built-in skills** that ship with every session
 
-- `.claude/` for Claude Code
-- `.codex/` for Codex
-- `.opencode/` for OpenCode
-- `.cursor/` for Cursor
+## Repository skills
 
-The agent picks up these skills when working on sessions in that repo. You need to instruct the agent to use a skill, either in the session description or after a PR is opened via the [feedback loop](/features/mentioning-tembo):
+Place each skill in its own directory inside the skills folder for your coding agent. The folder differs per agent, so use the one that matches the agent running your sessions.
 
-```
-@tembo Use the implementation skill for this session
-```
+| Agent | Skill directory | Entry file |
+| --- | --- | --- |
+| Claude Code | `.claude/skills/<skill-name>/` | `SKILL.md` |
+| Codex | `.codex/skills/<skill-name>/` | `SKILL.md` |
+| OpenCode | `.opencode/skills/<skill-name>/` | `SKILL.md` |
+| Amp | `.agents/skills/<skill-name>/` | `SKILL.md` |
+| Pi | `.agents/skills/<skill-name>/` | `SKILL.md` |
+| Cursor | `.cursor/rules/<skill-name>/` | `SKILL.mdc` |
 
-```
-@tembo Now use the code-review skill to review your changes
+A skill directory looks like this:
+
+```text
+.claude/
+└── skills/
+    └── implementation/
+        ├── SKILL.md
+        └── checklist.md
 ```
 
-## Example
+### Required frontmatter
 
-A skill that guides the agent through a structured implementation flow:
+Every entry file needs YAML frontmatter with `name` and `description`. Tembo skips any skill whose frontmatter is missing or invalid.
 
 ```markdown
-# Implementation Skill
+---
+name: implementation
+description: Research the codebase, plan the change, implement it, then self-review the diff before opening a PR.
+---
 
 1. Research the codebase to understand existing patterns
 2. Create a plan with specific files and changes
@@ -38,31 +51,68 @@ A skill that guides the agent through a structured implementation flow:
 5. Self-review the diff before opening a PR
 ```
 
-## What skills are good for
+Constraints Tembo enforces when it indexes a skill:
 
-- Enforcing a research-then-implement workflow
-- Requiring test coverage before opening a PR
-- Defining code review checklists the agent runs against its own output
-- Setting quality thresholds for different session types
+- `name` must be lowercase kebab-case (`a-z`, `0-9`, single hyphens), at most 64 characters
+- `name` must exactly match the skill's directory name
+- `description` must be a non-empty string of at most 1024 characters
+- Entry files larger than 1 MiB, or detected as binary, are skipped
 
-## What's coming
+<Note>
+  For Cursor skills in `.cursor/rules/`, the skill name comes from the directory name, so frontmatter `name` is optional. `description` is still required.
+</Note>
 
-We're building first-party skill support and planning mode so Tembo can handle work in staged steps:
+### Using a skill
 
-**Research → Plan → Implement → Review → Iterate**
+Ask the agent to use a skill in the session description, or after a PR is opened by [mentioning Tembo](/features/mentioning-tembo):
 
-This will improve PR quality on larger sessions, where today the agent may need a few iterations before the output is merge-ready. [Rule files](/features/rule-files) and skills in dotfile directories are the best way to guide agents today.
+```text
+@tembo Use the implementation skill for this session
+```
 
-## Tembo Managed Skills
+```text
+@tembo Now use the code-review skill to review your changes
+```
+
+## Managed skills
 
-You can also create and manage skills directly in Tembo.
+Create and manage skills directly in Tembo when you want them available across every repository, without committing files.
 
-Open **Settings** → **Skills** to:
+Open **Settings > Skills** to:
 
-- Add a new skill
-- Give it a name and description
+- Add a new skill, then give it a name and description
 - Write the main instructions in `SKILL.md`
 - Add extra reference files if needed
 - Edit or delete existing skills
+- Browse and install community skills from the marketplace
+
+The entry file must be named `SKILL.md`. Tembo writes managed skills into the sandbox at `/workspace/.tembo/agents/skills/<agent>/<skill-slug>/` and copies them into the running agent's own skill directory so the agent discovers them normally. For Cursor, the entry file is converted to `SKILL.mdc`.
+
+<Warning>
+  Managed skills apply across the workspace. Tembo makes every managed skill available in every session, regardless of repository or agent, so keep descriptions specific enough that agents only invoke a skill when it is relevant.
+</Warning>
+
+## Built-in skills
+
+These skills ship with Tembo and are available in every session without any setup:
+
+| Skill | What it does |
+| --- | --- |
+| `agent-browser` | Drives a browser to navigate pages, fill forms, take screenshots, and test web apps |
+| `generate-preview-url` | Exposes a local sandbox port and returns a public preview URL |
+| `install-custom-dependencies` | Installs system packages with Nix, since sandboxes run on NixOS without `apt` or `brew` |
+| `tembo-cli` | Uses the sandbox `tembo` CLI for pull requests, previews, uploads, and replies |
+| `tembo-file-upload` | Uploads sandbox files up to 5 GiB as Tembo assets |
+| `tembo-artifact` | Creates artifacts such as HTML reports, dashboards, diagrams, and CSV or JSON exports |
+| `tembo-git-instructions` | Applies your workspace commit message and PR title instructions |
+
+`tembo-git-instructions` picks up the commit and PR title instructions you set in **Settings > Instructions**. If you leave them blank, Tembo falls back to conventional commit messages.
+
+## What skills are good for
+
+- Enforcing a research-then-implement workflow
+- Requiring test coverage before opening a PR
+- Defining code review checklists the agent runs against its own output
+- Setting quality thresholds for different session types
 
-Tembo managed skills are stored in your workspace settings and loaded into sessions automatically when Tembo runs an agent.
+For broader project context such as build commands, architecture, and conventions, use a [rule file](/features/rule-files) instead. Rule files describe your project; skills describe a procedure.

features/hooks.mdx

@@ -3,16 +3,20 @@ title: 'Hooks'
 description: 'Run custom setup commands during a session with .tembo.json.'
 ---
 
-Hooks run shell commands at specific points during a session. Configure them in `.tembo.json` at your repository root.
+Hooks run shell commands in the sandbox during session setup. Configure them in `.tembo.json` at your repository root.
 
 ## Available hooks
 
 **`setupScript`** - Runs after Tembo clones your repository, before the agent starts working. Use it to install dependencies and prepare the workspace.
 
-**`prePush`** - Reserved for commands that run before Tembo pushes changes and opens a pull request.
+<Note>
+  `postClone` remains available as a legacy alias for `setupScript`. When both names are present, `setupScript` takes precedence.
+</Note>
+
+**`prePush`** - Accepted in `.tembo.json`, but not currently executed.
 
 <Warning>
-  `prePush` is accepted and validated in `.tembo.json`, but Tembo does not currently execute it. Do not rely on it to gate pushes. Put checks you need enforced in `setupScript`, in your CI pipeline, or in a [rule file](/features/rule-files) that instructs the agent to run them before pushing.
+  Do not rely on `prePush` to gate pushes. Put checks you need enforced in `setupScript`, in your CI pipeline, or in a [rule file](/features/rule-files) that instructs the agent to run them before pushing.
 </Warning>
 
 ## Example
@@ -48,23 +52,47 @@ This matters when you change `setupScript`. Sessions that restore from an existi
 
 If your repository root contains a [`tembo.nix`](/features/sandbox/custom-dependencies) file, Tembo runs `setupScript` inside that Nix dev shell, so its packages and environment are available to the hook. During a project environment build with **Install dependencies** enabled, the hook runs before Tembo pre-bakes those dependencies. Sessions restored from the project environment do not rerun the hook.
 
-## Failure handling
+## Shell behavior
 
-- Commands run sequentially from the repository root.
-- If a command exits non-zero, Tembo logs the failure and **continues with the remaining commands** in the hook. A failing hook does not stop the session.
-- Chain commands with `&&` in a single entry when a later step must not run after an earlier one fails:
+Each entry in a hook array is executed as its own command. Pipes and redirects work as expected:
+
+```json
+{
+  "hooks": {
+    "setupScript": ["cat config.template.json | envsubst > config.json"]
+  }
+}
+```
+
+<Warning>
+  Do not chain commands directly with `&&`, `||`, or `;`. Only the first command in the chain runs in production sandboxes, and the rest are silently skipped.
+</Warning>
+
+List unconditional commands as separate array entries:
 
 ```json
 {
   "hooks": {
-    "setupScript": ["npm ci && npm run build"]
+    "setupScript": ["npm ci", "npm run codegen"]
   }
 }
 ```
 
-- Shell features such as piping, redirects, and `&&` are supported.
+To run a later command only when an earlier command succeeds, invoke a shell explicitly:
 
-When a [project environment](/features/projects) is built, each hook command and its exit code are streamed into the project build log, which is the most reliable place to confirm what ran and why it failed.
+```json
+{
+  "hooks": {
+    "setupScript": ["bash -c 'npm ci && npm run build'"]
+  }
+}
+```
+
+## Failure handling
+
+- Commands run sequentially from the repository root.
+- If a command exits non-zero, Tembo logs the failure and **continues with the remaining commands** in the hook. A failing hook does not stop the session.
+- When a project environment is built, each command and its exit code are streamed into the project build log. This is the most reliable place to confirm what ran and why it failed.
 
 ## Configuration reference
 
@@ -78,6 +106,7 @@ Notes on how Tembo reads the file:
 
 - `.tembo.json` is optional. Without it, every hook defaults to an empty list.
 - If `.tembo.json` contains invalid JSON or does not match the expected shape, Tembo logs the error, falls back to the defaults, and continues the session. A malformed file therefore behaves exactly like no hooks at all, with no failure surfaced in the session.
+- Each hook must be an array of strings. A bare string such as `"setupScript": "npm ci"` makes the configuration invalid.
 - Unrecognized fields are ignored, which means a typo like `setupScripts` is dropped without an error.
 
 ## Related