create-theokit 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",

package/templates/default/agents/chat.ts

@@ -1,7 +1,10 @@
 import { agent } from '@theokit/agents'
+import { defineSkillReadTool } from '@theokit/sdk'
 import { z } from 'zod'
 
 import { BASE_INSTRUCTIONS } from './prompts/instructions.js'
+import { dailyBriefingSkill } from './skills/daily-briefing.js'
+import { currentTimeTool } from './tools/current-time.js'
 import { weatherTool } from './tools/weather.js'
 
 /**
@@ -21,4 +24,11 @@ export default agent()
   .model('openai/gpt-4o-mini')
   .system(BASE_INSTRUCTIONS)
   .tool(weatherTool)
+  .tool(currentTimeTool)
+  // `.skills([...])` registers the code-defined skill: the SDK lists its name + description in a
+  // `<skills>` block in every system prompt (cheap), so the model KNOWS the skill exists.
+  .skills([dailyBriefingSkill])
+  // `defineSkillReadTool` then gives the model a `skill_read` tool to load the full body on demand —
+  // so a long procedure only enters the prompt when the model actually needs it.
+  .tool(defineSkillReadTool([dailyBriefingSkill]))
   .build()

package/templates/default/agents/prompts/instructions.ts

@@ -5,6 +5,17 @@
  */
 export const BASE_INSTRUCTIONS = `You are a helpful assistant living inside a TheoKit app.
 
-- Answer clearly and concisely.
-- When the user asks about current weather, call the \`weather\` tool instead of guessing.
-- If you are unsure, say so rather than inventing an answer.`
+## Voice
+- Answer clearly and concisely. Prefer a direct answer over a preamble.
+- If you are unsure, say so rather than inventing an answer.
+
+## Tools — call them, don't guess
+- **Current weather** for a place → call the \`weather\` tool.
+- **Current date / time** (optionally for a timezone) → call the \`current_time\` tool.
+- Never state a time or the weather from memory; always call the tool. If a tool errors, tell the user
+  what failed and what you need (e.g. a valid city or IANA timezone).
+
+## Skills
+- The \`<skills>\` block above lists documented procedures (skills) by name + description. When a request
+  matches a skill's description, call the \`skill_read\` tool with that skill's name to load its full
+  steps, then follow them. Don't guess a procedure a skill already documents.`

package/templates/default/agents/skills/daily-briefing.ts

@@ -0,0 +1,31 @@
+import { createSkill } from '@theokit/sdk'
+
+/**
+ * A real, code-defined skill (`createSkill`) — a documented procedure the MODEL can pull in on demand.
+ *
+ * Unlike a loose Markdown note, this is wired into the agent: `agents/chat.ts` passes it to
+ * `defineSkillReadTool([...])`, which gives the model a `skill_read` tool. The model sees the skill's
+ * name + description in every turn (cheap) and calls `skill_read('daily-briefing')` to load the full
+ * `instructions` only when it actually needs them — so long procedures don't bloat every prompt.
+ *
+ * Lives in `agents/skills/` — a semantic folder the route scanner skips, so it never becomes an endpoint.
+ */
+export const dailyBriefingSkill = createSkill({
+  name: 'daily-briefing',
+  description:
+    "Produce a short 'good morning' briefing (today's date, the weather, and a one-line nudge).",
+  instructions: `# Daily briefing
+
+Trigger: the user asks for a "briefing", "morning update", or "what's my day looking like".
+
+Steps:
+1. Ask for (or reuse) the user's city and IANA timezone if you don't already have them.
+2. Call the \`current_time\` tool with their timezone → the local date and time.
+3. Call the \`weather\` tool with their city → the current conditions.
+4. Reply in exactly three lines:
+   - **Today** — weekday + date (from current_time).
+   - **Weather** — conditions + temperature (from weather).
+   - **Nudge** — one short, friendly suggestion based on the weather.
+
+Never invent the time or weather — always call the tools. Keep it to three lines unless asked for more.`,
+})

package/templates/default/agents/tools/current-time.ts

@@ -0,0 +1,35 @@
+import { tool } from 'theokit/server'
+import { z } from 'zod'
+
+/**
+ * A local, deterministic tool — the current date + time, optionally in an IANA timezone. No network,
+ * always works: the counterpart to `weather.ts` (which hits an HTTP API), so the scaffold shows both a
+ * remote-call tool and a pure local one. Imported into `chat.ts` and chained with `.tool(currentTimeTool)`.
+ */
+export const currentTimeTool = tool('current_time')
+  .describe('Get the current date and time, optionally for a specific IANA timezone.')
+  .input(
+    z.object({
+      timezone: z
+        .string()
+        .optional()
+        .describe('IANA timezone, e.g. "Europe/Lisbon" or "America/Sao_Paulo". Defaults to UTC.'),
+    }),
+  )
+  .execute(async ({ timezone }) => {
+    const tz = timezone ?? 'UTC'
+    try {
+      const formatted = new Intl.DateTimeFormat('en-US', {
+        timeZone: tz,
+        dateStyle: 'full',
+        timeStyle: 'long',
+      }).format(new Date())
+      return `Current time (${tz}): ${formatted}`
+    } catch {
+      // fail-fast with a clear, actionable message (Rule 8) rather than a cryptic RangeError.
+      throw new Error(
+        `Unknown timezone "${tz}". Use an IANA name like "Europe/Lisbon" or "America/Sao_Paulo".`,
+      )
+    }
+  })
+  .build()

