callstackincubator/apex-software-factory / .agents/skills/appduct
appduct
VerifiedCall 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.0 KB |
| SOURCE.md | markdown | 1.3 KB |
| references/cli.md | markdown | 15.1 KB |
| references/setup.md | markdown | 7.6 KB |
| references/writing-tools.md | markdown | 8.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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |