Build your first extension with $extension-builder

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.

What you will build

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.

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:

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

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

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

1. Create the package directories

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:

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

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

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

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

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

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

Expected human output is equivalent to:

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

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:

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

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:

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

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

Troubleshooting

Next steps

• Build a trusted runtime extension when your package needs commands, UI, hooks, providers, or permission policy.
• Build a Level 500 Atlassian Rovo integration to combine a declarative extension with a remote MCP service, OAuth, change gates, and production verification.
• Validate and publish an extension after the copied artifact passes its lifecycle tests.