yakoshiq / skills

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. Each one is exercised on several models, and the skill file stays limited to guidance that transfers across tasks.

Included

concurrency-invariants
Names the guarantees behind atomicity, ordering, retries, ownership, and partial success.
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.
npx skills add yakoshiq/skills
GitHub

Works with Pi, Claude Code, Cursor, Codex, and other agents that support skills.

Before / after

concurrency-invariants

full before / after

Names the guarantee before choosing a mutex, retry, transaction, lease, or idempotency key — then enforces it across every owner and commit boundary.

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,
  );
  if (claimed.kind !== "acquired") return;

  const charge = await deps.payments.charge({
    orderId,
    idempotencyKey: `charge:${orderId}`,
  });

  const result = await deps.orders
    .commitChargedAndEnqueue({
      orderId,
      fence: claimed.claim.fence,
      chargeId: charge.id,
      event: {
        id: `order-charged:${orderId}`,
        type: "order_charged",
        status: "pending",
      },
    });

  if (result === "stale_owner") {
    return { kind: "partial" };
  }
  return { kind: "committed" };
}

The local set coordinates only one process, every retry can charge again, and a crash can split state from publication. The correction uses one provider identity, a shared claim whose fence rejects stale owners, and one local commit that stores charged state with a durable pending event.

essential-comments

full before / after

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;

  // Reserve the stock.
  inventory[req.productId] = stock - req.qty;
  // Subtract quantity.

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;

  // Reserve before charge so concurrent
  // checkouts cannot both pass the stock check.
  inventory[req.productId] = stock - req.qty;

Same function, same behavior. The narration only repeated what the lines already say. The surviving comments carry what a reader cannot reconstruct: who owns force, and why reserve must come before charge.

jane-street-style

full before / after

Names the domain operation and gives every failure its own type — while the legacy entry point keeps its observable behavior.

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,
): number {
  if (amount <= 0) throw new InvalidDebit(amount);
  if (!(userId in wallets)) {
    throw new WalletNotFound(userId);
  }

  const balance = wallets[userId] - amount;
  wallets[userId] = balance;

  try {
    notifyProvider(userId, -amount);
  } catch (cause) {
    // debit already committed — carry both facts
    throw new NotifyFailedAfterDebit(
      userId, balance, cause,
    );
  }

  return balance;
}

Callers can now tell invalid input from a missing wallet, and NotifyFailedAfterDebit states that the debit committed while notification did not. The legacy process entry point still returns the same values, so nobody migrates.

surgical-changes

full before / after

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) {

Both diffs fix the missing retry attempt. The first also replaces the public API and forces every caller and test to migrate. The second touches only the causal line, so the review takes seconds.

tests-that-matter

full before / after

Proves observable state and the real external boundary. A call-count test stays green while the wrong amount moves.

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 first test stays green when the wrong amount moves, one balance is lost, or the result lies. The second fails in all three cases: it asserts observable state, and mocks only the provider the repo does not own.