Concepts & the SPEC

Every Agent Kit follows a public package specification owned by @agentkitforge/core (the engine behind Forge). This page covers the core concepts and the shape of a kit. The full, authoritative spec lives in SPEC.md in @agentkitforge/core.

Core building blocks

• Skills — a skill is a folder under skills/ with a SKILL.md describing how the AI performs part of the job, plus trigger phrases. Every kit needs at least one skill.
• Prepared Prompts — reusable prompt flows defined in prompts/<prompt-id>.yaml with typed inputs Forge collects before a run.
• Policies — guardrails (what to avoid, require, or escalate) stored under policies/.
• Templates & examples — output formats (templates/) and sample input/output pairs (examples/).
• References & context — supporting material under references/ the kit can draw on.
• Workflows, evals, adapters, scripts, assets, exports — optional folders for multi-step flows, evaluation cases, integration adapters, helper scripts, binary assets, and pre-built exports.

The .agentkit.zip package

A kit is distributed as a single portable .agentkit.zip archive. The canonical structure required for the local-valid profile is:

agentkit.yaml        # the package manifest
AGENTKIT.md          # agent entrypoint
START_HERE.md        # human entrypoint
skills/
skills/<skill-id>/SKILL.md

Optional files and folders include:

README.md  LICENSE  CHANGELOG.md
workflows/  policies/  references/  templates/
examples/  examples/prompts/  examples/inputs/  examples/outputs/
evals/  adapters/  scripts/  assets/  exports/
prompts/  prompts/<prompt-id>.yaml

The manifest: agentkit.yaml

The manifest uses schemaVersion: "0.1" (the spec FORMAT version) and includes required fields such as:

schemaVersion: "0.1"
kind: ...
id: ...
name: ...
version: "1"            # content version (see below)
description: ...
author:
  name: ...
license: ...
entrypoints:
  human: START_HERE.md
  agent: AGENTKIT.md
userExperience:
  setupLevel: ...
compatibility:
  targets: [...]
risk:
  level: ...
skills:
  - id: ...
    path: ...
    description: ...
    triggers: [...]

Content versioning

A kit's version is its content version: a sequential positive integer (1, 2, 3, …) displayed to authors as vN and auto-incremented when a new revision is published. It is stored as a quoted string (e.g. version: "1") and is distinct from schemaVersion (the spec format version). Legacy kits carrying a semver version (e.g. "0.1.0") are treated as v1 and normalized to "1" on the next write.

Validation profiles

Forge Core validates a kit against escalating profiles:

• local-valid — the minimum to build, run, and export locally.
• publishable — required before submitting to the Market.
• trusted → verified — higher review/trust levels.

Package safeguards

Packaging enforces hard limits to keep kits portable and safe:

• Max 2000 entries per package.
• Max 100 MB uncompressed total.
• Max 25 MB per file.
• No symlinks and no path traversal.