---
title: "Build Your First Extension with $extension-builder"
source: https://docs.autohand.ai/tutorials/extensions/authoring-your-first-extension
---

# Build your first extension with `$extension-builder`

Use Autohand Code's built-in authoring skill to create a complete acme.code-health package with a safe tool, focused agent, and reusable $code-health-review Agent Skill—then inspect and prove every generated file.

## Before you begin

Complete this tutorial in an initialized Git repository that is safe to modify. The finished extension is declarative, project-scoped, and does not require the trusted runtime layer.

### Prerequisites

-   A current Autohand Code CLI with the `autohand extensions` command tree.
-   Git and a repository containing at least one tracked source file.
-   A normal interactive permission policy so you can verify approval and denial behavior.
-   About 15 minutes with `$extension-builder`, or 30 minutes for the manual path.

### Learning objectives

After completing this tutorial, you can:

-   Choose the declarative extension layer for tools, agents, and Agent Skills.
-   Generate an extension with `$extension-builder` and review every generated contribution.
-   Validate, link, invoke, disable, enable, copy-install, and remove an extension.
-   Prove that a contributed skill appears in `/skills` and follows the normal permission path.

**Important:** Generated files are a starting point, not validation evidence. Review the manifest, handler, agent prompt, and skill instructions before installation.

## What you will build

``` text
acme.code-health/
  autohand.extension.json
  README.md
  tools/
    find-todos.json
  agents/
    code-health-reviewer.md
  skills/
    code-health-review/
      SKILL.md
```

The tool runs a bounded `git grep`. The agent provides a callable specialist. The skill gives users one repeatable `$code-health-review` workflow that gathers evidence before reporting findings.

**Architecture:** the manifest discovers the package, the tool gathers bounded evidence, the agent provides specialist reasoning, and the skill defines the repeatable user workflow.

## Fast path: ask the built-in extension builder

Start Autohand in the repository you want to extend. Autohand Code already bundles `$extension-builder`, so mention it exactly in the prompt:

``` text
$extension-builder create a declarative project extension named acme.code-health.
Add a safe find_todos tool that searches a repository-relative path, a focused
code-health-reviewer agent, and a code-health-review Agent Skill that gathers
evidence before reporting maintainability risks. Write the complete package to
./acme.code-health. Do not install it yet. Show me what to review and the exact
validation command.
```

The exact `$extension-builder` mention activates the authoring workflow in that turn. It should choose the declarative layer because this package needs only a bounded shell-backed tool, an agent prompt, and a portable skill—no trusted runtime code.

**Review the result, do not treat generation as proof.** Compare the generated package with the files below, inspect every handler and instruction, then validate and exercise the lifecycle yourself. The authoring skill does not bypass validation, permissions, or installation trust.

If your team manages the authoring workflow as a project skill instead of using the bundled copy, install the community version explicitly:

``` bash
npx skills add https://github.com/autohandai/community-skills \
  --skill extension-builder -a autohand-code -y
```

## 1\. Create the package directories

``` bash
mkdir -p acme.code-health/tools acme.code-health/agents
mkdir -p acme.code-health/skills/code-health-review
cd acme.code-health
```

Skip this command if `$extension-builder` already created the package. The directory name does not control identity during validation, but matching the manifest id keeps checkouts, install roots, and diagnostics easy to compare.

## 2\. Write the manifest

Create `autohand.extension.json`:

``` json
{
  "$schema": "https://raw.githubusercontent.com/autohandai/code-extensions/main/schema/autohand.extension.schema.json",
  "schemaVersion": 1,
  "extensionApi": 1,
  "id": "acme.code-health",
  "name": "ACME Code Health",
  "version": "1.0.0",
  "description": "Find maintainability risks and delegate focused code-health reviews.",
  "license": "Apache-2.0",
  "repository": "https://github.com/acme/code-extensions",
  "contributes": {
    "tools": ["tools/find-todos.json"],
    "agents": ["agents/code-health-reviewer.md"],
    "skills": ["skills/code-health-review/SKILL.md"]
  }
}
```

Both version fields must be the number `1`. The package version must be strict numeric semver. Every path uses forward slashes and stays inside the package root.

## 3\. Add the tool

Create `tools/find-todos.json`:

``` json
{
  "name": "find_todos",
  "description": "Find TODO and FIXME comments under a path tracked by Git",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Repository-relative file or directory"
      }
    },
    "required": ["path"]
  },
  "handler": "git grep -n -E 'TODO|FIXME' -- {{path}}",
  "source": "user"
}
```

The placeholder name matches the required schema property. Autohand shell-escapes the value at invocation, but the handler remains intentionally narrow: callers select a path, not an arbitrary command.

## 4\. Add the specialist agent

Create `agents/code-health-reviewer.md`:

``` markdown
---
description: Review maintainability risks and prioritize focused cleanup
tools: read_file, fff_grep, find_todos
---
Review the requested code for correctness, unnecessary complexity, stale TODOs,
duplication, and maintainability risks. Preserve working contracts. Return a
prioritized set of specific findings with file evidence and the smallest safe
remediation for each finding.
```

The file name becomes `code-health-reviewer`. Its allowlist includes the extension tool but does not grant permission to run it; the active registry and permission manager still decide availability and approval.

## 5\. Add the reusable Agent Skill

Create `skills/code-health-review/SKILL.md`:

