---
title: "Build the Workspace Brief Extension"
source: https://docs.autohand.ai/tutorials/extensions/workspace-brief-extension
---

# Build the Workspace Brief extension

Pair deterministic Git evidence with a portable Agent Skill so users can invoke one repeatable $workspace-brief workflow without trusting package code.

## Pattern under test

This package demonstrates the declarative tool-plus-skill pattern. The tools collect current repository evidence; the skill tells the model how to turn that evidence into a concise briefing without confusing inference with proof.

| Contribution | Responsibility | Security boundary |
|---|---|---|
| brief_workspace_status | Show the current short Git status. | Shell-backed tool using normal permission flow. |
| brief_recent_commits | Show a caller-bounded recent commit list. | Required numeric parameter is shell escaped. |
| $workspace-brief | Use both tools and produce an evidence-backed summary. | Portable instructions; no package code execution. |

## 1\. Create the package layout

``` bash
mkdir -p autohand.workspace-brief/tools
mkdir -p autohand.workspace-brief/skills/workspace-brief
cd autohand.workspace-brief
```

``` text
autohand.workspace-brief/
  autohand.extension.json
  README.md
  tools/
    workspace-status.json
    recent-commits.json
  skills/
    workspace-brief/
      SKILL.md
```

Every contribution file must be declared in the manifest. The skill may later add references or scripts inside its own directory, but keep the first version small enough to review in one pass.

## 2\. Declare tools and skill

``` json
{
  "$schema": "https://raw.githubusercontent.com/autohandai/code-extensions/main/schema/autohand.extension.schema.json",
  "schemaVersion": 1,
  "extensionApi": 1,
  "id": "autohand.workspace-brief",
  "name": "Workspace Brief",
  "version": "1.0.0",
  "description": "Gather a concise workspace snapshot and guide evidence-based project briefings.",
  "license": "Apache-2.0",
  "repository": "https://github.com/autohandai/code-cli",
  "contributes": {
    "tools": [
      "tools/workspace-status.json",
      "tools/recent-commits.json"
    ],
    "skills": [
      "skills/workspace-brief/SKILL.md"
    ]
  }
}
```

`schemaVersion` and `extensionApi` are exactly `1`. The qualified id is the installed identity. Because `contributes.runtime` is absent, this package does not require `--trust`.

## 3\. Add the workspace status tool

Create `tools/workspace-status.json`:

``` json
{
  "name": "brief_workspace_status",
  "description": "Show the current Git workspace status for a project briefing",
  "parameters": {
    "type": "object",
    "properties": {}
  },
  "handler": "git status --short",
  "source": "user"
}
```

The tool takes no caller input. It reports working-tree state but does not claim whether individual changes are correct, staged, reviewed, or ready to ship.

## 4\. Add bounded commit history

Create `tools/recent-commits.json`:

``` json
{
  "name": "brief_recent_commits",
  "description": "Show a bounded number of recent commits for a project briefing",
  "parameters": {
    "type": "object",
    "properties": {
      "count": {
        "type": "number",
        "description": "Maximum number of recent commits"
      }
    },
    "required": ["count"]
  },
  "handler": "git log --max-count={{count}} --oneline",
  "source": "user"
}
```

The required placeholder prevents a partial command. The model chooses a reasonable count, the renderer shell-escapes it, and the resulting command still passes through the active permission policy.

## 5\. Write the Agent Skill

Create `skills/workspace-brief/SKILL.md`:

``` markdown
---
name: workspace-brief
description: Build a concise, evidence-backed briefing from workspace status and recent commits.
---

# Prepare a workspace brief

Use `brief_workspace_status` and `brief_recent_commits` before writing the brief.
Summarize active changes, recent direction, immediate risks, and the next concrete action.
Distinguish observed repository evidence from inference and do not claim the workspace is clean without checking.
```

The exact name becomes the `$workspace-brief` invocation. The skill names both extension tools and defines the reporting contract, but it does not grant permission or force a tool call to succeed.

## 6\. Validate without executing tools

``` bash
autohand extensions validate .
autohand extensions validate . --json
```

Validation parses the manifest, verifies contained paths, validates both tool schemas and the skill entrypoint, and reports names without running either Git command.

**Expected:** a valid package with two tools, zero agents, one skill, and zero runtime entrypoints.

Before continuing, deliberately remove `count` from the tool's `required` list and confirm validation fails because the handler placeholder would be optional. Restore the valid definition.

## 7\. Install at project scope

Use a development link while iterating:

``` bash
autohand --path /work/example extensions install . --scope project --link
autohand --path /work/example extensions show autohand.workspace-brief --scope project
autohand --path /work/example extensions doctor
```

The project registry stores linked state under `/work/example/.autohand/extensions`. Removing the installed link later does not delete this source directory.

**Do not add `--trust`.** This package has no runtime entrypoint. Its tools and skill use the declarative layer.

## 8\. Invoke the workflow

Start a fresh Autohand session in the target repository and prompt:

$workspace-brief summarize the current project state and identify the next concrete action

Confirm the agent requests both tools, permission prompts match your policy, and the final brief separates these categories:

-   Observed working-tree changes from `git status --short`.
-   Observed recent direction from the bounded commit list.
-   Risks or intent explicitly labeled as inference.
-   One concrete next action grounded in the evidence.

Deny one tool call and confirm the briefing reports missing evidence instead of claiming a clean or current repository state.

## 9\. Prove disable, enable, copy, and removal

``` bash
autohand --path /work/example extensions disable autohand.workspace-brief --scope project
autohand --path /work/example extensions enable autohand.workspace-brief --scope project
autohand --path /work/example extensions remove autohand.workspace-brief --scope project --yes

# Release-style copied installation:
autohand --path /work/example extensions install . --scope project
autohand --path /work/example extensions show autohand.workspace-brief --scope project
```

After disable, both tools and the `$workspace-brief` skill must disappear together. The copied install must work from a fresh process even if the authoring directory is moved away.

## What you learned

-   Used the safe declarative layer for bounded Git evidence and reusable workflow instructions.
-   Designed a required parameter around bounded output.
-   Kept a skill's reporting rules separate from deterministic tool execution.
-   Validated without execution and exercised normal permission denial.
-   Proved project scope, linked development, copied release behavior, and lifecycle cleanup.

Next, compare this package with the [trusted runtime extension](/tutorials/extensions/build-runtime-extension.html), which adds a native slash command, Ink UI, shortcut, flags, hooks, provider, and permission policy.