Skills for intentional code
Agent skills that push toward code humans can review, with explicit concurrency guarantees. Default agent output looks finished and still hides the hard parts: vague names, one false for every failure, a mutex, retry, or transaction with no named invariant, narration comments, and green tests without confidence.
These skills are short on purpose. The original five — concurrency-invariants, essential-comments, jane-street-style, surgical-changes, and tests-that-matter — were exercised across seven models. New additions and later revisions do not automatically inherit that evidence. Skill files stay limited to guidance that transfers across tasks.
Included · 7 skills
- concurrency-invariants
- Names the guarantees behind atomicity, ordering, retries, ownership, and partial success.
- correct
- Prevents a demonstrated recurring mistake with structural enforcement. Explicit use only.
- essential-comments
- Keeps only comments that explain why, invariants, or external constraints.
- jane-street-style
- Makes domain meaning, effects, and failure cases explicit.
- surgical-changes
- Solves the root cause with the smallest coherent change.
- tests-that-matter
- Proves observable behavior, boundaries, and real regressions.
- verification-planning
- Plans acceptance across runtime boundaries and closes evidence gaps — not every small fix.
npx skills add yakoshiq/skillsWorks with Pi, Claude Code, Cursor, Codex, and other agents that support skills. Choose Intentional Code for the full set, or add --skill essential-commentsfor one skill. Prefer an explicit invoke such as /skill:essential-comments; automatic triggering depends on the model.
Before / after
Designs, fixes, or reviews concurrent and asynchronous code by naming the guarantee before choosing coordination. Separately owned state can remove unnecessary shared writes; a canonical atomic invariant still needs coordination.
before
const activeOrders = new Set<string>();
export async function processOrder(
orderId: string, deps: Deps,
) {
if (activeOrders.has(orderId)) return;
activeOrders.add(orderId);
try {
const charge = await retry(3, (attempt) =>
deps.payments.charge({
orderId,
idempotencyKey:
`${orderId}:${Date.now()}:${attempt}`,
}),
);
await deps.orders.markCharged(
orderId, charge.id,
);
await deps.events.publish({
type: "order_charged", orderId,
});
} finally {
activeOrders.delete(orderId);
}
}after
export async function processOrder(
orderId: string, deps: Deps,
) {
const claimed = await deps.orders.claim(
orderId, deps.workerId, 30_000,
);
if (claimed.kind !== "acquired") {
return { kind: "skipped",
reason: claimed.kind };
}
if (deps.signal.aborted) {
await deps.orders.release(claimed.claim);
throw deps.signal.reason;
}
const key = `charge:${orderId}`;
let outcome = await deps.payments.charge(
orderId, key, deps.signal,
);
if (outcome.kind === "unknown") {
const existing = await deps.payments
.findByIdempotencyKey(key, deps.signal);
if (!existing) {
return {
kind: "partial", charge: "unknown",
order: "unknown",
recovery: "retry_delivery",
};
}
outcome = {
kind: "charged",
chargeId: existing.chargeId,
};
}
if (outcome.kind === "declined") {
await deps.orders.release(claimed.claim);
return { kind: "failed",
reason: "payment_declined" };
}
const result = await deps.orders
.commitChargedAndEnqueue(
claimed.claim, outcome.chargeId, {
id: `order-charged:${orderId}`,
type: "order_charged", orderId,
},
);
if (result === "stale_owner") {
return {
kind: "partial", charge: "confirmed",
order: "unknown",
recovery: "retry_delivery",
};
}
return { kind: "committed",
chargeId: outcome.chargeId,
event: "pending" };
}The corrected excerpt assumes a durable queue that redelivers partial results, a fenced store, provider deduplication and lookup, and an atomic state/outbox commit. Timeout remains unknown, not a confirmed non-charge. The full example names these adapter guarantees, cancellation handling, and recovery paths.
On explicit request, prevents a demonstrated recurring class of mistakes with the narrowest effective structural constraint, type, mechanical check, or regression. Not an automatic redesign after feedback.
before
const menuFormats = [
"pdf", "csv", "json",
];
const exportFormats = ["pdf", "csv"];after
const formats = {
pdf: { label: "PDF",
contentType: "application/pdf" },
csv: { label: "CSV",
contentType: "text/csv" },
json: { label: "JSON",
contentType: "application/json" },
} as const;
type Format = keyof typeof formats;
export function downloadMenu() {
return Object.entries(formats).map(
([format, spec]) => ({
label: spec.label,
href: `/exports/${format}`,
}),
);
}
export function exportContentType(
format: string,
): string {
if (!Object.hasOwn(formats, format)) {
throw new Error(
`Unsupported export format: ${format}`,
);
}
return formats[format as Format].contentType;
}CSV and JSON were advertised but omitted from a second catalog. One authoritative definition removes that opportunity. This excerpt illustrates the catalog boundary, not a complete exporter: existing implementations and errors remain unchanged. Replay the omissions, a nearby implemented format, and unknown-format rejection at the real consumer boundary; these are illustrative checks, not executed results.
Keeps the facts code cannot recover — why, invariants, external constraints — and deletes narration that only restates it.
before
export function handleCheckout(
req: CheckoutReq,
opts: { dryRun?: boolean; force?: boolean } = {},
): boolean {
// Validate the request.
if (!req.productId || req.qty <= 0) return false;
// Get the stock.
const stock = inventory[req.productId] ?? 0;
// Check whether oversell is allowed.
if (stock < req.qty && !opts.force) return false;
if (opts.dryRun) return true;
// Reserve the stock.
inventory[req.productId] = stock - req.qty;
// Subtract quantity.
try {
charge(req.userId, req.unitPrice * req.qty);
} catch {
inventory[req.productId] = stock;
return false;
}
scheduleConfirm(req.orderId, { afterMs: 2000 });
return true;
}after
export function handleCheckout(
req: CheckoutReq,
opts: { dryRun?: boolean; force?: boolean } = {},
): boolean {
if (!req.productId || req.qty <= 0) return false;
const stock = inventory[req.productId] ?? 0;
// force is an operations override
// for VIP oversell.
if (stock < req.qty && !opts.force) return false;
if (opts.dryRun) return true;
// Reserve before charge so concurrent
// checkouts cannot both pass the stock check.
// Charge failure restores the brief over-hold.
inventory[req.productId] = stock - req.qty;
try {
charge(req.userId, req.unitPrice * req.qty);
} catch {
inventory[req.productId] = stock;
return false;
}
// Stripe webhook can race the read model;
// see #1842.
scheduleConfirm(req.orderId, { afterMs: 2000 });
return true;
}Same function, same behavior. Known task context supplies VIP-operations policy, the accepted brief over-hold, and the Stripe read-model race. Keep those facts and remove narration; do not invent missing context or rename code during a comments-only cleanup.
For explicit clarity-first design, refactoring, or review — not an ordinary shape-preserving bug fix. Names the domain operation and makes effects and failures explicit.
before
export function process(
d: any,
flag = true,
mode = 0,
): any {
try {
if (mode !== 1) return false;
if (
typeof d.uid !== "string" ||
typeof d.amt !== "number" ||
d.amt <= 0 ||
!(d.uid in wallets)
) {
return false;
}
const bal = wallets[d.uid] - d.amt;
wallets[d.uid] = bal;
if (flag) notifyProvider(d.uid, -d.amt);
return bal;
} catch {
return false;
}
}after
export function debitWallet(
userId: string,
amount: number,
opts: { notify?: boolean } = {},
): number {
if (amount <= 0) throw new InvalidDebit(amount);
if (!(userId in wallets)) {
throw new WalletNotFound(userId);
}
const balance = wallets[userId] - amount;
wallets[userId] = balance;
if (opts.notify ?? true) {
try {
notifyProvider(userId, -amount);
} catch (cause) {
throw new NotifyFailedAfterDebit(
userId, balance, cause,
);
}
}
return balance;
}The new API distinguishes invalid input, a missing wallet, and notification failure after debit. In this compatibility example, the full source keeps process as an adapter preserving legacy results and effect order. An approved clean cutover instead migrates callers and deletes the old entry point. Derive genuinely new APIs from a representative caller, not a generic framework.
Fixes the root cause and leaves everything else alone — no renames, no result-type redesign, no migration the bug never asked for.
before
- export async function deliver(
- message: string,
- maxAttempts: number,
- send: Sender,
- ): Promise<boolean> {
+ export async function deliverWithRetry(
+ message: string,
+ policy: RetryPolicy,
+ sender: Sender,
+ ): Promise<DeliveryResult> {after
- while (attempt < maxAttempts - 1) {
+ while (attempt < maxAttempts) {The broad approach replaces the API and forces an unrelated migration. The focused change repairs the loop, with a public-boundary regression for all attempts and final-error rethrow in the full example. Reuse still-valid evidence unless a required gate demands a fresh run; after repeated failures at the same gate, test their shared premise rather than patching another symptom.
Writes or reviews tests for observable outcomes, distinct failures, invariants, and boundaries — not call counts or coverage without confidence.
before
it("calls its dependencies", async () => {
const wallets = { get: vi.fn(), save: vi.fn() };
const notify = vi.fn();
wallets.get.mockResolvedValue({
id: "w1", balance: 100,
});
await processTransfer(
{ from: "w1", to: "w2", amount: 40 },
{ wallets, notify },
);
expect(wallets.get).toHaveBeenCalledWith("w1");
expect(wallets.save).toHaveBeenCalled();
expect(notify).toHaveBeenCalled();
});after
it("moves balances and notifies", async () => {
const wallets = memoryWallets({
w1: 100, w2: 10,
});
const notify = vi.fn()
.mockResolvedValue(undefined);
const result = await processTransfer(
{ from: "w1", to: "w2", amount: 40 },
{ wallets, notify },
);
expect(result).toEqual({ ok: true });
expect(wallets.snapshot()).toEqual({
w1: 60, w2: 50,
});
expect(notify).toHaveBeenCalledWith({
from: "w1", to: "w2", amount: 40,
});
});The stronger test asserts the result, both balances, and the provider payload. Its in-memory wallet proves local behavior, not real-store persistence; the mocked provider does not prove live-provider behavior. Reread persisted or completed state at the required boundary, cover every agreed journey, and keep distinct failures and partial success explicit.
Plans and carries out acceptance across runtime boundaries, reuses trustworthy evidence, and recovers verification stuck in repeated runs or unclear results. Not routine test authoring, every small fix, or root-cause debugging.
before
Task: grant and revoke a subscription;
both must survive reload.
Tests and required integrated check passed.
API ready; server still running.
Grant returned HTTP 200.
Only a Git fetch followed the checks.
Live-provider access unavailable.
Wait for the server to exit.
Restart it and repeat unchanged checks.
Skip persisted state and revoke.
Call the controlled provider live proof.after
Confirm checked state is still relevant.
Reuse results unless a fresh run is required.
Keep the ready service running.
Grant through the admin interface.
Reload or reread persisted subscription.
Verify the granted state.
Revoke and reread persisted state.
Verify the revoked state.
Report local acceptance separately.
Leave required live evidence unproved
when live access is unavailable.
Stop after the agreed proof is complete.Illustrative plan, not executed results. Reuse requires the same relevant code, local changes, and material environment; required fresh runs still apply. A controlled provider cannot establish live-provider behavior. For risky changes, trace persisted, wire, and runtime consumers beyond symbol references and prove the safety premise at a meaningful boundary — or state the gap.
Selected mechanisms adapted from Lauren Tan’s pstack. Sources and upstream MIT notice: Third-party notices.