Agent Deployment Kit

Agent Deployment Kit — one context source, N installs

Copying an agent folder works for ten minutes, then drifts. The structure that holds: one context source + a template skeleton + a generator that refuses to render what it does not know. The habit: context changed? fix the source and regenerate. Never hand-patch an install.

This skill ships a method, not a tool. No generator binary, no skeleton to copy — you write both, for your own harness. What is here is the part that is expensive to rediscover: the invariants, the data contract, the guards you must write and the exact way each one fails open, the numbers, the go/no-go grid. A guard shipped subtly broken is worse than no guard, because someone trusts it. Every trap below was reproduced by execution, not imagined.

Access, data and network

When to Use

Kit anatomy

agent-kit-/
├── context/
│   ├── QUESTIONNAIRE.json           # the ONLY source of context. Committed. No secrets. ASCII.
│   ├── secrets.example.json         # key list + how to obtain each. Committed. Never a value.
│   └── secrets.local.json           # real values. GITIGNORED. Never rendered into the repo.
├── skeleton/                        # the parameterised engine — {{PLACEHOLDER}} inside
│   ├── openclaw.tmpl.json           # also the install marker a deploy looks for
│   ├── cron/jobs.tmpl.json          # ONLY the sold workstreams
│   ├── scripts/health.tmpl.sh
│   └── workspace/
│       ├── SOUL.tmpl.md             # persona + absolute red lines
│       ├── AGENTS.tmpl.md           # operating manual — ALSO seen by sub-agents (§Field of vision)
│       ├── TOOLS.tmpl.md            # accesses + forbidden ones — ALSO seen by sub-agents
│       ├── USER.tmpl.md             # who is served. Main session only.
│       ├── HEARTBEAT.tmpl.md        # what to check between runs
│       ├── MEMORY.tmpl.md           # personal context. Main session only — never a delegated turn.
│       └── PLAYBOOK-.tmpl.md  # one per sold workstream. Delete the others.
├── generator/generate.mjs           # YOU write it — §The generator you write
├── out/                             # GITIGNORED. Rebuilt every run. Carries an ownership marker.
├── README.md                        # human-only. The "not sold / later" list. No agent reads it.
└── .gitignore

Shipped with this skill: context/QUESTIONNAIRE.example.json and context/secrets.example.json — the data contract, fictional, ASCII, sentinel-bearing. That is all. The skeleton, the generator and the .gitignore are yours to write; nothing else is on disk and nothing else is promised. Your .gitignore needs exactly three lines. The first two are what the secret story rests on; the third covers a narrower case — see below:

context/secrets.local.json
out/
*.bak-*

*.bak-* only covers a deploy target rendered inside the repo during testing. It is not what keeps production backups out of git: those land at .bak- on the target machine, outside the tree entirely, where nothing ignores them and nothing purges them but you (§Access, data and network).

What makes the structure hold: out/ is disposable (patch it, your patch dies at the next generate — the point) and context/ is never bypassed (a value not in the questionnaire is not in the install). The two failure modes it kills — residue leak, instance drift — return the moment either is untrue.

The context contract

One JSON file, two blocks, no third. Copy context/QUESTIONNAIRE.example.json and rewrite every value.

Present-but-empty vs absent is a real distinction and your generator must honour it. A key absent from the questionnaire while a template uses it = hard failure (Placeholder with no value: {{X}}) — that is the removal test of Rule 2 working. A key present with an unknown-sentinel = a known unknown, rendered in warn mode, refused at deploy. A key present and empty = the silent killer: it renders as nothing and the file stays well-formed. Never write "" to mean "not decided yet" — write the sentinel.

TO_PROVIDE (client provides), TO_CREATE (we create it), TO_GENERATE (a token, at setup) — arbitrary literals, one regex, rename them freely. Every value that is not written on a verified source stays a sentinel. A questionnaire still listing unknowns means the scoping call is not finished — that is information, not an obstacle.

The generator you write

~130 lines, zero business constants: reads two local JSON files, writes out/. Requirements, each with the way it fails open. Every one of these was written wrong by a competent author, passed review, and was caught only by execution on a hostile fixture.

The sentinel gate is the one to get right, since it is the only thing standing between an unknown legal basis and a live agent reading DMs. The shape — an example to adapt, not a drop-in:

