Skip to content

Quickstart: Package & Sign

This walkthrough takes you from an empty directory to a signed, publishable extension bundle. You will scaffold a project, declare permissions, package it into a .aext artifact, generate supply-chain attestations, and sign the result with an Ed25519 key.

The entire process takes under five minutes.

Prerequisites

  • Go 1.23+ installed
  • agentsec CLI installed and on your PATH — see Installation

Express path

Three commands to scaffold, package, and install in dev mode:

# 1. Scaffold a new extension project
agentsec init ./my-skill --id com.example.my-skill --type skill

# 2. Package the directory into a .aext artifact
agentsec package ./my-skill --out my-skill.aext

# 3. Install locally in dev mode (skips signature verification)
agentsec install my-skill.aext --dev --aem my-skill/aem.json --dest ./installed

What is --dev mode?

The --dev flag skips signature verification and uses a permissive policy, making it suitable for local iteration. When you are ready to sign and enforce policy, follow the full flow below.

Full flow

1) Scaffold the project

The init command creates a ready-to-use project directory with sensible defaults:

agentsec init ./my-skill --id com.example.my-skill --type skill

This generates three files:

File Purpose
my-skill/aem.json AEM manifest with least-privilege (zero) permissions
my-skill/devkey.json Ed25519 dev signing keypair
my-skill/policy.json Warn-mode policy for development testing

2) Add your content

Create your SKILL.md and any supporting files. The content structure depends on your target platform — see the Platform Integration guides for platform-specific conventions.

cat > my-skill/SKILL.md << 'EOF'
# My Skill

Instructions for the agent go here.
EOF

3) Declare permissions

Edit my-skill/aem.json to declare what your extension actually needs. The manifest generated by agentsec init starts with zero permissions — add only what is required.

# Review the current manifest
cat my-skill/aem.json

Start minimal, add incrementally

Every permission you declare is a permission that consumers must evaluate and accept. Request only what your extension genuinely needs. See Declaring Permissions for guidance on choosing the right values.

4) Package the artifact

Bundle the project directory into a .aext artifact — a hardened zip archive with safety controls (symlink blocking, size limits, and path traversal prevention):

agentsec package ./my-skill --out my-skill.aext

5) Validate the manifest

Run the manifest validator to confirm schema conformance before signing:

agentsec manifest validate my-skill/aem.json

Validation checks that the schema string matches aessf.dev/aem/v0, the extension type is valid, the version is valid semver, and no unknown fields are present.

Didn't use agentsec init?

If you created your manifest manually, you can generate one with manifest init:

agentsec manifest init ./my-skill \
  --id com.example.my-skill --type skill --version 0.1.0 \
  --out my-skill/aem.json

6) Generate attestations

Generate supply-chain evidence for the artifact. Each attestation serves a different purpose:

Command Output What it provides
agentsec sbom sbom.spdx.json Dependency and file inventory (SPDX format)
agentsec provenance provenance.json Build origin — source repo, commit, builder
agentsec scan scan.json Heuristic risk scan of skill content and scripts 
agentsec sbom my-skill.aext --out sbom.spdx.json
agentsec provenance my-skill.aext \
  --source-repo https://github.com/your-org/your-skill-repo \
  --source-rev "$(git rev-parse HEAD)" \
  --out provenance.json
agentsec scan my-skill.aext --out scan.json

Scaffold quality

These attestation outputs are reference-quality placeholders in the current implementation. They demonstrate the intended workflow shape but are not yet compliance-grade. See Production Readiness for the roadmap toward full SPDX/CycloneDX, SLSA provenance, and multi-engine scanning.

7) Sign and verify

Sign the artifact digest with your Ed25519 key, then verify to confirm the signature is valid:

agentsec sign my-skill.aext --key my-skill/devkey.json --out my-skill.sig.json
agentsec verify my-skill.aext --sig my-skill.sig.json --pub my-skill/devkey.json

A successful verification prints verified: my-skill.aext, confirming that the artifact has not been modified since signing and that the signature matches the provided public key.

Dev keys are not identity-bound

The dev keypair generated by agentsec init proves integrity (the artifact hasn't changed) but does not bind the signature to a verified identity. For production use, identity-bound signing via Sigstore is planned — see Contributing for the roadmap.

What you've built

At this point you have a complete, publishable extension bundle:

File Purpose
my-skill.aext Packaged extension artifact
aem.json Permission manifest
my-skill.sig.json Ed25519 signature
sbom.spdx.json Software bill of materials
provenance.json Build provenance record
scan.json Heuristic scan results

Self-test: simulate a consumer install

Before publishing, verify that the full consumer experience works — including signature verification and policy enforcement. This catches policy violations before your consumers encounter them.

agentsec install my-skill.aext \
  --sig my-skill.sig.json \
  --pub my-skill/devkey.json \
  --aem my-skill/aem.json \
  --policy my-skill/policy.json \
  --dest ./test-install

Test against multiple policies

Try installing with different policy templates to understand how consumers with varying security postures will experience your extension. See Examples & Policies for pre-built policy files ranging from permissive to strict.

For the full consumer perspective, see the Consumer Quickstart.

Next steps