package/templates/default/docs/ARCHITECTURE.md

@@ -13,9 +13,10 @@ folders it composes (prompts, tools, skills) live together under `agents/`, with
 │   ├── prompts/            #   system prompts / personas
 │   │   └── instructions.ts
 │   ├── tools/              #   tools the agent can call
-│   │   └── weather.ts      #     tool('weather')…build()
-│   └── skills/             #   Markdown procedures the agent (and you) can follow
-│       └── getting-started.md
+│   │   ├── weather.ts      #     remote — current weather via open-meteo (HTTP)
+│   │   └── current-time.ts #     local — date/time in an IANA timezone (no network)
+│   └── skills/             #   procedures the model loads on demand (createSkill)
+│       └── daily-briefing.ts    #   a real skill: time → weather → a one-line nudge
 ├── app/                    # Frontend (web surface). tui → tui/, desktop → frontend/
 ├── server/                 # Backend routes / actions (POST/GET handlers, jobs)
 ├── shared/                 # Code imported by more than one layer
@@ -44,12 +45,16 @@ export default agent()
   .model('openai/gpt-4o-mini')
   .system(BASE_INSTRUCTIONS)   // agents/prompts/instructions.ts
   .tool(weatherTool)           // agents/tools/weather.ts
+  .tool(currentTimeTool)       // agents/tools/current-time.ts
+  .tool(defineSkillReadTool([dailyBriefingSkill]))  // agents/skills/daily-briefing.ts
   .build()
 ```
 
 Grow the agent by editing its neighbours, not by inflating `chat.ts`: persona → `prompts/instructions.ts`,
-a new capability → `tools/<name>.ts` (then `.tool(<name>Tool)`), a documented procedure →
-`skills/<name>.md`. Add a **second agent** as another `agents/<name>.ts`.
+a new capability → `tools/<name>.ts` (then `.tool(<name>Tool)`), a documented procedure → a
+`createSkill(...)` in `skills/<name>.ts` (add it to the `defineSkillReadTool([...])` list). A **skill** is
+loaded by the model on demand via the `skill_read` tool, so long procedures don't bloat every prompt. Add a
+**second agent** as another `agents/<name>.ts`.
 
 ## Surfaces
 

package/templates/default/docs/CUSTOMIZATION.md

@@ -7,7 +7,7 @@ Common changes, and where they go. See [ARCHITECTURE](./ARCHITECTURE.md) for the
 | Change the model | `agents/chat.ts` (`.model(...)`) + the label in `shared/agent.ts` |
 | Change the persona / rules | `agents/prompts/instructions.ts` |
 | Add a tool (an action the agent can take) | new `agents/tools/<name>.ts`, then `.tool(<name>Tool)` in `agents/chat.ts` |
-| Add a skill (a documented procedure) | new `agents/skills/<name>.md` |
+| Add a skill (a procedure the model loads on demand) | `createSkill(...)` in `agents/skills/<name>.ts`, then add it to `defineSkillReadTool([...])` in `agents/chat.ts` |
 | Add a second agent | new `agents/<name>.ts` → auto-served at `/api/agents/<name>`, bind with `useAgent('<name>')` |
 | Change the greeting / app name | `shared/agent.ts` |
 | Add a backend route | `server/routes/<name>.ts` |

package/templates/default/package.json.tmpl

@@ -15,9 +15,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.31.0",
-    "@theokit/agents": "^0.35.2",
-    "@theokit/sdk": "^2.13.0",
+    "theokit": "^0.35.0",
+    "@theokit/agents": "^0.37.0",
+    "@theokit/sdk": "^2.25.0",
     "@theokit/ui": "^1.0.0",
     "@usetheo/ui": "^0.14.0",
     "ai": "^7.0.0",

package/templates/default/agents/skills/getting-started.md

@@ -1,21 +0,0 @@
-# Getting started
-
-A **skill** is a Markdown file that documents a repeatable task for your agent — a recipe it (and you) can
-follow. Skills live in the agent's `skills/` folder and are plain `.md`; reference them from your prompt or
-load them into context as your app grows.
-
-This example documents the scaffold itself:
-
-## Answer a question
-
-1. Read the user's message.
-2. If it needs live weather, call the `weather` tool (see `../tools/weather.ts`).
-3. Otherwise answer directly, concisely.
-
-## Add a capability to this agent
-
-- **A tool** (an action the agent can take) → `agents/tools/<name>.ts`, then `.tool(<name>Tool)` in
-  `agents/chat.ts`.
-- **A skill** (a documented procedure) → a new `agents/skills/<name>.md` like this one.
-- **The persona / rules** → edit `agents/prompts/instructions.ts`.
-- **A whole new agent** → a new folder `agents/<name>/index.ts` → served at `/api/agents/<name>`.