The Hub

The Agent Apps Hub is a shared registry for distributing skills as packages. It uses git as the transport, semver for version resolution, and SHA-512 for integrity verification. There is no registry server — just a git repo with a JSON index.

Quick Start

agent-apps hub-search                          # Browse all packages
agent-apps hub-add --name echo            # Install a package
agent-apps echo --text "Hello"            # Use it immediately

Installed packages are discovered automatically. No config changes needed.

Browsing and Searching

hub-search queries all configured registries and returns results:

agent-apps hub-search                              # List everything
agent-apps hub-search --query "csv"          # Keyword search
agent-apps hub-search --query "analyze data" # Multi-term search

Search uses case-insensitive substring matching across package names, descriptions, keywords, and skill names. Exact name matches appear first; remaining results are sorted alphabetically. Empty queries return all packages.

Return Format

All hub skills return structured objects. hub-search returns:

{
  "results": [
    { "name": "echo", "version": "1.1.0", "description": "Echo input back...", "tags": ["utility"], "deprecated": null }
  ],
  "text": "1 package(s) found:\n\n  echo@1.1.0 — Echo input back... [utility]\n\nInstall with: agent-apps hub-add <name>"
}

The text field is a human-readable summary. The results array is the structured data. Every hub skill follows this pattern — structured data alongside a text fallback.

Installing Packages

agent-apps hub-add --name echo              # Latest version
agent-apps hub-add --name echo@^1.0.0       # Semver range
agent-apps hub-add --name echo@1.1.0        # Exact version

Installation resolves the full dependency tree, copies package files to .agent-apps/packages/, computes SHA-512 integrity hashes, runs per-package npm install for packages with dependencies, and writes the lockfile.

After installing, the package's skills are immediately available as CLI commands:

agent-apps echo --text "installed from the hub"

Dry Run

Preview what would be installed without modifying disk:

agent-apps hub-add --name csv-analyze --dryRun true

{
  "success": true,
  "packages": [
    { "name": "csv-analyze", "version": "2.1.0" },
    { "name": "formula-calc", "version": "1.2.0" }
  ],
  "text": "Dry run — would install 2 package(s):\n\n  csv-analyze@2.1.0\n  formula-calc@1.2.0\n\n1 transitive dep(s)."
}

Where Packages Live

.agent-apps/
  packages/
    echo/              ← hub package (skill files + package.json)
      node_modules/    ← npm deps for this package (if any)
    csv-analyze/       ← another hub package
      node_modules/    ← its own npm deps
  lock.json            ← installed versions, integrity hashes, dependency graph

The framework's default search path includes { external: ".agent-apps/packages" }, so installed packages are discovered automatically. The external flag means hub packages have isolated authority — they don't inherit your project's cascade config. --local overrides don't apply to them; --global overrides do.

npm Dependencies

Some hub packages have npm dependencies (e.g., a CSV analyzer that needs csv-parse). These are declared in the package's package.json under dependencies. When a package is installed, the hub runs npm install --production inside the package directory, giving each package its own node_modules/. This keeps packages isolated — no version conflicts between packages, and no interference with your project's own dependencies.

Listing Installed Packages

agent-apps hub-list

Shows installed packages with version, available updates, and dependency tree:

{
  "packages": [
    { "name": "echo", "version": "1.0.0", "updateAvailable": "1.1.0" },
    { "name": "csv-analyze", "version": "2.1.0", "hubDependencies": { "formula-calc": "1.2.0" } }
  ],
  "text": "2 package(s) installed:\n\n  echo@1.0.0 (update available: 1.1.0)\n  csv-analyze@2.1.0\n    └─ formula-calc@1.2.0"
}

Package Details

agent-apps hub-info --name echo

Returns everything about a package — all versions, skill frontmatter, dependencies, keywords, installed status, and integrity hash:

{
  "package": {
    "name": "echo",
    "latest": "1.1.0",
    "versions": ["1.0.0", "1.1.0"],
    "description": "Echo input back, optionally transformed",
    "keywords": ["utility", "text", "debug"],
    "skills": ["echo"],
    "deprecated": null,
    "frontmatter": [{ "name": "echo", "description": "Echo input back, optionally transformed", "metadata": { "params": {} } }],
    "hubDependencies": null,
    "installed": { "version": "1.1.0", "integrity": "sha512-2EDlWH..." }
  },
  "text": "echo@1.1.0\n  Echo input back...\n\nInstalled: 1.1.0 (latest)\nIntegrity: sha512-2EDlWH...\n\nVersions: 1.0.0, 1.1.0\nSkills: echo\nKeywords: utility, text, debug\nMetadata: params"
}

The frontmatter field contains the raw frontmatter from each skill file in the package — name, description, params, metadata keys, and any other fields the skill declares. This gives consumers full visibility into what a package contains without installing it.

Updating Packages

agent-apps hub-update                          # Update all
agent-apps hub-update --name echo        # Update one

Update fetches the latest registry index, compares versions, verifies integrity of the existing install, copies the new version, re-resolves hub dependencies (installing any new transitive deps), syncs npm deps, and updates the lockfile:

{
  "success": true,
  "packages": [
    { "name": "echo", "version": "1.1.0", "previousVersion": "1.0.0" }
  ],
  "text": "Updated:\n\n  ✓ echo@1.1.0 (was 1.0.0)"
}

Packages already at the latest version are skipped with a ✓ already at latest message.

Removing Packages

agent-apps hub-remove --name echo

Removes the package from disk and updates the lockfile. If other installed packages depend on the one being removed, you get a warning:

{
  "success": true,
  "packages": [{ "name": "echo" }],
  "warnings": ["⚠ csv-analyze depends on echo"],
  "text": "✓ Removed echo\n\n⚠ csv-analyze depends on echo"
}

The removal still proceeds — the warning is informational. The dependent package may break until you reinstall the dependency or remove the dependent too.

Publishing

Share a skill with the community:

agent-apps hub-publish --path ./skills/my-skill.skill.js
agent-apps hub-publish --path ./skills/my-package/    # Directory with multiple skills
agent-apps hub-publish --path ./skills/my-skill.skill.js --name custom-name

Publishing validates the skill files, extracts frontmatter and skill names, computes a SHA-512 integrity hash, and pushes a branch to the registry. The output includes a URL to open a pull request.

What Gets Published

When publishing a directory, the entire directory tree is copied — skill files, resource files, subdirectories, configuration, data files, everything. The only requirement is that at least one skill file (.skill.js, .skill.ts, .skill.md, or SKILL.md) exists. When publishing a single file, just that file is copied into a new package directory.

The same applies on install: hub-add copies the full package directory recursively, preserving any subdirectories and non-skill resources the package includes.

Package Manifest

Each published package has a package.json:

{
  "name": "@agent-apps/echo",
  "version": "1.1.0",
  "type": "module",
  "description": "Echo input back, optionally transformed",
  "keywords": ["utility", "text", "debug"],
  "author": "Your Name <you@example.com>",
  "dependencies": { "csv-parse": "^5.0.0" },
  "agentApps": {
    "skills": ["echo"],
    "frontmatter": [{ "name": "echo", "description": "Echo input back, optionally transformed", "metadata": { "params": {} } }],
    "integrity": "sha512-abc..."
  }
}

The agentApps field is populated automatically during publishing. dependencies are standard npm deps installed per-package on hub-add.

Dependencies

Hub packages can depend on other hub packages via hubDependencies in the registry index:

{
  "csv-analyze": {
    "latest": "2.1.0",
    "versions": {
      "2.1.0": {
        "hubDependencies": { "formula-calc": "^1.0.0" }
      }
    }
  }
}

When you install csv-analyze, the resolver walks the dependency tree and installs formula-calc too. Diamond dependencies are allowed if versions are compatible. Conflicts produce a clear error message.

The lockfile records the resolved dependency graph:

{
  "version": 2,
  "packages": {
    "csv-analyze": {
      "version": "2.1.0",
      "integrity": "sha512-abc...",
      "registry": "ssh://git.amazon.com/pkg/AgentAppsHub",
      "commit": "a1b2c3d",
      "installed": "2026-03-10T02:57:38.223Z",
      "hubDependencies": { "formula-calc": "1.2.0" }
    },
    "formula-calc": {
      "version": "1.2.0",
      "integrity": "sha512-def...",
      "registry": "ssh://git.amazon.com/pkg/AgentAppsHub",
      "commit": "a1b2c3d",
      "installed": "2026-03-10T02:57:38.500Z"
    }
  }
}

