Show HN: Introducing: Zotfile Agents

Zotfile Agents introduces a portable .zot file format that packages an AI agent's persona, skills, permissions, and requirements into a single shareable artifact. Users run agents locally with their own model credentials using the zot runtime, enabling easy distribution and execution of specialized AI agents.

zotfile agents Package agent behavior, skills, requirements, and permissions into a portable .zot file. A zotfile is an agent you can share like a file. It packages an agent's persona and standing instructions, reusable skills, requirements, and enforced tool permissions into one portable .zot artifact. The user runs it locally with their own model credentials, in their own workspace, using zot as the runtime. Create an agent A source directory needs manifest.json and AGENT.md . Add skills when the agent has procedures that should be loaded only for relevant tasks. code-reviewer/ manifest.json AGENT.md skills/ review-change/ SKILL.md assets/ optional static files README.md optional human documentation { "zotfile": 1, "name": "code-reviewer", "version": "0.1.0", "description": "Reviews a repository without modifying it.", "runtime": { "min zot": "0.2.76" }, "model": { "requires": "tools", "reasoning" , "min context": 64000, "preferred": }, "permissions": { "fs": { "read": "${workspace}" , "write": }, "bash": { "mode": "none" } }, "requirements": { "bin": "git" , "os": "darwin", "linux", "windows" }, "entry": { "greeting": "What should I review?", "default prompt": null }, "replace system prompt": false } Local names are flat and lowercase. They may contain letters, digits, dots, hyphens, and underscores. Registry-style namespace/agent names are not accepted by the local runtime yet. Versions should use semver, although semver is not currently validated. Write the behavior Put the agent's role, workflow, constraints, and output expectations in AGENT.md . By default it is appended to zot's normal system prompt, so the agent keeps zot's standard tool-use and safety guidance. Code reviewer Review the current repository without modifying it. Prioritize correctness, security, regressions, and missing tests. Report findings in severity order with file and line references. Stay grounded in the code and do not invent failures. Set replace system prompt to true only for a fully specialized agent that should replace zot's default system prompt rather than extend it. Capability and security claims belong in the manifest, not in agent-authored prose. Bundle skills Skills use the normal SKILL.md format under skills/<name /SKILL.md . zot adds bundled skills to discovery while the agent runs. The model sees each skill's name and description, then loads the full body with the skill tool only when it applies. --- name: review-change description: Review the current Git diff for correctness and missing tests. --- Review change 1. Read the complete diff and every changed file. 2. Run focused tests when permitted. 3. Report actionable findings with file and line references. See Skills /docs/skills for discovery rules and authoring guidance. Ordinary files under assets/ are included in the artifact, but are not automatically placed in model context or granted filesystem access. Declare permissions zotfile permissions are an enforced ceiling for the built-in file and bash tools. Empty or omitted filesystem scopes deny access. Keep declarations as narrow as the agent's job allows. Use ${workspace} for the run's working directory and ${agent data} for persistent private storage at $ZOT HOME/agents/<name /data/ . Relative permission paths resolve beneath the workspace. Canonical path checks prevent file tools from escaping a scope through symlinks. { "permissions": { "fs": { "read": "${workspace}", "${agent data}" , "write": "${agent data}" }, "bash": { "mode": "allowlist", "allow": "git", "go" } } } Set requirements Use runtime.min zot for the minimum runtime, requirements.os for supported operating systems, and requirements.bin for programs that must already exist on PATH . zotfiles have no install or postinstall hooks. Model requirements are provider-neutral. model.min context sets the minimum context window. model.requires accepts tools and reasoning . vision is recognized but currently fails closed because vision support is not represented in the model catalog. Unknown capabilities and a non-empty model.min tier are rejected. zot keeps an explicitly selected or configured default model when it qualifies, then tries model.preferred , then another compatible active model. It stops with a clear error when no catalog model satisfies the requirements. Test and package Develop directly from the source directory zot inspect ./code-reviewer zot run ./code-reviewer zot run ./code-reviewer "Review the authentication package" Create and validate the portable artifact zot pack ./code-reviewer zot verify ./code-reviewer.zot zot inspect ./code-reviewer.zot zot run ./code-reviewer.zot Run directly from a public GitHub repository zot run https://github.com/patriceckhart/agents/zot-maintenance \ --cwd /path/to/zot Packed archives have sorted entries, normalized tar metadata, and fixed timestamps. Symlinks are rejected. Extraction rejects absolute paths and parent traversal and limits the archive to 100 MiB compressed, 64 MiB per entry, and 256 MiB expanded. For a GitHub URL, zot downloads the public repository archive to a temporary directory and removes it when the command exits. The short github.com/owner/repo/path form uses the default branch; standard github.com/owner/repo/tree/ref/path URLs select a branch or tag. Consent, data, and sessions Before an agent runs, zot prints its identity and expanded permissions and asks the user to approve them. Approval is cached for the exact artifact digest, except for bash: ask , which requests consent on every launch. Any artifact change creates a new digest and requires approval again. Non-interactive runs refuse to bypass consent by default. Controlled automation can set ZOT AGENT CONSENT=1 , but should do so only after independently inspecting and trusting the exact artifact. Agent history is isolated under $ZOT HOME/sessions/agents/<name / , so packaged-agent sessions do not bleed into ordinary zot sessions or another agent's history. Normal session flags such as --continue , --resume , and --no-session still apply.