Build the Workspace Brief extension

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.

1. Create the package layout

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

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

{
  "$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:

{
  "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:

{
  "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:

---
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

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.

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:

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.

8. Invoke the workflow

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

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

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, which adds a native slash command, Ink UI, shortcut, flags, hooks, provider, and permission policy.