@andreprado/agentkit 0.1.0-alpha.5 → 0.1.0-alpha.7

package/src/templates/skills/agentkit-prompts/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: agentkit-prompts
+description: Use when writing or revising AgentKit prompt files, especially prompts/instructions.md, including agent role, behavior, boundaries, escalation rules, tool-use policy, Knowledge policy, and user-facing tone.
+---
+
+# AgentKit Prompts
+
+Use this when editing `prompts/instructions.md`.
+
+## Prompt Checklist
+
+Include only behavior the runtime should apply on every conversation:
+
+- agent role and audience;
+- domain-specific goals;
+- what information to collect;
+- when to use tools;
+- when to search Knowledge;
+- what the agent must not claim;
+- escalation and safety boundaries;
+- response style.
+
+Keep operational secrets, provider details, and implementation notes out of prompts.
+
+## Tool And Knowledge Policy
+
+- Use tools for actions, live data, authorization-sensitive records, payments, orders, booking, and writes.
+- Use Knowledge for committed reference facts such as FAQs, prices, services, policies, procedures, and CSV tables.
+- Do not expose raw tool output, retrieval JSON, chunk IDs, scores, secrets, logs, or internal labels.
+
+## Templates
+
+- `templates/knowledge-grounded-faq.instructions.md`
+- `../agentkit-build-agent/templates/support-agent.instructions.md`
+- `../agentkit-build-agent/templates/appointment-intake.instructions.md`
+
+## Verification
+
+```sh
+npm run chat -- --message "hello"
+npm run eval
+```
+
+If the provider is still `test/fake`, say prompt behavior was not tested with a real model.
+

package/src/templates/skills/agentkit-prompts/templates/knowledge-grounded-faq.instructions.md

@@ -0,0 +1,11 @@
+You are a knowledge-grounded FAQ agent.
+
+Use the configured Knowledge search before answering business-specific factual questions about services, prices, policies, procedures, or support rules.
+
+Rules:
+- Answer from the retrieved source material when available.
+- If the answer is not in the available sources, say that you do not have enough information.
+- Do not expose raw retrieval JSON, scores, chunk IDs, or internal source metadata.
+- Do not use Knowledge for secrets, credentials, live customer records, payments, or authorization-sensitive data.
+- Use tools for live or customer-specific lookups.
+

