Skip to main content

New artifact authoring

This skill is the canonical entry point for any developer who wants to add or modify a platform artifact in bewith-docs. It enforces the artifact-types decision tree, prevents duplication, and produces a reviewable PR.

When to invoke​

Trigger whenever a developer expresses intent to add or change platform content:

  • "I want to create an agent / skill / command / rule / hook / policy"
  • "Let's add a skill that does X"
  • "We need a command for X"
  • "Add a rule that says Y"
  • Hebrew equivalents: "אני רוצה ליצור agent", "צריך skill ל...", "נוסיף command", וכו'.

Do not invoke this skill for:

  • Questions about how the platform works — read docs/methodology/ directly.
  • Adding application code to a consumer repo — this skill is for the platform repo only.
  • Modifying an existing artifact's content without changing its shape — those edits should be straightforward and don't need the full audit.

Steps​

1. Gather intent​

The developer should not have to think in platform terms. Ask in plain language with concrete options. Skip any dimension already answered in the request.

The only open question:

Describe what you want in one or two sentences, with a concrete example. (For example: "I want something that warns me when a commit message lacks a CU-id" or "I want a reviewer for backend security issues".)

Fill in the rest from that answer. If a dimension is still genuinely ambiguous after the description, ask only the ambiguous dimension(s) as a multi-choice — never abstract platform jargon, always plain options the developer can pick without thinking:

When should it run? (pick one or more)

  • (a) On every commit or other git event
  • (b) When I type a slash command (e.g. /<name>)
  • (c) Automatically whenever certain files or paths are touched
  • (d) Always — it's a constraint that just applies
  • (e) When another part of the workflow needs this procedure
  • (f) When I want a deep expert review on a judgment-rich topic

What kind of output? (pick one)

  • (a) A check that blocks a bad action (e.g., prevents a bad commit)
  • (b) A repeatable procedure that produces consistent results
  • (c) An expert opinion or review
  • (d) A constraint that always holds

Once enough is known, restate the intent in one sentence and proceed. Do not ask all questions if the description already answers them.

2. Audit existing artifacts​

Before drafting anything, scan the platform for prior art. Use Grep and Glob:

