Skip to main content

Artifact Types โ€” When to Use Which

This document is the single source of truth for deciding what shape a piece of platform content should take. Before authoring a new artifact under .claude/ or policies/ โ€” or before consolidating or splitting an existing one โ€” walk the decision tree below.

The platform has six artifact types. Choosing the right one keeps the system predictable: humans can reason about what loads when, the Policy Engine can route triggers correctly, and Claude can locate the right surface to act on without searching the whole tree.

The six artifact typesโ€‹

ArtifactLives atActivationOne-line essence
RuleCLAUDE.md, agent bodies, policies/*.yamlAlways loaded; no triggerAn invariant โ€” "every time you touch X, Y must hold"
Hook.claude/hooks/*.shEvent-driven (pre-commit, PreToolUse, SessionStart, โ€ฆ)Enforcement at the exact moment of an action
Policypolicies/*.yamlPolicy Engine at step 4 of /continueA trigger declaration that loads agents
Agent.claude/agents/<name>.mdPolicy Engine via required_agents, or @agent-nameAn expert persona with its own context window and tool allowlist
Skill.claude/skills/<name>/SKILL.md/name, or progressive load from inside an agentA multi-step procedure with bundled scripts and references
Command.claude/commands/<name>.mdUser types /nameA thin prompt template โ€” an invocation handle

For the broader system, see ai-engineering-strategy.md ยง12โ€“ยง13, policy-engine.md, and autonomy-model.md.

Documentation artifacts (Product / R&D handoff)โ€‹

Distinct from the six platform artifacts above, BeWith uses a small set of documentation artifacts that capture the lifecycle of a feature from product intent to shipped code. Each has a clear owner and lives at a specific path.

ArtifactOwnerWhen writtenLives atTemplate
ProposalAnyoneEarly, side-project sized ideadocs/proposals/proposal-YYYY-MM-DD-<slug>.mdproposal
PRDProductAfter idea is committed todocs/prds/<slug>-<cu-id>.mdprd
Design DocR&DAfter PRD reaches ready-for-rddocs/designs/<slug>-<cu-id>.mddesign-doc
RFCWhoever drivesMulti-team / week-plus / contract-changing changedocs/rfcs/rfc-<slug>.mdrfc
ADRR&DAfter a technical decision is madedocs/adrs/adr-NNN-<slug>.mdadr
Decision LogAnyoneAfter a product/business decision is madedocs/decisions/<slug>.mddecision
RunbookOperations / R&DRepeatable human proceduredocs/runbooks/<name>.mdrunbook

The PRD โ†’ Design Doc pair is the spine of feature delivery. A PRD without a Design Doc is product-only ideation; a Design Doc without a PRD is R&D guessing what to build. The pipeline that ties them is documented in Product โ†” R&D Handoff.

Boundary rule (between PRD and Design Doc):

  • The PRD captures WHAT and WHY โ€” problem, requirements, UI references to the design-system catalog, analytics events to fire, API-accessible capabilities (as business statements).
  • The Design Doc captures HOW โ€” endpoint shapes, schemas, architecture, task breakdown. It is R&D's translation, never authored by Product.

If you find product writing endpoint paths or engineering writing user stories, the boundary is being violated. Move the content to the right document.

Frontmatter conventionsโ€‹

Every artifact under .claude/ and policies/ carries YAML frontmatter declaring its identity and discovery metadata. Two fields are universal; one is context-specific.

name, description, tags (universal)โ€‹

  • name โ€” kebab-case identifier, must match the filename / directory.
  • description โ€” one-line summary used by /help-me and the capability index.
  • tags โ€” array of keywords used to group artifacts in docs/capabilities.md.

audience (REQUIRED on agents, skills, commands, and policies โ€” see ยง"Audience" below)โ€‹

audience: dev | product | both โ€” declares which user role the artifact serves. The capability-awareness hook and /help-me filter offers by intersection with the current user's role (set via /role).

  • audience: dev โ€” surfaced only when user's role is dev (the default for everyone). Examples: code-reviewer, process-guardian, /breakdown.
  • audience: product โ€” surfaced only when user's role is product. Examples: prd-writer (when Phase 2 of the ABC-TOM merge lands), gatekeeper, intake skill.
  • audience: both โ€” surfaced regardless of role. Examples: /help-me, /new-artifact, /propose, /role itself.

Rules and hooks do not carry audience โ€” rules are always-on invariants, and hooks fire on events rather than appearing in discovery surfaces.

If an artifact is missing the audience field, the capability-awareness hook treats it as both during the transition window and surfaces a one-line warning the first time it appears in a session. New artifacts must declare audience explicitly โ€” the unset default exists only for legacy content not yet swept.

See docs/proposals/proposal-2026-05-31-user-role-and-audience-filtering for the design.

Decision treeโ€‹

Walk these questions top-down. The first "yes" picks the shape.

  1. Must this apply every time, with no trigger needed? โ†’ Rule. Place it in CLAUDE.md for platform-wide invariants, in an agent body for domain-narrow ones, or in policies/*.yaml if it is a structured trigger.

  2. Must this block or enforce at the exact moment of an action? (before a commit, before a tool runs, on session start) โ†’ Hook in .claude/hooks/. Hooks typically pair with a rule โ€” the rule states the invariant, the hook enforces it.

  3. Does this declare which agents to load when certain conditions are met? โ†’ Policy in policies/. Policies have required_agents; the Policy Engine evaluates them at step 4 of /continue and aggregates the agent set.

  4. Is this a multi-step procedure you would re-run the same way, with optional scripts or data bundled alongside? โ†’ Skill in .claude/skills/<name>/. Lightweight; invocable by an agent, by a user, or by a command. Progressive loading: metadata first, then SKILL.md, then bundled resources.

  5. Does this require sustained expert judgment, a protected context window, and a restricted tool allowlist? โ†’ Agent in .claude/agents/<name>.md. The heaviest artifact โ€” use sparingly. Reserve for domains where the AI must hold deep specialised context.

  6. Is this a user-typed entry point that needs $ARGUMENTS and a stable, discoverable name? โ†’ Command in .claude/commands/<name>.md. Almost always a thin wrapper around a skill or an agent invocation.

If a candidate fits two shapes, prefer the lighter one. Ordered from light to heavy:

rule  <  command  <  skill  <  agent  <  hook  <  policy

(Hook is heavier than agent in the sense that it executes outside the AI's context and cannot be debated; policy is heaviest because it pulls full agents into context when it fires.)

Consolidation is the defaultโ€‹

Splitting an agent or a skill requires a concrete reason that one of the layers is needed only sometimes โ€” different cadence, different risk profile, different access pattern. The default is consolidation.

Examples of correct consolidation:

  • The design system โ†’ one design-system agent owning tokens, component library, Storybook conventions. Not three separate ux-designer + component-library + storybook agents.
  • Database work โ†’ one database agent owning schema design, indexing, document size, migrations, rollback, query patterns. Not separate database-design and database-migrations agents.
  • Decision recording โ†’ the decision-record skill (/decision) plus a rule carried by architect and product-manager. One skill routes both homes (ADR for technical, decision log for product/business) โ€” not a dedicated decision-recorder agent, because the judgment about whether a decision is escalation-worthy belongs to the caller.

Before proposing a split, state explicitly: "X is needed only when Y, and Y is rare enough that loading the full bundle would be waste." If that sentence does not write itself cleanly, do not split.

Non-duplication principleโ€‹

Every fact lives in exactly one place. Other artifacts link to it. Duplication creates drift; references stay correct.

command  โ†’ skill                  (commands invoke procedures)
command  โ†’ agent (via @agent)     (commands invoke experts)
agent    โ†’ skill                  (agents call procedures progressively)
agent    โ†’ policy                 (an agent may read its own triggering policy)
policy   โ†’ agent (required_agents)(policy declares which agents it loads)
skill    โ†’ scripts/refs (own dir) (a skill bundles its own assets)
hook     โ†’ script (own .sh)       (hook implementation lives next to declaration)

Illegal patternsโ€‹

  • Cycles of any length: A โ†’ B โ†’ A, A โ†’ B โ†’ C โ†’ A. If an agent calls a skill, that skill must not call the agent back.
  • Lateral duplication: two agents (or two skills) carrying the same conceptual content. One must own; the other links.
  • Upward references: a skill referencing a specific calling agent by name. Skills must be agent-agnostic so multiple agents can reuse them.
  • CLAUDE.md leakage: a rule appearing both in CLAUDE.md and in an agent body. CLAUDE.md is the project-wide ceiling; agents narrow it but never restate it.

Detecting driftโ€‹

During PR review on changes that touch .claude/ or policies/:

  • Build the reference graph from frontmatter and [[wiki-links]]; fail on cycles. (Validator script scripts/checks/artifact-graph.mjs is TODO; until it lands, the review is manual.)
  • Search the platform for any phrase longer than ~15 words appearing in two places โ€” that is a duplication candidate.
  • Search for an agent's name (kebab-case) inside any skill โ€” that is an upward reference and must be removed.

Worked examplesโ€‹

Each example below shows how the heuristic resolves a real platform question. These are reference cases โ€” use them as templates for similar decisions.

Accessibility (WCAG AA, RTL, keyboard, screen readers)โ€‹

  • Procedure (run axe, check contrast ratios, validate focus order, test keyboard nav) โ†’ skill a11y-review.
  • Invariant ("no UI ships without an a11y pass") โ†’ rule in frontend-developer.md and design-system.md. Optionally a policy with required_skills: [a11y-review] on PRs touching UI paths.
  • A dedicated agent is not warranted: BeWith UIs are largely internal-facing; the judgment surface is narrow enough to live as rules + a skill.

Storybookโ€‹

  • Invariant ("every component needs a story") โ†’ rule in design-system.md.
  • Procedure ("how to write a good story โ€” argTypes, controls, Chromatic, i18n in stories") โ†’ skill bundled with the design system, or referenced by design-system agent.
  • Not an agent: surface is mechanical, no judgment.

Decision recording (ADR / decision log)โ€‹

  • The act of capturing a discussion that reached decisions (route to the right home, fill the template, update the index, then hand action items to /breakdown) โ†’ skill decision-record, invoked by /decision. One skill covers both homes โ€” docs/adrs/ for technical/architectural decisions, docs/decisions/ for product/business/process โ€” because the procedure is identical and only the destination template differs (consolidation, not a split).
  • The invariant ("any cross-domain or hard-to-reverse decision must open a GitHub issue, hold discussion, and produce a record") โ†’ rule carried by product-manager and architect.
  • Not a dedicated decision-recorder agent: judgment about whether a decision is escalation-worthy belongs to the caller; mechanical creation is a skill.
  • The decision record is an intake artifact above tasks โ€” its action items feed /breakdown. It is distinct from a design doc, which sits below a task (per task, after research). See planning-docs.md.

Contracts (FE โ†” BE schemas)โ€‹

  • Cross-repo schema layer (Zod, OpenAPI, RPC schemas โ€” exact shape depends on the audit of BeWith repos) โ†’ agent contracts-schema owning versioning and breaking-change discipline. The judgment surface is rich enough to justify an agent.
  • The rule "any schema change touching public surfaces must update version + downstream consumers" lives in the agent body and is triggered by policies/api-contract-change.yaml.
  • A skill /contracts-bump (TBD) can mechanise the version bump and the consumer-notification step.

Cross-review by another modelโ€‹

Tempting candidate for a /cross-review skill. Correct framing under autonomy-first: cross-review is a step that should happen automatically inside /adr and design-an-interface, not a user-triggered skill. Manual triggers for recurring quality steps are smells.

Authoring invariants โ€” beyond the type choiceโ€‹

Any new artifact that mutates git state (a skill that opens a PR, a script that pushes a branch) must additionally satisfy the rules in session-safety.md: operate in an isolated git worktree, pre-flight refuse on branch collisions, never touch the developer's main checkout. The artifact-type choice picks the shape; session safety picks the execution model. Both must be settled before the artifact lands.

Cross-referencesโ€‹