ambleloftExtension anatomy
Know where each file belongs before turning a local build into an installable application.
Outcome: Identify the manifest, entry point and packaged resources; verify the installed behavior.
Before you begin: Prepare the files and tools specified on this page. The previous page in the learning path is not automatically a dependency.
On this page
01Start from the scaffold
First complete local package setup in the first-extension guide. Run from extension-work with AMBLELOFT_PACKS still set. The CLI does not install dependencies.
npx --no-install amble-extension init my-business-app --name my-business-app --template project-card
cd my-business-app
npm install --save-dev "$AMBLELOFT_PACKS/ambleloft-extension-sdk-0.1.0-alpha.9.tgz" "$AMBLELOFT_PACKS/ambleloft-extension-core-0.1.0-alpha.9.tgz" "$AMBLELOFT_PACKS/ambleloft-extension-cli-0.1.0-alpha.9.tgz"
npm run build
npm run validate
npm run pack02Sources and the installed package
main, icon and skills resolve inside the installed package, not your working directory. The scaffold build.cjs prepares dist/package; CLI pack includes all files in that directory. Keep service credentials and node_modules outside it.
extension.json # Identity, permissions, operations
extension.nls.json # Default UI strings
extension.nls.zh-CN.json # Chinese UI strings
src/extension.ts # Node backend
src/page.ts # Home-page browser entry
web/index.html # Home page
assets/icon.png # Add and copy during build
skills/intake/SKILL.md # Add and copy during build
skills/intake/intake.yaml
build.cjs # Build → dist/package
dist/*.amble-extension # Installable archive03Register and dispose
activate receives ExtensionContext. Add registrations and listeners to context.subscriptions; background connections should expose dispose() and be added too. A page closing is not the same as extension deactivation. Do not create a duplicate service connection per page.
Look up ExtensionContext04Verify the installed result
Open Skills & extensions → Install from local, select the archive, confirm trust and grant declared permissions. The project card should open. After changes, build, validate, pack and install again: source edits do not update an installed extension automatically.
Next: add your iconCheck the result and troubleshoot
Identify the manifest, entry point and packaged resources; verify the installed behavior.
Check actual results using this page’s verification steps. For business integrations, inspect UI submission, tool receipts and server records separately.
Open the error reference →