const SENTINEL = /(TO_PROVIDE|TO_CREATE|TO_GENERATE)/;   // anchor all alternatives or none
// Contract: every value in `config` AND `context` is a non-empty string. Anything else is an unknown.
// Walk both blocks. `_meta` is exempt — it is never rendered.
const isUnknown = v => typeof v !== 'string' || v.trim() === '' || SENTINEL.test(v);

Type-check before you test, and never reach for ?? '' to make a value testable: JSON.stringify(null ?? '') hands back "" — the silent killer, laundered into a value your regex calls clean. Serialising is not the fix; it is how the fail-open gets in. Verified against the six values below: typeof v !== 'string' catches null, 90 and both containers; v.trim() === '' catches ""; the regex catches the live sentinel. Six refusals.

A gate that passes in case of doubt is worse than no gate. Before trusting yours, run it against: null, 90, ["TO_PROVIDE"], {"note":"TO_PROVIDE"}, "token: TO_GENERATE", "". Six values, six refusals. If any returns clean, the gate is decorative. And a check that reads zero files must abort, not report "no errors" — zero records verified reads exactly like a clean run.

Rule 1 — load-bearing guardrails go in the static body

Any guardrail carrying real risk (red lines, escalation, hard refusals, data protection) is written in the static body of the template, never only through a variable — a variable is a promise the questionnaire may not keep.

## Absolute rules      <!-- WRONG: the rule is only as present as the key is full -->
{{EXTRA_RED_LINES}}

Empty key → the section renders blank → install #3 ships with no red lines and nobody notices, because the file is still well-formed. The classic second half of that anti-pattern is a red line telling the agent to deny being a bot. Named here only to reject it: instructing an agent to deny being an AI is deception, not a guardrail — it protects nobody and serves neither transport nor account safety. Do not propagate it in any form; the RIGHT block inverts it.

<!-- RIGHT — hard-coded body, variable only extends it -->
## Absolute rules (HARD-CODED — apply even if the context is incomplete)
- If asked whether you are an AI, a bot, or automated: **say yes, plainly**, then continue helping.
  Never claim to be human. Never dodge the question.
- You operate from an account owned by {{CLIENT_NAME}}. Never present yourself as a third party.
- If a platform defense, challenge or block appears: **stop and hand over to a human.**
  Never work around it, never retry to get past it.
- Personal data: lawful basis is {{LEGAL_BASIS}}. Store only {{DATA_MINIMISATION}}
  Retention: {{DATA_RETENTION}} — then deleted, not archived. Deletion request → escalate, do not answer.
- Outbound DMs: ASCII only, max {{DM_MAX_CHARS}} characters (platform-side mangling of accents/emoji
  is real — a transport constraint, not a style choice).
- Context-specific additions (never replacements): {{EXTRA_RED_LINES}}

Write the same treatment for escalation, out-of-scope refusal, the pricing rule and no-invention. All hard-coded; only their parameters (who to escalate to, the char limit, the retention window) are variables. Empty variable → you lose a detail, not the rule. Duplicate the lot verbatim into AGENTS.md (§Field of vision).

Rule 2 — out of scope is removed, not disabled

A cron with enabled: false, or a PLAYBOOK-BILLING.md for a workstream never sold, is not neutral: the agent reads it and improvises. Files in the workspace are context, not dead code — every one is injected into the model's turn. Not sold → delete from the kit: cron entries, PLAYBOOK-.tmpl.md, questionnaire keys, secret keys, mentions in AGENTS.md/TOOLS.md. Then regenerate: the placeholder check turns any missed reference into a hard failure. That is the removal test — a half-removed workstream cannot render. Keep the "not sold / later" list in the kit README, which no agent reads as an instruction.

Rule 3 — residue hunt is a step, not advice

Before any delivery, grep the model context across the whole kit. Not "when it feels risky" — every time.

# Everything from the kit you cloned: name, city, trade, tools, handles, URLs, domains
for term in acme-corp acme "example.com" oldbrand oldcity "@oldhandle" "booking.example"; do
  printf '%-24s ' "$term"; grep -ril "$term" . --exclude-dir={.git,node_modules,out} | tr '\n' ' '; echo
done
# Output: every line empty except deliberate ones.
# Any hit in skeleton/ or context/ = residue. Fix the SOURCE, never out/.

