Skip to content
Seal

What is Seal?

Seal is a specification and a CLI for checking project-local agent files against a pinned content snapshot. It records per-file hashes in seal.json; your review process establishes which snapshot to trust.

The problem

Section titled “The problem”

AI coding agents load bundles: skills, hooks, prompts, scripts, templates, tool definitions, MCP configs, and related resources. These files can change how the agent behaves inside the host’s sandbox and permission model, including:

  • reading files the host permits
  • writing code or configuration
  • invoking tools or commands the host permits

A reviewed bundle can change after installation or through a later update. Seal detects differences between its local contents and the snapshot you pinned, including additions within configured discovery paths.

Git review and dependency lockfiles already address parts of this problem. Seal provides a dedicated integrity check across selected agent assets, including project-local files outside conventional skill directories.

Terminology

Section titled “Terminology”

Seal uses precise terms that matter when reading the spec or the CLI output.

Term Meaning
Bundle A loadable agent extension with a single top‑level identity and a sealed root. May contain skills, hooks, prompts, scripts, templates, tool definitions, MCP configs, assets. The primary subject of Seal v1.
Component A file or sub‑resource inside a bundle (e.g. a skill, hook, prompt, script). Components are tracked as part of their containing bundle, not separately.
Project‑local loadable unit A loadable unit whose sealed root is inside the project root containing seal.json.
Project‑external extension A loadable unit whose sealed root is outside the project root: user‑level, home‑directory, organization‑level, global, admin, or cache‑installed.
Sealed root The project-local directory or regular file Seal verifies for a given bundle.
Bundle key The project‑root‑relative path to a sealed root, prefixed with ./ (e.g. ./.agents/skills/code-review).
Lockfile seal.json at the project root. The authoritative allowlist for project‑local bundles.

In Seal docs, plugin refers to a host‑specific kind of bundle. The portable concept is bundle; plugin is used only when discussing host‑specific formats.

The approach

Section titled “The approach”
  1. Review the instructions, scripts, and resources you intend to use.
  2. Run seal init to propose discovery paths and record hashes in seal.json.
  3. Review and commit the lockfile through your normal approval process.
  4. Run seal verify locally or in CI to compare the installed files with that snapshot.
  5. For intentional updates, review the content changes before seal pin, then review and commit the resulting lockfile diff.

Under the default block policy, changed bundles and new bundles within discovery paths make verification exit 1. Removing an entire bundle produces Drift and does not block by itself. Under warn, mismatches and new bundles are reported with exit 0.

The CLI checks files when invoked. Preventing an agent from loading changed files requires a native integration that verifies immediately before loading. Installing the CLI does not change the agent’s loading behavior.

Why use Seal alongside Git?

Section titled “Why use Seal alongside Git?”

If every agent file is tracked, reviewed, and used from a clean checkout, Git may already provide the checks you need. Seal adds an explicit bundle inventory, file hashes, discovery patterns, and one offline verification command. Its coverage can include installed or generated files that are not tracked by Git.

The lockfile is only as trustworthy as the process that approves it. A change to both the files and their hashes can pass verification. See the alternatives comparison.

Scope and limits

Section titled “Scope and limits”
  • Local contents: a directory bundle covers the regular files beneath its root. A file bundle covers that file. Discovery patterns determine where the CLI detects new bundles.
  • Safety and provenance: matching hashes establish equality with the snapshot; they do not establish safe behavior or an author’s identity.
  • Installation: Seal checks files already present on disk. It does not install or resolve dependencies.
  • External inputs: remote downloads, runtime responses, and dependencies outside a sealed root are not covered by that entry. Seal does not pin a transitive dependency graph.

Where to go next

Section titled “Where to go next”