``` markdown
---
name: code-health-review
description: Review maintainability risks with repository evidence. Use when a user asks for code-health, TODO, FIXME, cleanup, or maintainability analysis.
---

# Review code health

1. Run `find_todos` against the requested repository-relative path.
2. Read the files around each relevant match before drawing a conclusion.
3. Separate observed evidence from inference.
4. Return prioritized findings with file evidence, impact, and the smallest safe remediation.

Do not edit files unless the user explicitly asks.
Do not claim the repository is clean when a tool call was denied or failed.
```

The frontmatter `name` becomes the exact `$code-health-review` invocation. The description explains both what the skill does and when it should activate. Keep the body procedural and concise; add `references/`, `scripts/`, or `assets/` inside this skill directory only when the workflow genuinely needs them.

The extension manifest declares only the `SKILL.md` entrypoint. Enabled extension skills appear in `$` suggestions and `/skills`; disabling or removing the extension removes them from the active runtime snapshot.

## 6\. Add operator instructions

Create a README that states purpose, requirements, exact contributions, expected permission prompts, install commands, and removal. At minimum include:

``` markdown
# ACME Code Health

Contributes `find_todos`, `code-health-reviewer`, and `$code-health-review`.
The tool runs `git grep` only when invoked and uses the normal shell approval path.
Installation does not execute the tool.

From the package's parent directory:
Validate: `autohand extensions validate ./acme.code-health`
Install: `autohand --path . extensions install ./acme.code-health --scope project`
Remove: `autohand --path . extensions remove acme.code-health --scope project --yes`
```

## 7\. Validate without installing

From the parent directory:

``` bash
autohand extensions validate ./acme.code-health
autohand extensions validate ./acme.code-health --json
```

Expected human output is equivalent to:

``` text
Valid extension acme.code-health@1.0.0 (1 tool, 1 agent, 1 skill, 0 runtime entrypoints)
```

If validation fails, fix the first reported contract error. Do not manually copy an invalid package into an extension root; registry discovery will fail it closed and `doctor` will report the package.

## 8\. Link it for project development

``` bash
autohand --path . extensions install ./acme.code-health --scope project --link
autohand --path . extensions show acme.code-health --scope project
autohand --path . extensions doctor
```

`show` should report project scope, enabled state, linked status, `find_todos`, `code-health-reviewer`, and `code-health-review`. The source directory stays where you created it.

## 9\. Invoke the generated skill

Add a harmless TODO to a tracked test file, start a fresh Autohand process in that repository, confirm `code-health-review` appears in `/skills`, and ask:

``` text
$code-health-review inspect src/ and return a prioritized maintainability report
with exact file evidence. Do not edit anything.
```

The explicit skill mention activates its instructions in the same turn. Approve the expected read-only shell action if your policy prompts. Confirm that the result calls `find_todos`, reads relevant context, cites the tracked file, distinguishes evidence from inference, and does not claim success when the tool is denied.

Then call the specialist separately when you need a focused delegated review:

``` text
Use the code-health-reviewer agent to inspect the same evidence and challenge
the highest-priority finding. Do not edit anything.
```

## 10\. Test disable, enable, and removal

In a normal interactive session, lifecycle mutations refresh the current registry:

``` text
/extensions disable acme.code-health
/extensions show acme.code-health
/extensions enable acme.code-health
/extensions doctor
/extensions remove acme.code-health --yes
```

After disabling, the package remains visible but contributes no tool, agent, or skill; `$code-health-review` must disappear from suggestions and `/skills`. After enabling, all three contributions must return. After removal, the linked source directory must still exist.

## 11\. Prove the copied artifact

Linked development is not the release proof. Install normally, start a fresh process, and repeat the smoke task:

``` bash
autohand extensions validate ./acme.code-health
autohand --path . extensions install ./acme.code-health --scope project
autohand --path . extensions show acme.code-health --scope project
autohand --path . extensions doctor

# After the fresh-process smoke test
autohand --path . extensions remove acme.code-health --scope project --yes
```

**Done means lifecycle proof.** The extension is ready to share only after validation, copied installation, fresh-process discovery, `$code-health-review` invocation, tool authorization, agent use, disable/enable, diagnostics, and removal all behave as documented.

## Troubleshooting

| Symptom | Check | Resolution |
|---|---|---|
| The package does not validate | Run autohand extensions validate ./acme.code-health --json. | Fix the first contract error, then rerun validation before installing. |
| $code-health-review is missing | Run /extensions show acme.code-health and /skills in a fresh process. | Confirm the extension is enabled and the manifest path exactly matches skills/code-health-review/SKILL.md. |
| find_todos is unavailable | Run /extensions doctor and inspect the active tool registry. | Confirm the JSON schema, tool name, and extension state; an agent allowlist does not register a missing tool. |
| The linked build works but the copied build fails | Inspect the installed package with extensions show. | Remove the old copy, install the current source normally, and repeat the fresh-process smoke test. |

## Next steps

-   [Build a trusted runtime extension](/tutorials/extensions/build-runtime-extension.html) when your package needs commands, UI, hooks, providers, or permission policy.
-   [Build a Level 500 Atlassian Rovo integration](/tutorials/extensions/500-atlassian-rovo-integration.html) to combine a declarative extension with a remote MCP service, OAuth, change gates, and production verification.
-   [Validate and publish an extension](/tutorials/extensions/validate-and-publish.html) after the copied artifact passes its lifecycle tests.