package/src/templates/skills/agentkit-provider/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: agentkit-provider
+description: Use when switching an AgentKit capsule from the deterministic test/fake provider to a real Pi-backed provider such as OpenAI, Anthropic, or OpenRouter, or when verifying provider secrets and model behavior.
+---
+
+# AgentKit Provider
+
+Use this when `test/fake` is no longer enough.
+
+## Rule
+
+Do not choose a real provider automatically. Ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider.
+
+## Workflow
+
+1. Edit `agentkit.config.ts`.
+2. Add required secret names to `secrets`.
+3. Add names to `.env.schema`.
+4. Set local secret values in ignored `.env` through AgentKit commands.
+5. Run inspect, chat, and UI checks.
+
+## Config Examples
+
+OpenAI:
+
+```ts
+provider: { name: "openai", model: "gpt-4o-mini" },
+secrets: ["OPENAI_API_KEY"],
+```
+
+Anthropic:
+
+```ts
+provider: { name: "anthropic", model: "claude-3-5-haiku-latest" },
+secrets: ["ANTHROPIC_API_KEY"],
+```
+
+OpenRouter:
+
+```ts
+provider: { name: "openrouter", model: "gpt-4o-mini" },
+secrets: ["OPENROUTER_API_KEY"],
+```
+
+## Verification
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+npm run dev
+```
+
+Open the printed `Chat:` URL and report it to the owner.
+
+Do not import provider SDKs in the capsule. AgentKit resolves providers internally through Pi-backed adapters.
+

package/src/templates/skills/agentkit-security/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: agentkit-security
+description: Use before or during AgentKit work involving secrets, external APIs, tools, evals from real data, public access, hosted deploys, or messaging channels.
+---
+
+# AgentKit Security
+
+Use this as a guardrail skill.
+
+## Never Commit
+
+```txt
+.env
+.agentkit/
+node_modules/
+```
+
+Secret values must not appear in:
+
+```txt
+agentkit.config.ts
+.env.schema
+AGENTS.md
+AGENTKIT.md
+CLAUDE.md
+README.md
+prompts/
+evals/
+docs/
+skills/
+```
+
+## Rules
+
+- `.env.schema` stores secret names only.
+- Ignored `.env` stores local development values only.
+- Hosted production uses managed secrets.
+- Tools receive only secrets listed in that tool's `secrets` field.
+- Prefer `ctx.secrets` over direct `process.env` reads in tools.
+- Add `permissions` for external capabilities.
+- Add timeouts to network tools.
+- Remove client PII before writing evals.
+- Treat public deploy URLs as transport, not access control.
+
+## Checks
+
+```sh
+git status --short
+npm run agentkit -- env list
+npm run agentkit -- inspect
+git diff --check
+```
+
+Expected: secret names may appear, secret values do not.
+

package/src/templates/skills/agentkit-tools/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: agentkit-tools
+description: Use when adding, changing, registering, or testing AgentKit TypeScript tools with defineTool, including external APIs, local actions, input/output schemas, tool secrets, permissions, timeouts, and eval-safe side effects.
+---
+
+# AgentKit Tools
+
+Use this when the agent needs code, an API, live data, a write, or an external action.
+
+## Workflow
+
+1. Create or edit `tools/<name>.ts`.
+2. Export a `defineTool` tool with `name`, `description`, `inputSchema`, and usually `outputSchema`.
+3. Add `secrets`, `permissions`, and `timeoutMs` when needed.
+4. Register the tool in `agentkit.config.ts`.
+5. Keep secret names in `.env.schema`; values stay in ignored `.env` or hosted managed secrets.
+6. Add eval guards for destructive or external side effects.
+
+## Examples
+
+- `examples/lookup-order.tool.md`: simple lookup
+- `examples/database-write.tool.md`: write through `ctx.db`
+- `examples/eval-safe-external-action.tool.md`: safe eval branch for external side effects
+
+Use `skills/agentkit-database/SKILL.md` for database-backed tools.
+Use `skills/agentkit-security/SKILL.md` before adding external APIs or secrets.
+
+## Verification
+
+```sh
+npm run typecheck
+npm run agentkit -- tool <tool_name> --input '<json>'
+npm run agentkit -- inspect
+```
+
+Expected: input/output validation passes, tool calls persist, and no secret values appear in output or stored data.

package/src/templates/skills/agentkit-tools/examples/database-write.tool.md

@@ -0,0 +1,35 @@
+# Database Write Tool
+
+Copy the code into a real tool file and make sure `schema.sql` contains the target table.
+
+```ts
+import { defineTool } from "@andreprado/agentkit";
+
+export const saveNote = defineTool({
+  name: "save_note",
+  description: "Saves a note in the AgentKit-managed database.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      content: { type: "string" },
+    },
+    required: ["content"],
+    additionalProperties: false,
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      id: { type: "string" },
+      content: { type: "string" },
+    },
+    required: ["id", "content"],
+    additionalProperties: false,
+  },
+  async execute(input: { content: string }, ctx) {
+    const id = crypto.randomUUID();
+    await ctx.db.execute("INSERT INTO notes (id, content) VALUES (?, ?)", [id, input.content]);
+    return { id, content: input.content };
+  },
+});
+```
+

package/src/templates/skills/agentkit-tools/examples/eval-safe-external-action.tool.md

@@ -0,0 +1,37 @@
+# Eval-Safe External Action Tool
+
+Use this pattern for tools that send email, call customer systems, charge money, delete data, or perform other external side effects.
+
+```ts
+import { defineTool } from "@andreprado/agentkit";
+
+export const sendFollowupEmail = defineTool({
+  name: "send_followup_email",
+  description: "Sends a follow-up email after explicit confirmation.",
+  secrets: ["EMAIL_API_KEY"],
+  permissions: ["email:send"],
+  inputSchema: {
+    type: "object",
+    properties: {
+      email: { type: "string" },
+      confirmed: { type: "boolean" },
+    },
+    required: ["email", "confirmed"],
+    additionalProperties: false,
+  },
+  async execute(input: { email: string; confirmed: boolean }, ctx) {
+    if (!input.confirmed) {
+      return { sent: false, reason: "confirmation_required" };
+    }
+
+    if (ctx.runtime.environment === "eval") {
+      return { sent: false, evalFixture: true, email: input.email };
+    }
+
+    const apiKey = ctx.secrets.EMAIL_API_KEY;
+    // Call the real email provider with apiKey here.
+    return { sent: true, evalFixture: false, email: input.email };
+  },
+});
+```
+

package/src/templates/skills/agentkit-tools/examples/lookup-order.tool.md

@@ -0,0 +1,46 @@
+# Lookup Order Tool
+
+Copy the code into `tools/lookup-order.ts` and register `lookupOrder` in `agentkit.config.ts`.
+
+```ts
+import { defineTool } from "@andreprado/agentkit";
+
+const orders: Record<string, { status: string; eta: string }> = {
+  A100: { status: "preparing", eta: "today" },
+  B200: { status: "shipped", eta: "tomorrow" },
+};
+
+export const lookupOrder = defineTool({
+  name: "lookup_order",
+  description: "Looks up a demo support order by order id.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      orderId: { type: "string" },
+    },
+    required: ["orderId"],
+    additionalProperties: false,
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      orderId: { type: "string" },
+      found: { type: "boolean" },
+      status: { type: "string" },
+      eta: { type: "string" },
+    },
+    required: ["orderId", "found", "status", "eta"],
+    additionalProperties: false,
+  },
+  execute(input: { orderId: string }) {
+    const order = orders[input.orderId];
+    return {
+      orderId: input.orderId,
+      found: Boolean(order),
+      status: order?.status ?? "unknown",
+      eta: order?.eta ?? "unknown",
+    };
+  },
+});
+```
+

package/src/templates/skills/agentkit-troubleshooting/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: agentkit-troubleshooting
+description: Use when an AgentKit command, local chat, tool, eval, Knowledge sync, channel, or deploy fails and the coding agent needs to diagnose from CLI output and route to the right narrow skill or docs guide.
+---
+
+# AgentKit Troubleshooting
+
+Use this when something fails.
+
+## Workflow
+
+1. Read the exact error code and message.
+2. Run the narrow inspect command before guessing.
+3. Route to a task skill when the failure points to config, tools, database, provider, evals, deploy, Knowledge, or channels.
+4. Load `llms-full.txt` only when the narrow skill and guide do not explain the behavior.
+
+## First Commands
+
+```sh
+npm run agentkit -- inspect
+npm run typecheck
+npm run agentkit -- env list
+git status --short
+```
+
+For chat issues:
+
+```sh
+npm run chat -- --message "hello"
+```
+
+For tool issues:
+
+```sh
+npm run agentkit -- tool <tool_name> --input '<json>'
+```
+
+For deploy issues:
+
+```sh
+npm run agentkit -- deploy doctor
+```
+
+## Common Causes
+
+- missing dependencies: run `npm install`;
+- missing provider key: set ignored `.env` and confirm with `inspect`;
+- provider not chosen: stay on `test/fake` or ask the owner;
+- schema missing: run `db migrate` and check `schema.sql`;
+- tool validation failed: check `inputSchema` and `outputSchema`;
+- channel secret missing: set hosted managed secret, not source files.
+

package/src/templates/support.ts

@@ -190,11 +190,13 @@ When the owner opens this folder in Codex, Claude Code, or another coding agent
 
 Start building immediately:
 
-- Read \`AGENTKIT.md\` and the full docs path from \`npm run agentkit -- docs full\`.
+- Start with \`skills/agentkit-capsule/SKILL.md\`, then use \`npm run agentkit -- docs llms\` as the docs router.
+- Create or update \`AGENT_SPEC.md\` from the owner's request with \`npm run agentkit -- spec init --brief "<owner request>"\`; the owner should not fill this file by hand before work starts.
 - Infer the first useful version from the owner's request.
 - Edit \`prompts/instructions.md\` for support behavior.
 - Edit \`agentkit.config.ts\` for provider, tools, secrets, access, and storage.
 - Add or replace TypeScript tools under \`tools/\` when the requested support agent needs actions or external data.
+- Add \`sync.ts\`, \`seed.sql\`, and ordered \`migrations/*.sql\` when the support agent depends on external catalogs or production-shaped data changes.
 - Do not wait for a wizard or recipe. AgentKit provides the scaffold and contract; you decide the implementation from the owner's brief.
 - Ask follow-up questions only when missing information blocks a safe local implementation.
 - State assumptions in the final response.
@@ -205,11 +207,15 @@ Start building immediately:
 - \`npm run chat -- --message "hello"\`: send one local chat message.
 - \`npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'\`: test the example tool directly.
 - \`npm run eval\`: run agent evals.
+- \`npm run agentkit -- spec check\`: verify the local agent implementation contract exists.
+- \`npm run agentkit -- eval from-conversation <conversation-id>\`: turn a real conversation into a regression eval.
+- \`npm run agentkit -- conversations trace <conversation-id>\`: inspect messages, runs, tool calls, inputs, outputs, rendered output, and final responses.
 - \`npm run dev\`: run the local Agent Capsule runtime.
 - \`npm run agentkit -- inspect\`: print machine-readable capsule state.
 - \`printf %s "$VALUE" | npm run agentkit -- env set <NAME> --stdin\`: write a local secret value to ignored \`.env\` without putting it in shell history.
 - \`npm run agentkit -- env list\`: list local secret names without printing values.
-- \`npm run agentkit -- docs full\`: print the full AgentKit contract path.
+- \`npm run agentkit -- docs llms\`: print the lightweight AgentKit docs router.
+- \`npm run agentkit -- docs full\`: print the full AgentKit contract path only when a skill asks for it.
 
 ## Testing With A UI
 
@@ -258,8 +264,10 @@ Example owner request:
 Turn the request into a working local capsule:
 
 - Update \`prompts/instructions.md\` with domain-specific behavior, boundaries, intake questions, and escalation rules.
+- Create or update \`AGENT_SPEC.md\` with \`npm run agentkit -- spec init --brief "<owner request>"\`. The owner gives the general idea; the coding agent turns it into the structured contract.
 - Update \`agentkit.config.ts\` when tools, secrets, provider, or access rules change.
 - Add, replace, or remove TypeScript tools under \`tools/\` for real actions or external data.
+- Use \`npm run agentkit -- sync init\` when the agent needs catalog sync, fixture seed data, or ordered migrations.
 - Keep the first version runnable with \`test/fake\` unless the owner explicitly asks for a real provider.
 - Do not use a wizard or recipe. Build the capsule directly from the scaffold, the AgentKit contract, and the owner's brief.
 - Make practical assumptions and list them in your final response.
@@ -313,12 +321,14 @@ If you add a tool, also run a fake-provider tool smoke test:
 npm run agentkit -- tool tool_name --input '{}'
 \`\`\`
 
-For the full framework contract, read the path printed by:
+For the lightweight docs router, read the path printed by:
 
 \`\`\`sh
-npm run agentkit -- docs full
+npm run agentkit -- docs llms
 \`\`\`
 
+Read the full framework contract with \`npm run agentkit -- docs full\` only when a skill asks for it.
+
 ## Database Tools
 
 Tools that need agent-owned tables should use canonical \`ctx.db\` from the tool context. \`ctx.database\` and \`ctx.storage.sql\` are aliases. Do not import local database drivers or Node-only APIs in a tool.
@@ -360,6 +370,7 @@ Use AgentKit conventions when editing this support capsule.
 - Ask the owner which real provider to use before switching from \`test/fake\`; do not choose OpenRouter, OpenAI, or Anthropic automatically.
 - Keep required local secret names in \`.env.schema\` and values in ignored \`.env\`. AgentKit local commands load \`.env\` directly.
 - Treat the owner's natural-language request as the brief and start implementing inside this capsule.
+- Start with \`skills/agentkit-capsule/SKILL.md\` when the task is not obvious.
 `,
       },
       {