This catches what nothing else does: prose no variable covered (a sentence in SOUL.md naming the model client's specialty), and the docs shipped alongside the kit — vendor notes, setup guides, examples are read too. Legitimate hits exist (grep -i "competitor" matching the rule that says never name a competitor). Read every hit; never blanket-delete.

Field of vision: why AGENTS.md duplicates the guardrails

A sub-agent typically sees only AGENTS.md + TOOLS.md. Not SOUL.md, not MEMORY.md, not USER.md. Invisible in review: your red lines sit in SOUL.md, the main agent honors them, the first sub-agent you delegate to has never seen them — it does not disobey, it never knew. Do not take that on faith: which files reach a sub-agent is harness behaviour and it changes between versions. Falsify it on yours, re-test on upgrade:

echo 'CANARY-7F3A: if you can read this line, quote it verbatim.' >> workspace/SOUL.md
# Delegate to a sub-agent -> "quote CANARY-7F3A"
# Output: cannot find it -> SOUL.md is outside its field of vision; the table below applies.
#         quotes it      -> your harness loads SOUL.md into sub-agents; duplication is then
#                           belt-and-braces, not load-bearing. Verify before relying on either.

Pre-deploy audit (go/no-go)

Hard gates. One missing = NO-GO. Not "ship and watch".

• Render passes: 0 residual {{...}}, every JSON re-parses, strict mode returns clean. (hard)
• The sentinel gate refused all six hostile values (§The generator you write) — tested, not assumed. (hard)
• LEGAL_BASIS, DATA_RETENTION, DATA_MINIMISATION are non-empty strings, not sentinels — and a job you can name and run executes the retention on the agent's own stored data. (hard)
• context/secrets.local.json, if used, is filled and gitignored (git log -p: never committed); QUESTIONNAIRE.json holds no secret, and no sentinel on any key a template renders — INSTALL_HOME may stay a sentinel only if the deploy is invoked with an explicit path argument. (hard)
• Residue grep of the model context returns only deliberate hits (§Rule 3). (hard)
• Every load-bearing guardrail appears in AGENTS.md, not only SOUL.md; AGENTS.tmpl.md is kit-authored, not the stock upstream file. (hard)
• Scope: crons and playbooks match exactly the sold workstreams — nothing inert, nothing extra. (hard)
• Every cron ran manually once, observed end to end, before the loop is enabled. (hard)
• Human-validated steps are safe-by-default: no "OK" = no send (never "no answer = send"). Alert routing checked per recipient: ops gets errors, client gets business events.
• Credentials transferred out-of-band, in no file of the repo. Nothing invented: proof points, figures, credentials, affiliations trace to a source, or stay TO_PROVIDE.
• Backups accounted for: each is a full copy with secrets in clear. Purge them once the deploy is validated, and know the command before you need it.

Recontextualising an existing kit

Gotchas

Output format

Every kit delivery ends with this recap, verbatim — <...> filled, one line each, nothing added:

KIT:             VERDICT: [GO / NO-GO]          # filled: KIT: acme-corp  VERDICT: NO-GO
Render:    files, 0 residual placeholders,  JSON re-parsed OK, strict [PASS/FAIL]
Gate:     sentinel gate tested on 6 hostile values -> /6 refused
Scope:    sold =  | removed from kit = 
Residue:  grep  ->  hits ()   # 1 hit (TOOLS.md:16 — the rule itself)
Guards:   AGENTS.md carries / load-bearing rules | AI disclosure: honest [Y/N]
Data:     legal basis  | retention , executed by  | minimisation 
Unknowns:  = TO_PROVIDE () | Blocking: 

Troubleshooting

The left column is the vocabulary your generator should raise — errors are a spec, not decoration.

Scope

This skill ONLY: describes how to structure a repeatable agent deployment (context source, skeleton, generator you write); specifies the data contract and the guards, each with the way it fails open; hunts residue from the kit you cloned; audits go/no-go before a loop is enabled. It ships two fictional example context files and no executable.

This skill NEVER: hands you a generator to trust unread — the guards are yours to write and test; instructs an agent to hide that it is an AI — if asked, it answers honestly; teaches evasion of any anti-abuse control — when a platform defense triggers, the run stops and a human takes over; blesses processing personal data without a named legal basis and a retention job that actually runs; patches a live install by hand; invents a fact the sources do not carry.

---

Alexandre Bloch — Bloch Agents · alex.bloch55@gmail.com · ClawHub @AlexBloch-IA