windmill-cli 1.625.0 → 1.628.0

package/esm/gen/core/OpenAPI.js

@@ -32,7 +32,7 @@ export const OpenAPI = {
     PASSWORD: undefined,
     TOKEN: getEnv("WM_TOKEN"),
     USERNAME: undefined,
-    VERSION: '1.625.0',
+    VERSION: '1.628.0',
     WITH_CREDENTIALS: true,
     interceptors: {
         request: new Interceptors(),

package/esm/src/commands/app/generate_agents.js

@@ -156,11 +156,13 @@ export async function regenerateAgentDocs(workspaceId, targetDir, silent = false
     // Generate and write AGENTS.md
     const agentsContent = generateAgentsDocumentation(localData);
     await dntShim.Deno.writeTextFile(path.join(targetDir, "AGENTS.md"), agentsContent);
+    // Generate and write CLAUDE.md referencing AGENTS.md
+    await dntShim.Deno.writeTextFile(path.join(targetDir, "CLAUDE.md"), `Instructions are in @AGENTS.md\n`);
     // Generate and write DATATABLES.md
     const datatablesContent = generateDatatablesMarkdown(schemas, localData);
     await dntShim.Deno.writeTextFile(path.join(targetDir, "DATATABLES.md"), datatablesContent);
     if (!silent) {
-        log.info(colors.green(`✓ Generated AGENTS.md and DATATABLES.md`));
+        log.info(colors.green(`✓ Generated AGENTS.md, CLAUDE.md, and DATATABLES.md`));
         // Summary
         const datatableCount = schemas.length;
         const tableCount = schemas.reduce((acc, dt) => {

package/esm/src/commands/app/new.js

@@ -440,6 +440,8 @@ CREATE SCHEMA IF NOT EXISTS ${schemaName};
         : undefined;
     const agentsContent = generateAgentsDocumentation(dataForDocs);
     await dntShim.Deno.writeTextFile(path.join(appDir, "AGENTS.md"), agentsContent);
+    // Create CLAUDE.md referencing AGENTS.md
+    await dntShim.Deno.writeTextFile(path.join(appDir, "CLAUDE.md"), `Instructions are in @AGENTS.md\n`);
     // Create DATATABLES.md with the configured data
     const datatablesContent = generateDatatablesDocumentation(dataForDocs);
     await dntShim.Deno.writeTextFile(path.join(appDir, "DATATABLES.md"), datatablesContent);

package/esm/src/commands/init/init.js

@@ -1,11 +1,22 @@
 import * as dntShim from "../../../_dnt.shims.js";
 import { colors, Command, log, yamlStringify, Confirm } from "../../../deps.js";
 import { readLockfile } from "../../utils/metadata.js";
-import { SCRIPT_GUIDANCE } from "../../guidance/script_guidance.js";
-import { FLOW_GUIDANCE } from "../../guidance/flow_guidance.js";
 import { getActiveWorkspaceOrFallback } from "../workspace/workspace.js";
 import { generateRTNamespace } from "../resource-type/resource-type.js";
-import { CLI_COMMANDS } from "../../guidance/prompts.js";
+import { SKILLS, SKILL_CONTENT, SCHEMAS, SCHEMA_MAPPINGS } from "../../guidance/skills.js";
+import { generateAgentsMdContent } from "../../guidance/core.js";
+/**
+ * Format a YAML schema for inclusion in skill markdown files.
+ */
+function formatSchemaForMarkdown(schemaYaml, schemaName, filePattern) {
+    return `## ${schemaName} (\`${filePattern}\`)
+
+Must be a YAML file that adheres to the following schema:
+
+\`\`\`yaml
+${schemaYaml.trim()}
+\`\`\``;
+}
 /**
  * Bootstrap a windmill project with a wmill.yaml file
  */
@@ -166,32 +177,60 @@ async function initAction(opts) {
             }
         }
     }
-    // Create .cursor/rules directory and files with SCRIPT_GUIDANCE content
+    // Create guidance files (AGENTS.md, CLAUDE.md, and Claude skills)
     try {
-        const scriptGuidanceContent = SCRIPT_GUIDANCE;
-        const flowGuidanceContent = FLOW_GUIDANCE;
-        const cliCommandsContent = CLI_COMMANDS;
-        // Create AGENTS.md file
+        // Generate skills reference section for AGENTS.md
+        const skills_base_dir = ".claude/skills";
+        const skillsReference = SKILLS.map((s) => `- \`${skills_base_dir}/${s.name}/SKILL.md\` - ${s.description}`).join("\n");
+        // Create AGENTS.md file with minimal instructions
         if (!(await dntShim.Deno.stat("AGENTS.md").catch(() => null))) {
-            await dntShim.Deno.writeTextFile("AGENTS.md", `
-You are a helpful assistant that can help with Windmill scripts and flows creation.
-
-## Script Guidance
-${scriptGuidanceContent}
-
-## Flow Guidance
-${flowGuidanceContent}
-
-## CLI Commands
-${cliCommandsContent}
-`);
+            await dntShim.Deno.writeTextFile("AGENTS.md", generateAgentsMdContent(skillsReference));
             log.info(colors.green("Created AGENTS.md"));
         }
         // Create CLAUDE.md file, referencing AGENTS.md
         if (!(await dntShim.Deno.stat("CLAUDE.md").catch(() => null))) {
-            await dntShim.Deno.writeTextFile("CLAUDE.md", "Instructions are in @AGENTS.md");
+            await dntShim.Deno.writeTextFile("CLAUDE.md", `Instructions are in @AGENTS.md
+`);
             log.info(colors.green("Created CLAUDE.md"));
         }
+        // Create .claude/skills/ directory and skill files
+        try {
+            await dntShim.Deno.mkdir(".claude/skills", { recursive: true });
+            await Promise.all(SKILLS.map(async (skill) => {
+                const skillDir = `.claude/skills/${skill.name}`;
+                await dntShim.Deno.mkdir(skillDir, { recursive: true });
+                let skillContent = SKILL_CONTENT[skill.name];
+                if (skillContent) {
+                    // Check if this skill has schemas that need to be appended
+                    const schemaMappings = SCHEMA_MAPPINGS[skill.name];
+                    if (schemaMappings && schemaMappings.length > 0) {
+                        // Combine base content with schemas
+                        const schemaDocs = schemaMappings
+                            .map((mapping) => {
+                            const schemaYaml = SCHEMAS[mapping.schemaKey];
+                            if (schemaYaml) {
+                                return formatSchemaForMarkdown(schemaYaml, mapping.name, mapping.filePattern);
+                            }
+                            return null;
+                        })
+                            .filter((doc) => doc !== null);
+                        if (schemaDocs.length > 0) {
+                            skillContent = skillContent + "\n\n" + schemaDocs.join("\n\n");
+                        }
+                    }
+                    await dntShim.Deno.writeTextFile(`${skillDir}/SKILL.md`, skillContent);
+                }
+            }));
+            log.info(colors.green(`Created .claude/skills/ with ${SKILLS.length} skills`));
+        }
+        catch (skillError) {
+            if (skillError instanceof Error) {
+                log.warn(`Could not create skills: ${skillError.message}`);
+            }
+            else {
+                log.warn(`Could not create skills: ${skillError}`);
+            }
+        }
     }
     catch (error) {
         if (error instanceof Error) {

package/esm/src/commands/sync/sync.js

@@ -202,8 +202,9 @@ export function extractFieldsForRawApps(runnables) {
     });
 }
 /**
- * Generates AGENTS.md - the main documentation file for AI agents working with raw apps.
- * This includes app structure, backend runnables, datatables usage, and all critical rules.
+ * Generates AGENTS.md - app-specific configuration for AI agents working with raw apps.
+ * References the raw-app skill for complete documentation and includes instance-specific
+ * data configuration (datatable, schema, whitelisted tables).
  */
 export function generateAgentsDocumentation(data) {
     const tables = data?.tables ?? [];
@@ -211,146 +212,13 @@ export function generateAgentsDocumentation(data) {
     const defaultSchema = data?.schema;
     return `# AI Agent Instructions
 
-This file contains instructions for AI agents (Claude, GPT, etc.) working with this Windmill raw app.
-**Read this file first** before making any changes to the app.
+For complete raw app documentation (app structure, backend runnables, datatables, SQL migrations), use the \`raw-app\` skill.
 
-## App Structure
-
-\`\`\`
-my_app.raw_app/
-├── AGENTS.md              # This file - read first!
-├── DATATABLES.md          # Database schemas (run 'wmill app generate-agents' to refresh)
-├── raw_app.yaml           # App configuration (summary, path, data settings)
-├── index.tsx              # Frontend entry point
-├── App.tsx                # Main React/Svelte/Vue component
-├── index.css              # Styles
-├── package.json           # Frontend dependencies
-├── wmill.ts               # Auto-generated - backend type definitions (DO NOT EDIT)
-├── backend/               # Backend runnables (server-side scripts)
-│   ├── <id>.<ext>         # Code file (e.g., get_user.ts) - auto-detected as inline
-│   ├── <id>.yaml          # Optional: config for fields, or to reference existing scripts
-│   └── <id>.lock          # Lock file (run 'wmill app generate-locks' to create)
-└── sql_to_apply/          # SQL migrations (dev only, not synced)
-    └── *.sql              # SQL files to apply via dev server
-\`\`\`
-
-## Backend Runnables
-
-Backend runnables are server-side scripts that your frontend can call. They live in the \`backend/\` folder.
-
-### Creating a Backend Runnable
-
-The simplest way to create a runnable is to add a code file:
-
-\`\`\`
-backend/<id>.<ext>
-\`\`\`
-
-The runnable ID is the filename without extension. For example, \`get_user.ts\` creates a runnable with ID \`get_user\`.
-
-**Optional:** Add a \`<id>.yaml\` file for additional configuration (fields, static values, etc.).
-
-### Supported Languages and Extensions
-
-| Language    | Extension      | Example            |
-|-------------|----------------|--------------------|
-| TypeScript  | \`.ts\`        | \`myFunc.ts\`      |
-| TypeScript (Bun) | \`.bun.ts\` | \`myFunc.bun.ts\` |
-| TypeScript (Deno) | \`.deno.ts\` | \`myFunc.deno.ts\` |
-| Python      | \`.py\`        | \`myFunc.py\`      |
-| Go          | \`.go\`        | \`myFunc.go\`      |
-| Bash        | \`.sh\`        | \`myFunc.sh\`      |
-| PowerShell  | \`.ps1\`       | \`myFunc.ps1\`     |
-| PostgreSQL  | \`.pg.sql\`    | \`myFunc.pg.sql\`  |
-| MySQL       | \`.my.sql\`    | \`myFunc.my.sql\`  |
-| BigQuery    | \`.bq.sql\`    | \`myFunc.bq.sql\`  |
-| Snowflake   | \`.sf.sql\`    | \`myFunc.sf.sql\`  |
-| MS SQL      | \`.ms.sql\`    | \`myFunc.ms.sql\`  |
-| GraphQL     | \`.gql\`       | \`myFunc.gql\`     |
-| PHP         | \`.php\`       | \`myFunc.php\`     |
-| Rust        | \`.rs\`        | \`myFunc.rs\`      |
-| C#          | \`.cs\`        | \`myFunc.cs\`      |
-| Java        | \`.java\`      | \`myFunc.java\`    |
-
-### Example: Creating a Runnable
-
-**backend/get_user.ts:**
-\`\`\`typescript
-import * as wmill from 'windmill-client';
-
-export async function main(user_id: string) {
-  const sql = wmill.datatable();
-  const user = await sql\`SELECT * FROM users WHERE id = \${user_id}\`.fetchOne();
-  return user;
-}
-\`\`\`
-
-That's it! The runnable is automatically detected and ready to use.
-
-**Generate lock files** for dependency management:
-\`\`\`bash
-wmill app generate-locks
-\`\`\`
-
-### Optional: YAML Configuration
-
-Add a \`<id>.yaml\` file to configure fields, static values, or other settings:
-
-**backend/get_user.yaml:**
-\`\`\`yaml
-type: inline
-fields:
-  user_id:
-    type: static
-    value: "default_user"
-\`\`\`
-
-### Referencing Existing Scripts
-
-To reference an existing Windmill script instead of inline code, use a different type:
-
-**backend/existing_script.yaml:**
-\`\`\`yaml
-type: script
-path: f/my_folder/existing_script
-\`\`\`
-
-For flows:
-\`\`\`yaml
-type: flow
-path: f/my_folder/my_flow
-\`\`\`
-
-### Calling Backend Runnables from Frontend
-
-Import from the auto-generated \`wmill.ts\`:
-
-\`\`\`typescript
-import { backend } from './wmill';
-
-// Call a backend runnable
-const user = await backend.get_user({ user_id: '123' });
-\`\`\`
-
-The \`wmill.ts\` file is auto-generated and provides type-safe access to all backend runnables.
+This file contains **app-specific configuration** for this raw app instance.
 
 ---
 
-## ⚠️ CRITICAL RULES FOR DATA TABLES
-
-**These rules are mandatory - violating them will cause runtime errors:**
-
-1. **ONLY USE WHITELISTED TABLES**: You can ONLY query tables listed in \`raw_app.yaml\` → \`data.tables\`.
-   Tables not in this list are NOT accessible to the app.
-
-2. **ADD TABLES BEFORE USING**: To use a new table, you MUST first add it to \`data.tables\` in \`raw_app.yaml\`.
-
-3. **USE CONFIGURED DATATABLE/SCHEMA**: When looking for tables:
-   - First, check the whitelisted tables below
-   - If creating new tables, use the default datatable${defaultSchema ? ` and schema` : ''} configured for this app
-   - See \`DATATABLES.md\` for full schema information
-
-### Current Data Configuration
+## Data Configuration
 
 ${defaultDatatable
         ? `**Default Datatable:** \`${defaultDatatable}\`${defaultSchema ? ` | **Default Schema:** \`${defaultSchema}\`` : ''}`
@@ -362,7 +230,7 @@ ${tables.length > 0
         ? `These tables are accessible to this app:\n\n${tables.map(t => `- \`${t}\``).join('\n')}`
         : `**No tables whitelisted.** Add tables to \`data.tables\` in \`raw_app.yaml\`.`}
 
-### Adding a Table to the Whitelist
+### Adding a Table
 
 Edit \`raw_app.yaml\`:
 
@@ -375,116 +243,31 @@ ${tables.length > 0 ? tables.map(t => `    - ${t}`).join('\n') : '    # Add tabl
 \`\`\`
 
 **Table reference formats:**
-- \`<datatable>\` - All tables in the datatable
-- \`<datatable>/<table>\` - Specific table in public schema
+- \`<datatable>/<table>\` - Table in public schema
 - \`<datatable>/<schema>:<table>\` - Table in specific schema
 
 ---
 
-## Querying Data Tables
+## Quick Reference
 
-### TypeScript (Bun/Deno)
+**Backend runnable:** Add \`backend/<name>.ts\` (or .py, etc.), then run \`wmill app generate-locks\`
 
+**Call from frontend:**
 \`\`\`typescript
-import * as wmill from 'windmill-client';
-
-export async function main(user_id: string) {
-  const sql = wmill.datatable();  // Or: wmill.datatable('other_datatable')
-
-  // Parameterized queries (safe from SQL injection)
-  const user = await sql\`SELECT * FROM users WHERE id = \${user_id}\`.fetchOne();
-  const users = await sql\`SELECT * FROM users WHERE active = \${true}\`.fetch();
-
-  // Insert/Update
-  await sql\`INSERT INTO users (name, email) VALUES (\${name}, \${email})\`;
-  await sql\`UPDATE users SET name = \${newName} WHERE id = \${user_id}\`;
-
-  return user;
-}
-\`\`\`
-
-### Python
-
-\`\`\`python
-import wmill
-
-def main(user_id: str):
-    db = wmill.datatable()  # Or: wmill.datatable('other_datatable')
-
-    # Use $1, $2, etc. for parameters
-    user = db.query('SELECT * FROM users WHERE id = $1', user_id).fetch_one()
-    users = db.query('SELECT * FROM users WHERE active = $1', True).fetch()
-
-    # Insert/Update
-    db.query('INSERT INTO users (name, email) VALUES ($1, $2)', name, email)
-    db.query('UPDATE users SET name = $1 WHERE id = $2', new_name, user_id)
-
-    return user
-\`\`\`
-
----
-
-## SQL Migrations (sql_to_apply/)
-
-The \`sql_to_apply/\` folder is for creating/modifying database tables during development.
-
-### How It Works
-
-1. Create \`.sql\` files in \`sql_to_apply/\`
-2. Run \`wmill app dev\` - the dev server watches this folder
-3. When SQL files change, a modal appears in the browser to confirm execution
-4. After creating tables, **add them to \`data.tables\`** in \`raw_app.yaml\`
-
-### Example Migration
-
-**sql_to_apply/001_create_users.sql:**
-\`\`\`sql
-CREATE TABLE IF NOT EXISTS ${defaultSchema ? defaultSchema + '.' : ''}users (
-    id SERIAL PRIMARY KEY,
-    email TEXT NOT NULL UNIQUE,
-    name TEXT,
-    created_at TIMESTAMP DEFAULT NOW()
-);
+import { backend } from './wmill';
+const result = await backend.<name>({ arg: 'value' });
 \`\`\`
 
-After applying, add to \`raw_app.yaml\`:
-\`\`\`yaml
-data:
-  tables:
-    - ${defaultDatatable || 'main'}/${defaultSchema ? defaultSchema + ':' : ''}users
+**Query datatable (TypeScript):**
+\`\`\`typescript
+const sql = wmill.datatable();
+const rows = await sql\`SELECT * FROM table WHERE id = \${id}\`.fetch();
 \`\`\`
 
-### Important Notes
-
-- **This folder is NOT synced** - it's local development only
-- **Use idempotent SQL**: \`CREATE TABLE IF NOT EXISTS\`, etc.
-- **Number your files**: \`001_\`, \`002_\` for ordering
-- **Always whitelist tables after creation**
-
----
-
-## Commands Reference
-
-| Command | Description |
-|---------|-------------|
-| \`wmill app dev\` | Start dev server with live reload |
-| \`wmill app generate-agents\` | Refresh AGENTS.md and DATATABLES.md |
-| \`wmill app generate-locks\` | Generate lock files for backend runnables |
-| \`wmill sync push\` | Deploy app to Windmill |
-| \`wmill sync pull\` | Pull latest from Windmill |
-
----
-
-## Best Practices
-
-1. **Check DATATABLES.md** for existing tables before creating new ones
-2. **Use parameterized queries** - never concatenate user input into SQL
-3. **Keep runnables focused** - one function per file
-4. **Use descriptive IDs** - \`get_user.ts\` not \`a.ts\`
-5. **Always whitelist tables** - add to \`data.tables\` before querying
+**SQL migrations:** Add \`.sql\` files to \`sql_to_apply/\`, run \`wmill app dev\`, then whitelist tables
 
 ---
-*This file is auto-generated. Run \`wmill app new\` or \`wmill sync pull\` to regenerate.*
+*Run \`wmill app generate-agents\` to refresh. See \`.claude/skills/raw-app\` skill for full documentation.*
 `;
 }
 /**

package/esm/src/guidance/core.js

@@ -0,0 +1,57 @@
+/**
+ * Core guidance content for AGENTS.md
+ *
+ * This module exports the template for the AGENTS.md file that provides
+ * AI agent instructions for working with Windmill projects.
+ */
+/**
+ * Generate the AGENTS.md content with the given skills reference.
+ * @param skillsReference - A formatted list of skills to include in the document
+ * @returns The complete AGENTS.md content
+ */
+export function generateAgentsMdContent(skillsReference) {
+    return `# Windmill AI Agent Instructions
+
+You are a helpful assistant that can help with Windmill scripts, flows, apps, and resources management.
+
+## Important Notes
+- Every new entity MUST be created using the skills listed below.
+- Every modification of an entity MUST be done using the skills listed below.
+- User MUST be asked where to create the entity. It can be in its user folder, under u/{user_name} folder, or in a new folder, /f/{folder_name}/. folder_name and user_name must be provided by the user.
+
+## Script Writing Guide
+
+You MUST use the \`write-script-<language>\` skill to write or modify scripts in the language specified by the user. Use bun by default.
+
+## Flow Writing Guide
+
+You MUST use the \`write-flow\` skill to create or modify flows.
+
+## Raw App Development
+
+You MUST use the \`raw-app\` skill to create or modify raw apps.
+Whenever a new app needs to be created you MUST ask the user to run \`wmill app new\` in its terminal first.
+
+## Triggers
+
+You MUST use the \`triggers\` skill to configure HTTP routes, WebSocket, Kafka, NATS, SQS, MQTT, GCP, or Postgres CDC triggers.
+
+## Schedules
+
+You MUST use the \`schedules\` skill to configure cron schedules.
+
+## Resources
+
+You MUST use the \`resources\` skill to manage resource types and credentials.
+
+## CLI Reference
+
+You MUST use the \`cli-commands\` skill to use the CLI.
+
+## Skills
+
+For specific guidance, ALWAYS use the skills listed below.
+
+${skillsReference}
+`;
+}