Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add instructions/portolan-sdi/portolan-cli/agents-mdgit clone --depth 1 https://github.com/portolan-sdi/portolan-cliWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/instructions/portolan-sdi/portolan-cli/agents-md)<a href="https://agentmods.dev/instructions/portolan-sdi/portolan-cli/agents-md"><img src="https://agentmods.dev/badge/instructions/portolan-sdi/portolan-cli/agents-md.svg" alt="Measured on agentmods" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.04102 | $0.04102 |
| Opus 5 | $0.02051 | $0.02051 |
| Sonnet 5 | $0.00820 | $0.00820 |
| Haiku 4.5 | $0.00410 | $0.00410 |
Grade A, and why
portolan-cli AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured today.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 259 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Portolan Agent Norms
These rules apply to AI agents working in any portolan-sdi repo. Every downstream repo carries this text verbatim as a synced block at the top of its own AGENTS.md. Repo-specific instructions live below the block and override the canonical rules in that repo only.
Claude Code does not read AGENTS.md. Each repo carries a one-line CLAUDE.md that imports it instead. Put repo-specific instructions in AGENTS.md, never in CLAUDE.md, which the sync overwrites.
Ground Rules
The portolan-spec repo is ground truth for the Portolan standard. The CLI, validator, registry, and every other tool implement the spec. They are downstream of it. Never describe the CLI as the source of truth. Propose spec changes in portolan-spec.
Before documenting any command, flag, or API, verify it exists in the shipped tool. A fabricated example persists beyond the session that wrote it.
Every repo uses Apache-2.0 except portolan-browser and portolan-nl-demo, which are ISC forks. See norms/repos.md for the record. Never introduce code under another license without a human decision recorded there.
Never bypass pre-commit hooks or CI gates. Green means green.
Write commits in conventional form. Squash-merge makes the pull request title become the commit message.
Pull Requests and Issues
Write every issue and pull request in two layers. The human layer comes first: what is wrong or missing, why it matters, and what should happen instead. Someone who did not follow your investigation should understand it in about a minute. The agent layer comes after: evidence, implementation detail, constraints, edge cases, and verification.
There is no word limit. A 700-word issue is good when its first 150 words make the outcome obvious. A 150-word issue is bad when it compresses the meaning into prose the reader has to unpack. Optimize for fast comprehension, not for short tickets.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- today Changed · +3 lines · +200 tokens per session 675fdf1f2b85
- 4d ago First seen · 256 lines · 3,902 tokens per session scan A fb89e1277ab8
portolan-cli AGENTS.md is an instructions file published in the GitHub repository portolan-sdi/portolan-cli (30 stars, last pushed yesterday), licensed Apache-2.0. It adds 4,102 tokens to every session, about $0.0205 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other instructions, from other repositories
vscode buildNext.instructions.md
Working notes and architecture documentation for the new esbuild-based build system in build/next. Use when making changes to the new build pipeline (transpile/bundle commands, NLS plugin, source-map handling, resource copying, or self-hosting watch tasks).
spec-kit AGENTS.md
AGENTS.md instructions for github/spec-kit, covering agents.md, about spec kit and specify, quickstart — add a new integration in 5 steps, integration architecture and integrationmanifest — file tracking.
codex AGENTS.md
AGENTS.md instructions for openai/codex, covering rust/codex-rs, the codex-core crate, code review rules, crate api surface and model visible context.
langchain AGENTS.md
AGENTS.md instructions for langchain-ai/langchain, covering global development guidelines for the langchain monorepo, corridor security analysis, project architecture and context, monorepo structure and development tools & commands.
vscode oss-third-party-notices.instructions.md
Instructions for microsoft/vscode, covering vs code oss third-party-notices pipeline, architecture, pipeline flow in ci, applying the notice (cutover) and fallback chain (never fail the build).
next.js AGENTS.md
Instructions for vercel/next.js, covering next.js development guide, codebase structure, monorepo overview, core package: packages/next and other important packages.