Skip to content
TilloTech Docs

Choose the right surface

Use the smallest surface that matches the persistence, scope, side effects, and trust boundary of the need. The surfaces compose; they are not substitutes for one another.

Decision table

  • Constraint for this task only: use a prompt or plan, not repository configuration. It should disappear with the task.
  • Rule every task in a repository must know: use the target client’s root instruction file, not a skill. Root instructions are loaded before work starts, so keep them short.
  • Convention for one subtree: use a nested instruction file or path-scoped rule, not a root manual. Scope it to the code that needs it.
  • Detailed durable knowledge: use an indexed repository document, not a huge root instruction file. Docs are versioned and can load only when needed.
  • Repeatable procedure or domain judgement: use a skill, not a hook. A skill can reason, branch, read references, and produce an artifact.
  • Repeated deterministic mechanics: use a script or CLI, not rewritten skill prose. Scripts are testable, composable, and shareable with CI.
  • Automatic lifecycle reaction: use a hook, not skill routing. Hooks fire because an event occurred, not because the model remembered.
  • Command allow, prompt, or deny policy: use native rules or permissions, not a best-effort hook matcher. Policy engines are the security boundary; hooks are defense in depth.
  • Installable, versioned capability bundle: use a plugin, not copied repository folders. A plugin packages stable skills, hooks, MCP/app wiring, and assets.
  • Live external data or actions: use an MCP server or connector, not static instructions or web search. The external system owns current state, authentication, and actions.
  • Independent parallel work: use a subagent, not one crowded context. Delegation helps only when work is bounded and genuinely parallel.
  • Isolated implementation checkout: use a worktree or focused checkout, not multiple agents editing one tree. Isolation prevents conflicting writes and reduces irrelevant scope.
  • CI or one-shot automation: use a non-interactive CLI, not an interactive app protocol. A bounded job needs an exit status and artifacts, not a session UI.
  • Embedded agent workflow: use an SDK, not shell parsing. The host application needs typed control over execution and results.
  • Interactive resumable client: use App Server or an equivalent event runtime, not a one-shot CLI. The client needs streaming, approvals, cancellation, and reconnects.
  • Durable result or handoff: use a versioned artifact with a declared location, not a final chat message. Later steps and reviewers need evidence that survives conversation state.

Product mapping

  • Root guidance: Codex uses AGENTS.md; Claude Code uses CLAUDE.md. Keep one canonical body with a verified symlink or a thin client-specific router.
  • Nested guidance: Codex uses nested AGENTS.md files; Claude Code uses nested CLAUDE.md and path-scoped .claude/rules/*.md. Put detailed truth in shared docs and keep vendor entry files small.
  • Repository skills: Codex uses .agents/skills/<name>/SKILL.md; Claude Code uses .claude/skills/<name>/SKILL.md. Author one Agent Skills-compatible workflow and mirror or package it deliberately.
  • Skill UI and dependencies: Codex uses agents/openai.yaml; Claude Code uses frontmatter and supporting files. Keep vendor metadata outside the shared workflow where possible.
  • Project settings: Codex uses .codex/config.toml in trusted repositories; Claude Code uses .claude/settings.json. Do not assume inheritance or trust behavior is equivalent.
  • Hooks: Codex uses .codex/hooks.json or inline configuration and currently runs command handlers. Claude Code supports command, prompt, agent, and HTTP hooks in settings or plugin configuration. Share scripts, not configuration assumptions, and test event semantics per client.
  • Command policy: Codex uses .codex/rules/*.rules, sandboxing, approvals, and managed requirements.toml; Claude Code uses permissions in settings and managed policy. Use the native policy layer for hard boundaries.
  • Plugin manifest: Codex uses .codex-plugin/plugin.json; Claude Code uses .claude-plugin/plugin.json. A shared plugin root may need two manifests and client-specific components.
  • Plugin catalogue: Codex uses .agents/plugins/marketplace.json; Claude Code uses .claude-plugin/marketplace.json. Treat catalogues as distribution metadata, not capability source.
  • External tools: Codex configures MCP in .codex/config.toml or plugin .mcp.json, with app or connector mappings in .app.json; Claude Code uses MCP in settings or plugin .mcp.json. Review each server’s tools, auth, data, and network access independently.
  • Specialized delegation: Codex uses subagents and custom agent profiles; Claude Code uses subagents and plugin agents. Delegate bounded work and expect multiplied context and tool cost.

The product mapping is not an equivalence claim. For example, OpenAI’s current plugin layout documents skills, hooks, MCP configuration, app mappings, and assets, while Anthropic also documents plugin agents, LSP servers, monitors, executables, and default settings. Model the required capability first, then implement only the components the target client supports.

For a dual-client repository, prefer one canonical shared root body. When all required environments preserve repository symlinks, CLAUDE.md can point to AGENTS.md. Otherwise use a small CLAUDE.md that routes to AGENTS.md and contains only Claude-specific launch or settings semantics. Do not maintain two independent copies of shared policy.

Selection questions

Before adding a surface, answer these in order:

  1. Must every task know this? If yes, put the shortest possible rule in the applicable instruction file. Otherwise keep it on demand.
  2. Is this knowledge, judgement, or mechanics? Put knowledge in docs, judgement in a skill, and mechanics in a script or native check.
  3. Should it run automatically? If yes, identify the exact lifecycle event and use a hook. If it must constrain authority, also use permissions or rules.
  4. Does it need current external state? If yes, expose a bounded MCP tool or connector rather than teaching the model an API through prose.
  5. Who consumes and updates it? Keep one-repo workflows local. Package only when multiple consumers need an owned, versioned release.
  6. What is the failure mode? Define fail-open or fail-closed behavior, timeout, idempotency, approval, and recovery before enabling automation.
  7. How will it be evaluated? Specify routing and outcome tests, plus the evidence a human needs to trust a result.
  8. Where will durable state and artifacts live? Define the plan, evidence, and handoff boundary before a workflow can span compaction or clients.

Common compositions

Required repository verification

Use a short conditional trigger in root instructions, a skill to select the applicable checks and interpret failures, scripts to run those checks, and CI to enforce the result. A hook may format changed files, but should not be the only verification gate.

External issue workflow

Use MCP for authenticated issue data and mutations, a skill for the triage or planning procedure, and explicit approval before consequential writes. Package them as a plugin only when the integration and workflow are stable enough for other teams to install.

Protected repository policy

Use native command rules, sandboxing, and permissions as the authority. Add a PreToolUse hook for richer contextual checks and audit output, recognizing that a hook may not intercept every equivalent tool path.

Long cross-package change

Use focused instructions and skills, a durable plan under docs/plans/, one isolated worktree per writer, and subagents only for independent exploration or verification. Preserve decisions and validation in files before compaction.