Package format

Every Nuclexa package is a directory of plain files. There is no build step, no proprietary container, and no runtime you must adopt — a package is just text on disk that any platform can read. This keeps packages portable, diffable in git, and easy to review before you run them.

The standard layout

my-agent/
  agent.json          # required — the manifest
  README.md           # required — human-facing overview
  instructions.md     # required — the entry point
  permissions.json    # optional — explicit permission scope
  examples/           # optional — example prompts & transcripts
    basic.md
    advanced.md
  assets/             # optional — images, schemas, reference files

Only three files are strictly required: agent.json, README.md, and the entry file referenced by the manifest (instructions.md by convention).

File reference

agent.json

The manifest — the single source of truth for the package's identity, version, type, supported platforms, and declared permissions. The agent.json manifest doc documents every field.

README.md

The human-facing overview, rendered on your package page. Explain what it does, who it's for, how to use it, and any setup it needs. Standard Markdown is supported.

instructions.md

The entry point — the content loaded into the tool. For an agent this is the system prompt; for a skill it is the skill definition; for a rule it is the rule body; for a prompt pack it is the prompts. The entry field in agent.json points here.

permissions.json

An optional explicit permission scope. Permissions can be declared inline in agent.json, but a separate file is useful when you want to document each grant with a justification. When both are present, permissions.json is authoritative. See the Permissions model.

examples/

A directory of example prompts and transcripts — the single most effective thing you can add to drive installs.

File summary

Next: the agent.json manifest reference.