{"slug": "show-hn-introducing-zotfile-agents", "title": "Show HN: Introducing: Zotfile Agents", "summary": "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.", "body_md": "# zotfile agents\n\nPackage agent behavior, skills, requirements, and permissions into a portable .zot file.\n\nA 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`\n\nartifact. The user runs it locally with their own model credentials, in their own workspace, using zot as the runtime.\n\n## Create an agent\n\nA source directory needs `manifest.json`\n\nand `AGENT.md`\n\n. Add skills when the agent has procedures that should be loaded only for relevant tasks.\n\n```\ncode-reviewer/\n  manifest.json\n  AGENT.md\n  skills/\n    review-change/\n      SKILL.md\n  assets/       # optional static files\n  README.md     # optional human documentation\n{\n  \"zotfile\": 1,\n  \"name\": \"code-reviewer\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Reviews a repository without modifying it.\",\n  \"runtime\": {\n    \"min_zot\": \"0.2.76\"\n  },\n  \"model\": {\n    \"requires\": [\"tools\", \"reasoning\"],\n    \"min_context\": 64000,\n    \"preferred\": []\n  },\n  \"permissions\": {\n    \"fs\": {\n      \"read\": [\"${workspace}\"],\n      \"write\": []\n    },\n    \"bash\": {\n      \"mode\": \"none\"\n    }\n  },\n  \"requirements\": {\n    \"bin\": [\"git\"],\n    \"os\": [\"darwin\", \"linux\", \"windows\"]\n  },\n  \"entry\": {\n    \"greeting\": \"What should I review?\",\n    \"default_prompt\": null\n  },\n  \"replace_system_prompt\": false\n}\n```\n\nLocal names are flat and lowercase. They may contain letters, digits, dots, hyphens, and underscores. Registry-style `namespace/agent`\n\nnames are not accepted by the local runtime yet. Versions should use semver, although semver is not currently validated.\n\n## Write the behavior\n\nPut the agent's role, workflow, constraints, and output expectations in `AGENT.md`\n\n. By default it is appended to zot's normal system prompt, so the agent keeps zot's standard tool-use and safety guidance.\n\n```\n# Code reviewer\n\nReview the current repository without modifying it.\n\nPrioritize correctness, security, regressions, and missing tests. Report\nfindings in severity order with file and line references. Stay grounded\nin the code and do not invent failures.\n```\n\nSet `replace_system_prompt`\n\nto `true`\n\nonly 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.\n\n## Bundle skills\n\nSkills use the normal `SKILL.md`\n\nformat under `skills/<name>/SKILL.md`\n\n. 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`\n\ntool only when it applies.\n\n```\n---\nname: review-change\ndescription: Review the current Git diff for correctness and missing tests.\n---\n\n# Review change\n\n1. Read the complete diff and every changed file.\n2. Run focused tests when permitted.\n3. Report actionable findings with file and line references.\n```\n\nSee [Skills](/docs/skills) for discovery rules and authoring guidance. Ordinary files under `assets/`\n\nare included in the artifact, but are not automatically placed in model context or granted filesystem access.\n\n## Declare permissions\n\nzotfile 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.\n\nUse `${workspace}`\n\nfor the run's working directory and `${agent_data}`\n\nfor persistent private storage at `$ZOT_HOME/agents/<name>/data/`\n\n. Relative permission paths resolve beneath the workspace. Canonical path checks prevent file tools from escaping a scope through symlinks.\n\n```\n{\n  \"permissions\": {\n    \"fs\": {\n      \"read\": [\"${workspace}\", \"${agent_data}\"],\n      \"write\": [\"${agent_data}\"]\n    },\n    \"bash\": {\n      \"mode\": \"allowlist\",\n      \"allow\": [\"git\", \"go\"]\n    }\n  }\n}\n```\n\n## Set requirements\n\nUse `runtime.min_zot`\n\nfor the minimum runtime, `requirements.os`\n\nfor supported operating systems, and `requirements.bin`\n\nfor programs that must already exist on `PATH`\n\n. zotfiles have no install or postinstall hooks.\n\nModel requirements are provider-neutral. `model.min_context`\n\nsets the minimum context window. `model.requires`\n\naccepts `tools`\n\nand `reasoning`\n\n. `vision`\n\nis recognized but currently fails closed because vision support is not represented in the model catalog. Unknown capabilities and a non-empty `model.min_tier`\n\nare rejected.\n\nzot keeps an explicitly selected or configured default model when it qualifies, then tries `model.preferred`\n\n, then another compatible active model. It stops with a clear error when no catalog model satisfies the requirements.\n\n## Test and package\n\n```\n# Develop directly from the source directory\nzot inspect ./code-reviewer\nzot run ./code-reviewer\nzot run ./code-reviewer \"Review the authentication package\"\n\n# Create and validate the portable artifact\nzot pack ./code-reviewer\nzot verify ./code-reviewer.zot\nzot inspect ./code-reviewer.zot\nzot run ./code-reviewer.zot\n\n# Run directly from a public GitHub repository\nzot run https://github.com/patriceckhart/agents/zot-maintenance \\\n  --cwd /path/to/zot\n```\n\nPacked 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`\n\nform uses the default branch; standard `github.com/owner/repo/tree/ref/path`\n\nURLs select a branch or tag.\n\n## Consent, data, and sessions\n\nBefore 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`\n\n, which requests consent on every launch. Any artifact change creates a new digest and requires approval again.\n\nNon-interactive runs refuse to bypass consent by default. Controlled automation can set `ZOT_AGENT_CONSENT=1`\n\n, but should do so only after independently inspecting and trusting the exact artifact.\n\nAgent history is isolated under `$ZOT_HOME/sessions/agents/<name>/`\n\n, so packaged-agent sessions do not bleed into ordinary zot sessions or another agent's history. Normal session flags such as `--continue`\n\n, `--resume`\n\n, and `--no-session`\n\nstill apply.", "url": "https://wpnews.pro/news/show-hn-introducing-zotfile-agents", "canonical_source": "https://www.zot.sh/docs/zotfiles", "published_at": "2026-07-12 14:34:33+00:00", "updated_at": "2026-07-12 15:05:56.300613+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["Zotfile Agents", "zot"], "alternates": {"html": "https://wpnews.pro/news/show-hn-introducing-zotfile-agents", "markdown": "https://wpnews.pro/news/show-hn-introducing-zotfile-agents.md", "text": "https://wpnews.pro/news/show-hn-introducing-zotfile-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-introducing-zotfile-agents.jsonld"}}