Search targetPathLooking for
Agents.claude/agents/*.mdAn agent that already owns this domain
Skills.claude/skills/*/SKILL.mdA skill with overlapping procedure
Commands.claude/commands/*.mdAn existing slash command for this intent
Policiespolicies/*.yamlA policy that already declares this trigger
Rules in agents.claude/agents/*.mdA rule body that already covers the invariant
Hooks.claude/hooks/*.shA hook already enforcing this at action-time
Methodologydocs/methodology/*.mdExisting methodological framing

Report findings to the developer. If overlap is ≥80% with an existing artifact, propose updating that artifact instead of creating a new one. Do not let "but mine is slightly different" win — splitting an existing concern requires the consolidation test from docs/methodology/artifact-types.md.

3. Pick the artifact type(s)​

Walk the decision tree in docs/methodology/artifact-types.md. Cite the deciding question (1–6) explicitly. Present the choice with one-line justification.

A single intent often maps to more than one artifact. Propose a bundle whenever the intent has both a procedure and an entry point, or both an invariant and enforcement, or both a trigger and the expert(s) it loads. Common bundles:

Intent shapeTypical bundle
Repeatable procedure with a discoverable slash entry pointskill + command
Invariant enforced automatically at the moment of actionrule + hook
Trigger declaration with the expert(s) it loadspolicy + one or more agents
Expert review on a recurring triggerpolicy + agent (+ skill the agent calls)
User-typed entry point that needs deep expertisecommand + agent

Bundling is not the same as splitting. Splitting violates the consolidation rule when two artifacts of the same type carry overlapping concerns. Bundling is correct when the artifacts play different roles (e.g., a skill is the procedure; a command is the discoverable name for it). This very skill (new-artifact) was authored as a skill + command bundle for exactly that reason.

If a candidate fits two shapes for the same role, default to the lighter one. Ordered light → heavy:

rule  <  command  <  skill  <  agent  <  hook  <  policy

If the bundle choice is genuinely ambiguous between two options, present the options to the developer as a quick multi-choice with one-line descriptions — do not make them read the decision tree.

Deterministic gate (code before model). Before settling on any artifact that asks the model to reason through a repeatable procedure, ask: can this step be a deterministic script the artifact invokes instead? A fixed, parameterized script with tracked output is cheaper and more reliable than model reasoning for anything mechanical (parsing, counting, formatting, a fixed sequence of shell/gh/git calls). If yes, the artifact becomes a thin wrapper (often a command) around that script — not a skill that re-derives the procedure each run. This is the Tier-0 lever from context-and-cost-economy.md; apply it here so cost discipline is designed in, not retrofitted.

4. Check for duplication and cycles​

For the proposed artifact, verify:

  • No phrase >15 words duplicates content from another artifact. Use Grep on distinctive phrases from the draft.
  • Reference direction is legal: agent → skill is fine; skill → specific-agent is not. Skills must be agent-agnostic so multiple agents can reuse them.
  • No cycles of any length (A → B → A, A → B → C → A). Build the reference graph mentally from the frontmatter and any [[wiki-links]] or relative-path links.
  • No CLAUDE.md leakage: if the artifact is a rule, ensure it does not duplicate CLAUDE.md. CLAUDE.md is the project-wide ceiling; agents narrow it without restating it.

If any check fails, fix the draft before opening the PR.

5. Draft the artifact(s)​

Use the canonical template for each chosen type. When drafting a bundle, draft all members together so cross-references between them are correct from the start:

TypeTemplate / patternLocation
Agent_template.md — 7-section body, frontmatter with name, description ("use proactively"), tools allowlist, model: inherit. Size target 15–25 KB..claude/agents/<name>.md
SkillAnthropic SKILL.md pattern — YAML frontmatter (name, description with triggers), progressive body, optional bundled scripts/refs in the same directory..claude/skills/<name>/SKILL.md
CommandFrontmatter (description) + body that tells the AI how to execute. Use $ARGUMENTS for parameters. Thin wrapper around a skill or agent..claude/commands/<name>.md
RuleDepends on scope. Platform-wide → CLAUDE.md. Domain-narrow → agent body. Structured trigger → policies/*.yaml.varies
HookBash script with a # tags: / # description: header. Must be wired into .claude/hooks/hooks.json — see step 5a (a script alone never fires). Honour feedback-validator-dependencies (.mjs per-file, not "type": "module" at root)..claude/hooks/<name>.sh
PolicyYAML validated against policies/schema.json. Must declare required_agents.policies/<name>.yaml

All content in English (chat may be Hebrew, artifacts must be English). No placeholder values to satisfy validators (no CU-pending, TBD, xxx). If a value is unknown, leave the section out and flag it as an open question instead.

Every artifact must declare tags: [...] (one or more from the vocabulary in scripts/build-capability-index.mjs) and a description under 300 chars. Policies use summary: instead of description for the index. Without these, the pre-commit hook will block. See docs/capabilities.md for the auto-generated index this metadata feeds.

5a. Register a hook into hooks.json (hooks only)​

A hook script alone does nothing — it must be wired into .claude/hooks/hooks.json, the plugin's hook registry. This is part of authoring the hook, not a follow-up — wire it in the same change, or the hook ships dead. Add an entry under the correct lifecycle:

  • SessionStart · UserPromptSubmit · Stop · SessionEnd · Notification — no matcher; append to that lifecycle's hooks array.
  • PreToolUse · PostToolUse — matcher-scoped; add to the existing group whose matcher regex already covers your tools (e.g. Edit|Write|NotebookEdit, Bash), or add a new { "matcher": "...", "hooks": [ ... ] } group.

The entry shape — always ${CLAUDE_PLUGIN_ROOT}-relative so it resolves in any consumer repo:

{ "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/.claude/hooks/<name>.sh" }

Order within a group deliberately: a hook that can BLOCK (exit 2) should sit before a cheap fail-open hook only when blocking early is the intent. Once wired, the hook auto-appears in the Hooks reference under the lifecycle you chose and in capabilities.md on the next commit — no manual index step. Other artifact types (agents, skills, commands, policies) are discovered by directory and need no registration here.

6. Open the PR — worktree-isolated​

Use the worktree pattern defined in docs/methodology/session-safety.md. Never operate on the developer's primary worktree — a concurrent session may be editing it.

6a. Locate the bewith-docs checkout. Resolve $BEWITH_DIR using the canonical cascade in docs/methodology/session-safety.md — "Locating the bewith-docs checkout". If no clone is found, stop and tell the developer.

6b. Branch naming (enforced by git-hooks/branch-name-check.sh):

feature/new-<type>-<kebab-name>     # for new artifacts
feature/update-<type>-<kebab-name>  # for updates to existing

Examples: feature/new-agent-design-system, feature/new-skill-a11y-review, feature/update-policy-api-contract-change.

6c. Pre-flight — refuse if the branch already exists:

git -C "$BEWITH_DIR" fetch origin master --quiet
if git -C "$BEWITH_DIR" rev-parse --verify --quiet "refs/heads/${BRANCH}" >/dev/null; then
  echo "ERROR: branch ${BRANCH} already exists locally. Pick a different slug or delete the stale branch." >&2
  exit 1
fi
if git -C "$BEWITH_DIR" ls-remote --exit-code origin "${BRANCH}" >/dev/null 2>&1; then
  echo "ERROR: branch ${BRANCH} already exists on remote — probably an in-flight artifact authoring session." >&2
  exit 1
fi

6d. Create an isolated worktree:

WORKTREE="$(mktemp -d -t bewith-new-artifact.XXXXXXXX)"
git -C "$BEWITH_DIR" worktree add -b "${BRANCH}" "${WORKTREE}" origin/master

Write all drafted files into the worktree, not into $BEWITH_DIR directly. The worktree shares .git/ with the primary worktree but has an independent working directory.

6e. Commit, push, and open the PR from inside the worktree:

cd "${WORKTREE}"
git add <list-of-drafted-files>
git commit -m "feat(<type>): <one-line summary>"
git push -u origin "${BRANCH}"

PR title — short, includes the artifact type and name:

  • feat(agents): add design-system agent
  • feat(skills): add a11y-review
  • feat(commands): add /new-artifact
  • feat(policies): update api-contract-change triggers

PR body — required sections, in this order:

## Summary
<one paragraph describing the new or updated artifact, in plain English>

## What was missing
<the concrete gap this fills. Cite the decision-tree question from
docs/methodology/artifact-types.md that selected this artifact type, and
say why the existing platform did not already cover it.>

## What we added
<bulleted list of files created or modified, with one-line purpose for each.
Group by type: agents, skills, commands, rules, hooks, policies, docs.>

## How we avoided duplication
<list of existing artifacts considered and why this is not redundant with them.
Confirm reference direction (no `skill → specific-agent`). Confirm no cycles.>

## Open questions
<anything still TBD that should be discussed in review. If "None", say so explicitly.>

## Links
- Decision tree: docs/methodology/artifact-types.md
- Related ClickUp task: <ID or "none">
- Related GitHub issues: <links or "none">
- Artifacts that reference this one or that this one references: <list>

Use a HEREDOC for the body in gh pr create so newlines survive. After opening, do not merge — wait for review.

6f. Cleanup the worktree (always, even on failure paths — use a trap):

git -C "$BEWITH_DIR" worktree remove --force "${WORKTREE}"

The remote branch and PR remain; only the local temporary worktree is removed.

6g. Why this matters​

This step is non-negotiable. A concurrent session in the developer's primary worktree — common when Ariel has session A on feature/X and triggers /new-artifact from session B — would otherwise see its branch switched and its unstaged work surfaced as conflicts. The worktree pattern eliminates that whole class of failure. See docs/methodology/session-safety.md for the underlying discipline.

Anti-patterns​

  • Skipping the audit step "to save time" — duplication is the most common failure mode for new artifacts. Always grep first.
  • Authoring in the developer's primary worktree instead of a worktree — step 6 is non-negotiable. See docs/methodology/session-safety.md.
  • Splitting concerns across multiple artifacts when one would do. See the "Consolidation is the default" section in docs/methodology/artifact-types.md. Singalong has separate ux-designer, component-library, and storybook agents; BeWith correctly merges them into one design-system.
  • Proposing a manual user-triggered skill when an auto-trigger inside an existing agent would do. Manual triggers for recurring quality steps are smells (see the autonomy-first memory).
  • Authoring in Hebrew. All artifacts must be English. Chat with the user can be Hebrew.
  • Adding placeholder values (CU-pending, TBD, xxx) to satisfy validators. Fix the gate or omit the section.
  • Merging the PR yourself. Open it and wait for review.

Cross-references​