{"slug": "agent-slugs-are-the-smallest-handoff-key-between-apc-and-apx", "title": "Agent Slugs Are the Smallest Handoff Key Between APC and APX", "summary": "APC and APX, two layers of a developer toolchain, use a stable 'agent slug' as the smallest handoff key between portable project contracts and local runtime state. The slug, defined in APC's structured agent definitions, serves as the routing key for APX commands and runtime file paths, avoiding hidden IDs and keeping the join key simple. Good slugs describe durable responsibilities like 'reviewer' or 'planner', while weak ones leak implementation details and age poorly.", "body_md": "A lot of APC and APX discussion happens at the level of folders, memory, or runtimes. But there is a smaller boundary that matters every day: the agent slug.\n\nAPC is the portable context layer. It keeps the project contract in the repository: `AGENTS.md`\n\n, `.apc/project.json`\n\n, `.apc/agents/<slug>.md`\n\n, skills, commands, and curated memory that is safe to share. APX is the daily-use runtime and tooling layer. It reads that contract, runs agents, stores local runtime state under `~/.apx/`\n\n, and gives you CLI, daemon, and web admin workflows.\n\nThe slug is where those two layers meet.\n\nIn APC, the slug identifies the structured agent definition. In APX, the same slug becomes the routing key for commands like `apx run <slug>`\n\n, `apx exec -a <slug>`\n\n, `apx memory <slug>`\n\n, and `apx session new <slug>`\n\n. APX also uses it to place runtime files under per-agent paths such as `~/.apx/projects/<project-id>/agents/<slug>/sessions`\n\n.\n\nThat sounds small, but it solves a real design problem: how do you keep a portable project contract and a local runtime aligned without inventing hidden IDs for every agent?\n\nThe answer is not to make the runtime smarter. The answer is to keep the join key boring.\n\nIf the shared name for an agent is unstable, everything around it gets noisy.\n\nA stable slug avoids that.\n\nFor example, if a repository defines `.apc/agents/reviewer.md`\n\n, APX can keep using `reviewer`\n\neverywhere:\n\n```\napx run reviewer --runtime claude-code \"Review the open PRs\"\napx exec -a reviewer \"Summarize test risk\"\napx memory reviewer\napx session new reviewer --title \"Follow-up audit\"\n```\n\nThat is a better contract than a display name. You can rename a role description, change the model, or expand the skills list, and the runtime history still lands under the same agent lane.\n\nThe slug should describe the durable responsibility, not the mood of the prompt.\n\nGood slugs:\n\n`reviewer`\n\n`planner`\n\n`backend`\n\n`release-manager`\n\nWeak slugs:\n\n`smart-reviewer-v2`\n\n`best-agent-final`\n\n`claude-helper`\n\n`telegram-reviewer-temporary`\n\nThose weaker names leak implementation details into the project contract. They age badly when you switch models, channels, or runtimes. APC should describe the project role. APX should decide how that role runs today.\n\nAPC keeps the definition portable:\n\n`AGENTS.md`\n\nholds repository-wide rules.`.apc/agents/<slug>.md`\n\nholds the structured agent definition.`.apc/agents/<slug>/memory.md`\n\ncan hold curated, team-safe memory.APX keeps the runtime local:\n\nThat split only stays clean if both sides can point to the same agent identity without translation glue. The slug is enough.\n\nThis is also why APX does not need a second hidden naming system for normal agent work. The portable name from APC already gives the runtime a stable filesystem lane, command target, and audit trail anchor.\n\nPick slugs like you would pick API names.\n\nIf you need to change how an agent behaves, edit the definition. If you need a different responsibility, create another slug.\n\nThat keeps APC readable in the repo and APX readable on disk.\n\nThe bigger APC/APX idea is often described as portable context plus local runtime. That is true. But in daily use, the smallest piece doing real work is often just one good slug.", "url": "https://wpnews.pro/news/agent-slugs-are-the-smallest-handoff-key-between-apc-and-apx", "canonical_source": "https://dev.to/agentprojectcontext/agent-slugs-are-the-smallest-handoff-key-between-apc-and-apx-dom", "published_at": "2026-07-08 12:03:00+00:00", "updated_at": "2026-07-08 12:29:19.472306+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-infrastructure"], "entities": ["APC", "APX", "AGENTS.md", "CLI", "daemon", "web admin"], "alternates": {"html": "https://wpnews.pro/news/agent-slugs-are-the-smallest-handoff-key-between-apc-and-apx", "markdown": "https://wpnews.pro/news/agent-slugs-are-the-smallest-handoff-key-between-apc-and-apx.md", "text": "https://wpnews.pro/news/agent-slugs-are-the-smallest-handoff-key-between-apc-and-apx.txt", "jsonld": "https://wpnews.pro/news/agent-slugs-are-the-smallest-handoff-key-between-apc-and-apx.jsonld"}}