Skip to content

docs: correct Agent Skills and Hooks pages against shipped behavior #681

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tembo wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: correct Agent Skills and Hooks pages against shipped behavior #681

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 82 additions & 32 deletions features/agent-skills.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/feedback-loop):
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
Expand All @@ -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 via the [feedback loop](/features/feedback-loop):

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>
Every skill in your workspace is loaded into every session for that workspace. There is no per-repository or per-agent filtering, 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.
108 changes: 94 additions & 14 deletions features/hooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
---
title: 'Hooks'
description: 'Run custom commands at lifecycle events like post-clone and pre-push.'
description: 'Run setup commands in the sandbox before an agent starts working.'
---

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

**`postClone`** - Runs after Tembo clones your repo, before it starts working.
**`postClone`** - Runs after your repositories are ready and before the agent starts working. Use it for dependency installs and other one-time setup.

**`prePush`** - Runs after Tembo makes changes, before pushing and opening a PR.
<Note>
`prePush` is accepted in `.tembo.json` for backwards compatibility, but it is not executed today. Commands placed there never run. Use `postClone` for setup, and run linters, tests, and builds from your CI or by instructing the agent directly.
</Note>

## Example

Expand All @@ -19,19 +21,97 @@ Hooks run shell commands at specific points during a session. Configure them in
"postClone": [
"npm ci",
"cp .env.example .env.local"
],
"prePush": [
"npm run lint",
"npm run test",
"npm run build"
]
}
}
```

## Details
`hooks` is the only supported top-level key. Any other key is ignored.

- Commands run sequentially in the repository root
- If a command fails, Tembo logs the failure and continues with the remaining commands in the hook
- Hooks run in the same [sandbox](/features/sandbox/overview) as the session
- Shell features (piping, redirects, `&&`) are supported
## When postClone runs

`postClone` runs during session setup, after Tembo configures git credentials, refreshes your repositories, and sets up MCP servers, and before it builds the prompt and starts the agent.

It also runs when Tembo builds a [snapshot](/features/snapshots), so dependencies installed by the hook are baked into the snapshot image.

<Warning>
`postClone` is skipped when a sandbox resumes from a snapshot, because the snapshot already contains the state the hook would have produced. If you rely on a hook for something that must happen every session, such as writing a short-lived credential, it will not run on resumed sessions.
</Warning>

## Shell behavior

Each entry in a hook array is executed as its own command. Pipes and redirects work as expected:

```json
{
"hooks": {
"postClone": ["cat config.template.json | envsubst > config.json"]
}
}
```

<Warning>
Do not chain commands with `&&`, `||`, or `;`. Only the first command in the chain runs, and the rest are silently dropped with no error.
</Warning>

List each command as a separate array entry instead:

```json
{
"hooks": {
"postClone": ["npm ci", "npm run codegen"]
}
}
```

If you genuinely need conditional chaining inside one command, wrap it in an explicit shell:

```json
{
"hooks": {
"postClone": ["bash -c 'npm ci && npm run codegen'"]
}
}
```

## Failure behavior

- Commands run sequentially in the sandbox
- A command that exits non-zero is logged, and the remaining commands still run
- A failing hook does not fail the session, and the agent starts either way

Because failures are non-fatal and easy to miss, avoid chaining critical setup steps and assuming they all succeeded.

## Working with tembo.nix

If your repository has a [`tembo.nix`](/features/sandbox/custom-dependencies) file, hook commands run inside that Nix dev shell, so any toolchain you declare there is on `PATH`.

To do this Tembo temporarily replaces `flake.nix` with the contents of `tembo.nix` while the hook runs, then restores the original afterwards. If your repository already has its own `flake.nix`, hooks run against the `tembo.nix` dev shell rather than yours.

When dependencies are already pre-built into a snapshot, Tembo reuses the saved environment instead of re-entering the dev shell.

## Troubleshooting

**Hooks did not run at all.** If `.tembo.json` is not valid JSON, or does not match the expected shape, Tembo logs the problem and falls back to defaults, which means no hooks run. Validation is all-or-nothing, so a single malformed entry disables every hook in the file. Check that each hook is an array of strings:

```json
{
"hooks": {
"postClone": ["npm ci"]
}
}
```

A common mistake is passing a bare string instead of an array:

```json
{
"hooks": {
"postClone": "npm ci"
}
}
```

**Hooks did not run on a follow-up session.** The sandbox likely resumed from a snapshot. See the warning above.

**A dependency is missing.** Add the toolchain to [`tembo.nix`](/features/sandbox/custom-dependencies) rather than installing it with `apt` or `brew`, which are not available in the sandbox.