Skip to content

callstackincubator/apex-software-factory / .agents/skills/appduct

appduct

Verified

Call the tools the running Apex Factory app registers with appduct (read app state, jump to a route, run an OTA check now, emulate the update banner, a feature's own seed tools) through .agents/scripts/device-lane.sh, and write or review those tools in apps/mobile. Use when a check needs app state or a deep screen without tapping through the UI, when a spec's Agent hooks names an appduct tool, or when someone mentions appduct.

FileKindSize
SKILL.mdskill md7.0 KB
SOURCE.mdmarkdown1.3 KB
references/cli.mdmarkdown15.1 KB
references/setup.mdmarkdown7.6 KB
references/writing-tools.mdmarkdown8.8 KB

references/writing-tools.md

View on GitHub
<!-- Vendored verbatim from callstackincubator/appduct v0.14.0, skills/appduct/references/writing-tools.md (see ../SOURCE.md). In this repo: appduct is already a pinned workspace devDependency (never npm i, npx or a global install); run it through .agents/scripts/device-lane.sh appduct ..., or as pnpm exec appduct from apps/mobile in a person's session. -->

# Writing Appduct tools

Read this when the task is to register tools in an app, or to review the tools it already has.
The tools you write are what a calling agent sees in `appduct tools ls`; write them for that reader.

## Register a tool

React Native (`@appduct/react-native`), with zod 4:

```ts
import { useAppductTool } from "@appduct/react-native";
import { z } from "zod";

useAppductTool({
  name: "seed_cart",
  description: "Fill the current user's cart with test items. Requires a signed-in user.",
  group: "cart",
  inputSchema: z.object({
    items: z.number().int().min(1).max(50).describe("How many distinct SKUs to add"),
    clear: z.boolean().default(true).describe("Empty the cart first"),
  }),
  outputSchema: z.object({ cartId: z.string(), itemCount: z.number() }),
  timeoutMs: 30_000,
  handler: async ({ items, clear }) => cart.seed({ items, clear }),
});
```

`useAppductTool` registers once per mount and re-registers only when the descriptor changes;
the handler always sees the latest render's state, so no refs or `deps` are needed. Outside
React, `registerTool({...})` takes the same object and returns `{ remove() }`. Give each tool
one owner. `createToolGroup("cart")` returns a `registerTool` bound to a group.

Swift (`AppductCore`) and Kotlin (`com.callstack.appduct:core`) take the same fields with raw
JSON Schema:

```swift
try Appduct.shared.register(
  name: "get_cart", description: "Return the current cart. Read-only.",
  outputSchema: ["type": "object", "properties": ["itemCount": ["type": "integer"]]],
  annotations: ToolAnnotations(readOnlyHint: true), group: "cart"
) { _ in ["itemCount": await store.cart.count] }
```

```kotlin
Appduct.register(
  name = "reset_app", description = "Clear all local data and sign out.",
  outputSchema = JSONObject("""{"type":"object","properties":{"cleared":{"type":"boolean"}}}"""),
  annotations = ToolAnnotations(destructiveHint = true, idempotentHint = true),
) { _ -> JSONObject().put("cleared", store.reset()) }
```

## Schema rules

| `inputSchema` / `outputSchema` form                                                              | Validated in app | What agents see             |
| ------------------------------------------------------------------------------------------------ | ---------------- | --------------------------- |
| Standard Schema with a JSON Schema exporter: **zod 4**, arktype                                  | yes              | the exported JSON Schema    |
| `{ schema, jsonSchema }` pair: zod 3 + `zod-to-json-schema`, valibot + `@valibot/to-json-schema` | yes              | the `jsonSchema` you supply |
| Raw JSON Schema object (optionally `jsonSchema<T>()` for typing)                                 | **no**           | the object verbatim         |

- A bare zod 3 or plain valibot schema **throws in dev**: it would publish a shapeless tool.
- The input schema must accept a JSON object; a root string, number or array can never be
  satisfied. Prefer a single `z.object(...)`: a root union shows as `(...)` in the listing and
  forces the agent to fetch the full schema first.
- Names: `[a-zA-Z0-9_-]`, at most 64. Groups: `cart` or one subgroup `checkout/payment`, same
  characters; anything deeper throws.
- `timeoutMs` (1,000–600,000; default 10,000) is the only way to give a call more time. Callers
  can shorten it, never extend it.

## Declare the events the app posts

Agents list events before they wait on one, so declare every event the app posts. In React Native:

```ts
registerEvent({
  name: "checkout_completed",
  description: "An order was paid.",
  payloadSchema: z.object({ orderId: z.string() }),
});
```

In Swift, `payloadSchema` is a JSON Schema dictionary:

```swift
try Appduct.shared.registerEvent(
  name: "checkout_completed",
  description: "An order was paid.",
  payloadSchema: ["type": "object", "properties": ["orderId": ["type": "string"]]]
)
```

In Kotlin, it is a `JSONObject`:

```kotlin
Appduct.registerEvent(
  name = "checkout_completed",
  description = "An order was paid.",
  payloadSchema = JSONObject("""{"type":"object","properties":{"orderId":{"type":"string"}}}"""),
)
```

Declare at app start, not inside a screen that may never open, or `events ls` stays empty until it does.

- In React Native, `payloadSchema` takes the same forms as `inputSchema`; a raw JSON Schema is
  listed but never checked. In Swift and Kotlin it is a plain JSON Schema object, listed and never
  checked. `name` can be any string, dotted names included.
- Declaring is advisory: an undeclared `postEvent` still arrives, and production posts as-is. Only
  the React Native SDK warns in dev, about an undeclared name and about a payload that fails a
  declared Standard Schema. Swift and Kotlin send without any warning.
- Verify with `appduct events ls`; an empty list means nothing is declared.

## Design tools for the agent that will call them

An agent sees `name(params) -> result` plus the first line of the description, and decides from
that alone. Each rule below fixes a specific way that decision goes wrong.

1. **Name by intent, not implementation.** `go_to_checkout`, `set_feature_flag`, `seed_cart`.
   Not `dispatch_action`, `run_effect`, `do_checkout(json)`.
2. **Set `annotations`.** `readOnlyHint: true` on every observer; `destructiveHint: true` on
   anything that deletes, logs out, resets or pays. The daemon's policy and the MCP client's
   permission prompt key on `destructiveHint`; an unmarked destructive tool is silently allowed.
3. **Pair every mutation with an observer, and return the new state from the mutation.**
   `seed_cart -> { cartId, itemCount }` plus `get_cart` lets the agent verify in one call and
   re-check later.
4. **Declare an `outputSchema`, object-rooted.** It is what puts `-> { ... }` in the listing;
   without it the agent has to call the tool to learn what comes back. Wrap a scalar:
   `{ count: number }`, not `number`.
5. **First line of the description: one sentence, what it does.** Then preconditions and side
   effects: "Requires a signed-in user. Navigates to the Cart tab." Name the screen or feature so
   `--filter` finds it.
6. **Describe every parameter** (`.describe()` in zod, `description` in JSON Schema) with units
   and allowed values. Prefer enums over free strings: `tab: "home" | "cart" | "profile"`.
7. **Make setup tools idempotent and say so.** `login(userId)` is a no-op when already signed in
   as that user; mark it `idempotentHint: true`. The agent can then retry safely.
8. **Prefer a few coarse tools over many fine ones.** `complete_onboarding()` beats
   `dismiss_step_1` … `dismiss_step_7`. A long tool list costs the agent more than a wide tool.
9. **Declare `timeoutMs` on anything that touches the network.** The default is 10 s.
10. **Never register a tool that needs a person to finish.** A tool that opens a modal and
    resolves when someone taps will time out. Return once the state change is done; if something
    happens later, `postEvent("checkout_completed", {...})` and let the caller wait for it.
11. **Group once the app has more than a screenful of tools**, by feature (`cart`, `checkout`),
    so an agent lists one area instead of everything.

Before and after:

```ts
// Before: the listing shows `checkout(payload: ...)` and the word "Checkout"; nothing says what happens.
registerTool({
  name: "checkout",
  description: "Checkout",
  inputSchema: z.object({ payload: z.any() }),
  handler: async ({ payload }) => runCheckout(payload),
});

// After: `place_order(paymentMethod: "card" | "apple_pay" = "card") -> { orderId: string, total: number }  [destructive]`
registerTool({
  name: "place_order",
  description:
    "Place an order for the current cart and navigate to the confirmation screen. Requires a signed-in user with a non-empty cart. Charges the test payment method.",
  group: "checkout",
  inputSchema: z.object({
    paymentMethod: z
      .enum(["card", "apple_pay"])
      .default("card")
      .describe("Saved test payment method to charge"),
  }),
  outputSchema: z.object({
    orderId: z.string(),
    total: z.number().describe("Order total in cents"),
  }),
  annotations: { destructiveHint: true },
  timeoutMs: 30_000,
  handler: async ({ paymentMethod }) => checkout.placeOrder(paymentMethod),
});
```

**Read it back.** After registering, connect a device and run `appduct tools ls` (or
`appduct_list_tools`). Fix any `...` in a signature, any tool without `-> { ... }`, and any
description whose first line does not say what the tool needs. That listing is exactly what the
calling agent gets.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall