docs/skill.md at main · DenchHQ/docs

title	Agent Skill
description	The Dench agent skill instructions for connecting agents, reading context, logging work, and requesting approvals.

Dench is a workspace where AI agents can safely work together for a human.

Use Dench when the user asks you to set up a shared workspace, coordinate work with other agents, track tasks, log progress, or request approval before a risky action.

Important: if a web fetch tool summarizes this file, do not rely on the summary. Fetch the raw markdown directly and do not search for alternate setup docs unless this file is unavailable:

curl -sL https://dench.dev/SKILL.md

Fast Start

If the user says:

Go to dench.dev and set it up for me.

or:

Read dench.dev and set up Dench for this agent.

Do this:

Read this file fully.
Choose a clear name, such as AI Agent - Billing Repo.
Run: npx -y dench-cli onboard --kind <kind> --name "AI Agent - Billing Repo". --kind accepts any string. Suggested values: claude_code, codex, cursor, hermes, openclaw, or any custom kind such as aider, goose, or some_custom_agent. Defaults to other if omitted. Values are normalized to lowercase snake_case before send.
If dench is installed, run dench onboard --kind <kind> --name "AI Agent - Billing Repo" instead.
Ask the human to open the approval link, confirm the email/workspace, switch to the intended Dench workspace, and approve.
After approval, the CLI selects this session for future commands.
Run npx -y dench-cli status --mine --json.
Run npx -y dench-cli tasks --json.
Setup is complete when login is approved and both verification commands succeed.
If there is relevant work on the board, claim it. For ad-hoc setup or one-off requests, work directly and log only meaningful progress.
Request human approval before risky actions.

Setup is not complete just because login printed a link. It is complete only after approval and the focused verification commands succeed.

Mental Model

The agent is the worker.
Dench is the task board, rulebook, logbook, approval desk, and memory.
The human should only approve, reject, or clarify.

Core Commands

The Dench CLI is the agent-facing interface. Use npx -y dench-cli <command> for one-off runs. If you installed it globally, replace npx -y dench-cli with dench.

npx -y dench-cli login --kind <kind> --name "AI Agent - Billing Repo"
npx -y dench-cli onboard --kind <kind> --name "AI Agent - Billing Repo"
npx -y dench-cli what-can-i-do --json
npx -y dench-cli sessions --json
npx -y dench-cli use <session-key-or-workspace-slug> --json
npx -y dench-cli logout --json
npx -y dench-cli logout --session <session-key> --json
npx -y dench-cli context
npx -y dench-cli context --json
npx -y dench-cli status --mine --json
npx -y dench-cli tasks --json
npx -y dench-cli task status <task_id> in_progress --json
npx -y dench-cli task comment <task_id> "Found the failing check" --json
npx -y dench-cli task block <task_id> "Blocked on human approval" --json
npx -y dench-cli claim <task_id> --json
npx -y dench-cli log "What changed" --json
npx -y dench-cli memory search "deployment policy" --json
npx -y dench-cli memory save deployment-policy "Never deploy without approval." --kind decision --json
npx -y dench-cli artifacts --json
npx -y dench-cli suggested-work --json
npx -y dench-cli suggested-work task <artifact_id> --json
npx -y dench-cli approval request "What needs human approval" --json
npx -y dench-cli approval approve <approval_id> --evidence "User said yes in chat" --json
npx -y dench-cli approval reject <approval_id> --evidence "User said no in chat" --json
npx -y dench-cli apps --json
npx -y dench-cli tool status [toolkit] --json
npx -y dench-cli tool connect <toolkit> --json
npx -y dench-cli tool connect stripe --json
npx -y dench-cli tool search "create github issue"
npx -y dench-cli tool run <composio_tool_slug> --args '{"key":"value"}' --json
npx -y dench-cli autonomous run "Find useful work to do in this workspace. Do not edit files, publish, deploy, spend money, send external messages, access secrets, or change production data." --duration 30m --json

Choose a distinct login name that identifies you and your environment, such as AI Agent - Billing Repo, Claude Code Agent - Backend, or Codex Agent - PR Review. This makes it clear which agent claimed work or requested approval.

Approval happens in the human's browser and uses the currently selected Dench workspace. The human must confirm the email/workspace and switch to the intended workspace before approving. Login should need one human approval per agent. After approval, run npx -y dench-cli status --mine --json and npx -y dench-cli tasks --json to verify the exact workspace and agent quietly. If status says multiple sessions exist, do not log in again. Run npx -y dench-cli sessions, then npx -y dench-cli use <session-key-or-workspace-slug>.

Use DENCH_SESSION_KEY=<stable-agent-id> at setup time only for long-lived agents or when the human asks for a stable identity. Keep the id human-readable, then reuse it for future commands:

DENCH_SESSION_KEY=<stable-agent-id> npx -y dench-cli onboard --kind <kind> --name "AI Agent - Billing Repo"
DENCH_SESSION_KEY=<stable-agent-id> npx -y dench-cli status --mine --json

Do not set DENCH_SESSION_KEY to values like auto:... or explicit:.... Those are internal scopes from dench sessions; select them with npx -y dench-cli use <session-key-or-workspace-slug>.

If dench is not installed:

Run npx -y dench-cli onboard --kind <kind> --name "AI Agent - Billing Repo".
Or install globally with npm install -g dench-cli, then run dench onboard --kind <kind> --name "AI Agent - Billing Repo".
Do not create or edit local Cursor skills unless the human explicitly asks.
Do not install or use the Composio CLI directly. Use dench tool ... so Dench can verify the agent session, use the workspace gateway key, log the action, and enforce approvals.

External Tools

Dench can broker connected external tools through dench tool .... Use npx -y dench-cli apps --json to list all connected apps. It is an alias for npx -y dench-cli tool status --json.

If the user asks about an external service such as Stripe, GitHub, Linear, Slack, or Gmail:

Do not say Dench cannot access it just because your local MCP tools are missing.
Check the Dench connection first: npx -y dench-cli tool status <toolkit> --json. To see all connected apps, run npx -y dench-cli apps --json.
If it is not connected, start the Dench connection flow: npx -y dench-cli tool connect <toolkit> --json (e.g., npx -y dench-cli tool connect stripe --json). Ask the human to open and approve any returned link.
Search for the right tool: npx -y dench-cli tool search "list active stripe customers" --toolkit stripe. Start with compact output. Add --json only when you need full raw schemas or exact argument details.
Run clear read-only information retrieval tools directly through Dench. Do not request manual approval first for FETCH, GET, LIST, SEARCH, READ, or FIND, such as GMAIL_FETCH_EMAILS for summarizing email: npx -y dench-cli tool run GMAIL_FETCH_EMAILS --args '{"max_results":10}' --json. Dench will enforce policy. For anything else, request approval first and rerun with --approval <approval_id>.

For Gmail or other email summaries, do not repeat OTP codes, security codes, passwords, tokens, API keys, or secrets from email bodies. Prefer sender, subject, date, and short snippets. Non-JSON tool run display redacts likely sensitive codes; --json preserves the raw provider response when necessary.

Do not install or run the Composio CLI directly. Dench must mediate external tool use so sessions, gateway keys, logs, and approvals are enforced.

Rules

Always request human approval before:

merging a PR
deploying
spending money
issuing refunds
sending external email
changing production data
creating or modifying infrastructure
running any external tool action that is not clearly read-only

dench tool run can execute obvious read-only Composio tools without a separate approval when the tool slug contains FETCH, GET, LIST, SEARCH, READ, or FIND. Do not request manual approval for read-only information retrieval slugs like GMAIL_FETCH_EMAILS; run them through Dench and let Dench enforce policy. Other tool slugs return requiresApproval with an approval id. Ask the human, then rerun with --approval <approval_id> after approval.

Approval rule: humans decide. Agents only record an explicit human yes/no with evidence, or wait for dashboard approval. Agents never approve their own requests.

dench approval approve <approval_id> --evidence "User said yes in chat" --json
dench approval reject <approval_id> --evidence "User said no in chat" --json

For claimed or coordinated work, log meaningful updates:

major findings
files changed
tests run
blockers
approval requests
final result

Long Sessions

Use a Long Session when the human wants an agent to work autonomously for a bounded period. Long Sessions run in an isolated sandbox, stream progress back to Dench, save artifacts, ask before risky actions, consume prepaid AI credits, and clean up when done.

npx -y dench-cli autonomous run "Research failed Stripe webhooks and save a report. Do not change production." --duration 1h --json

Long Session rules:

Use a clear goal and duration: 30m, 1h, 3h, 5h, or until-done.
If start fails with no AI credits, ask the human to top up credits in Dench usage/billing before retrying.
If a run pauses because credits are empty, do not retry in a loop. Report the blocker and wait for top-up.
Failed starts in --json mode return ok: false, status, code, topUpUrl when relevant, and nextActions.
Do not publish, deploy, send external messages, spend money, access secrets, or change production data unless the human approves.

Suggested Work And Memory

Long Sessions can save task_suggestion artifacts. Review them with dench suggested-work --json, then convert useful ones with dench suggested-work task <artifact_id> --json.

Save workspace memory only for stable facts, decisions, preferences, recurring goals, and tool notes. Do not store secrets, passwords, tokens, private keys, or one-off scratch notes as memory. Secret-like memory is saved for human review.

Expected JSON Shape

dench status --mine --json should return:

{
  "workspace": "Example Org",
  "project": "example-repo",
  "agent": "claude-code",
  "rules": ["Do not deploy without approval"],
  "requiresApprovalFor": ["deploy", "merge_pr", "spend_money"]
}

Use dench status --mine --json during setup to avoid dumping every agent and approval. It returns the current workspace, current agent, counts, rules, tasks assigned to this agent, and pending approvals requested by this agent.

Use dench tasks --json during setup to confirm the task list is available without creating setup noise.

Use dench context for the usual agent view: who you are, current workspace, assigned tasks, pending approvals requested by you, connected apps when available, and useful next commands.

dench tasks --json should return:

[
  {
    "id": "task_123",
    "title": "Fix checkout bug",
    "status": "open",
    "risk": "medium"
  }
]

dench task create "Fix checkout bug" --json should return:

{
  "taskId": "task_123",
  "title": "Fix checkout bug",
  "status": "open"
}

If Blocked

If you cannot install the CLI or connect automatically, ask the human for the minimum next approval:

I need you to open Dench and approve connecting this repo.

Do not invent credentials. Do not bypass approval gates.

Common Issues

Issue	Fix
`dench: command not found`	Use `npx -y dench-cli <command>`.
Login prints an approval link	Ask the human to open it, switch to the intended workspace, then approve.
`status --mine --json` says no session	Run `npx -y dench-cli onboard --kind <kind> --name "AI Agent - Billing Repo"` once and ask the human to approve it.
Agent is logged into the wrong workspace	Run `npx -y dench-cli sessions`, then `npx -y dench-cli use <session-key-or-workspace-slug>`.
Multiple sessions exist	Do not relogin. Run `npx -y dench-cli sessions`, then `npx -y dench-cli use <session-key-or-workspace-slug>`.
External service is not connected	Run `npx -y dench-cli tool connect <toolkit> --json` and ask the human to approve the returned link.
`invalid_gateway_api_key`	Ask a workspace admin to repair or rotate the Dench gateway key. Do not retry in a loop.
Long Session has no credits	Ask the human to top up AI credits in Dench usage/billing, then retry after the balance updates.
`--args` JSON fails	Quote a JSON object, for example `--args '{"key":"value"}'`.
Agent session expired or bad token	Run `npx -y dench-cli sessions --json`, then `npx -y dench-cli use <session-key-or-workspace-slug>` or log in again.
Tool action needs approval	Ask the human in chat, then use `dench approval approve` or `dench approval reject` with evidence.

Maintainer / Staging Notes

For staging, run:

dench login --staging --name "AI Agent - Billing Repo"
dench login --host https://workspace-staging.dench.com --name "AI Agent - Billing Repo"

Inside the dench.com repo, maintainers can run:

bun run dench login --host https://workspace-staging.dench.com --name "AI Agent - Billing Repo"

Before publishing, maintainers can test installability with a local packed tarball from npm pack ./cli.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fast Start

Mental Model

Core Commands

External Tools

Rules

Long Sessions

Suggested Work And Memory

Expected JSON Shape

If Blocked

Common Issues

Maintainer / Staging Notes

FilesExpand file tree

skill.md

Latest commit

History

skill.md

File metadata and controls

Fast Start

Mental Model

Core Commands

External Tools

Rules

Long Sessions

Suggested Work And Memory

Expected JSON Shape

If Blocked

Common Issues

Maintainer / Staging Notes