Federation

Configure multiple registries to search and install from:

# In your main skill
metadata:
  registries:
    - ssh://git.amazon.com/pkg/AgentAppsHub
    - ssh://git.amazon.com/pkg/TeamSkills

Search merges results from all registries. Install resolves from the first registry that has the package. Each registry gets its own cache directory under ~/.agent-apps/cache/registries/. The lockfile records which registry each package came from.

You can also set the registry via environment variable for testing:

AGENT_APPS_REGISTRY_REPO=file:///path/to/local/registry agent-apps hub-search

Agent Self-Service

Skills can let agents install hub packages at runtime. Add hub tools to allowed-tools:

---
name: data-assistant
description: Help the user analyze data files
metadata:
  model:
    id: us.anthropic.claude-sonnet-4-6
  allowed-tools: "* hub-search hub-add hub-remove hub-info"
---

You are a data analysis assistant. If the user asks you to work with a file format
you don't have tools for, search the hub for a relevant package and install it.

The agent can then discover and install capabilities on demand:

User: Can you analyze this CSV file?

Agent: I'll search for a CSV analysis package. (calls hub-search with query="csv") Found csv-analyze — let me install it. (calls hub-add with name="csv-analyze") Done. Now I can analyze your file. (calls csv-analyze)

Hub skills are visibility: hidden by default, so they only appear to agents when explicitly listed in allowed-tools.

Registry Format

The registry is a git repo with this structure:

packages/
  echo/
    echo.skill.js
    package.json
  timestamp/
    timestamp.skill.js
    package.json
registry.json
scripts/build-index.mjs

Registry Index (v2)

registry.json is the index that hub skills read:

{
  "version": 2,
  "generated": "2026-03-10T02:00:00Z",
  "packages": {
    "echo": {
      "latest": "1.1.0",
      "versions": {
        "1.1.0": {
          "path": "packages/echo",
          "description": "Echo input back, optionally transformed",
          "keywords": ["utility", "text", "debug"],
          "skills": ["echo"],
          "hubDependencies": null,
          "integrity": "sha512-abc...",
          "deprecated": null,
          "frontmatter": [
            { "name": "echo", "description": "Echo input back, optionally transformed", "metadata": { "params": {} } }
          ]
        }
      }
    }
  }
}

The framework auto-converts v1 indexes (flat [{name, version, description, keywords, path}] arrays) to v2 on read, so older registries continue to work.

Regenerating the Index

After adding or updating packages in the registry repo:

node scripts/build-index.mjs

This reads each package's package.json (including the agentApps field) and generates a fresh registry.json.

Integrity Verification

Every installed package has a SHA-512 integrity hash computed from its file contents (via the ssri library). The hash is stored in the lockfile and verified during updates. If the installed files have been tampered with, the update reports an integrity mismatch warning before proceeding.

Deprecation

Registry entries can include a deprecated field with a message:

{ "deprecated": "Use csv-analyze-v2 instead" }

Deprecated packages still install and work, but hub-search marks them with ⚠ and hub-add includes a warning in the response.

Reference

Skill Arguments Returns
hub-search query?: string { results: [{name, version, description, tags, deprecated}], text }
hub-add name: string, dryRun?: boolean { success, packages: [{name, version}], warnings, text }
hub-remove name: string { success, packages: [{name}], warnings, text }
hub-update name?: string { success, packages: [{name, version, previousVersion}], warnings, text }
hub-list (none) { packages: [{name, version, updateAvailable?, hubDependencies?}], text }
hub-info name: string { package: {name, latest, versions, description, ...}, text }
hub-publish path: string, name?: string, registry?: string { success, packages: [{name, version}], warnings, text }

For the full technical specification — resolution semantics, lockfile format, and federation behavior — see the Specification.

See Also

  • Specification — Complete technical reference
  • Sandbox — Container-based isolation for testing
  • Deploy — Deploy to AWS App Runner

Ask AI