assistme 0.2.6 → 0.2.7

package/dist/index.js

@@ -1812,6 +1812,11 @@ var SkillManager = class {
    * Convert a DB row to a Skill object.
    */
   rowToSkill(row) {
+    const meta = row.metadata || {};
+    const rawVars = row.variables || meta.variables;
+    const variables = Array.isArray(rawVars) ? rawVars : void 0;
+    const rawConfig = row.config;
+    const config = rawConfig && typeof rawConfig === "object" ? rawConfig : void 0;
     return {
       name: row.name,
       description: row.description || "",
@@ -1827,7 +1832,9 @@ var SkillManager = class {
       filePath: "",
       source: row.source || "manual",
       dbId: row.id,
-      sourceSkillId: row.source_skill_id || void 0
+      sourceSkillId: row.source_skill_id || void 0,
+      variables,
+      config
     };
   }
   /**
@@ -1966,7 +1973,13 @@ _(${skills.length - included} additional skills available \u2014 use skill_invok
     try {
       const sb = getSupabase();
       const source = options?.source || "manual";
-      const metadata = options?.emoji ? { openclaw: { emoji: options.emoji } } : {};
+      const metadata = {};
+      if (options?.emoji) {
+        metadata.openclaw = { emoji: options.emoji };
+      }
+      if (options?.variables && options.variables.length > 0) {
+        metadata.variables = options.variables;
+      }
       const { data, error } = await sb.rpc("create_skill", {
         p_user_id: this.userId,
         p_name: name,
@@ -2138,6 +2151,10 @@ _(${skills.length - included} additional skills available \u2014 use skill_invok
     if (!this.userId) return;
     try {
       const sb = getSupabase();
+      const metadata = {};
+      if (options?.variables && options.variables.length > 0) {
+        metadata.variables = options.variables;
+      }
       const { data, error } = await sb.rpc("upsert_agent_skill", {
         p_user_id: this.userId,
         p_name: name,
@@ -2148,7 +2165,8 @@ _(${skills.length - included} additional skills available \u2014 use skill_invok
         p_emoji: options?.emoji || null,
         p_keywords: options?.keywords || [],
         p_change_summary: options?.changeSummary || null,
-        p_source_skill_id: options?.sourceSkillId || null
+        p_source_skill_id: options?.sourceSkillId || null,
+        p_metadata: Object.keys(metadata).length > 0 ? metadata : null
       });
       if (error) {
         log.debug(`DB skill sync failed for "${name}": ${error.message}`);
@@ -2158,6 +2176,9 @@ _(${skills.length - included} additional skills available \u2014 use skill_invok
       if (skill && data && typeof data === "object" && "id" in data) {
         skill.dbId = data.id;
       }
+      if (skill && options?.variables) {
+        skill.variables = options.variables;
+      }
       log.debug(`Skill "${name}" synced to agent_skills`);
     } catch (err) {
       log.debug(`DB skill sync error for "${name}": ${err}`);
@@ -2314,7 +2335,54 @@ _(${skills.length - included} additional skills available \u2014 use skill_invok
       return [];
     }
   }
+  // ── Variable Configuration ──────────────────────────────────────────
+  /**
+   * Update user-specific variable values (config) for a skill.
+   * Persists to agent_skills.config in DB and updates in-memory.
+   */
+  async updateConfig(skillName, config) {
+    const skill = this.skills.get(skillName);
+    if (!skill) return false;
+    const merged = { ...skill.config || {}, ...config };
+    skill.config = merged;
+    if (this.userId && skill.dbId) {
+      try {
+        const sb = getSupabase();
+        await sb.from("agent_skills").update({ config: merged }).eq("id", skill.dbId).eq("user_id", this.userId);
+        log.debug(`Config updated for skill "${skillName}"`);
+      } catch (err) {
+        log.debug(`Config update failed for "${skillName}": ${err}`);
+      }
+    }
+    return true;
+  }
+  /**
+   * Get the unresolved (unconfigured) variables for a skill.
+   * Returns variables that are required but have no value in config.
+   */
+  getUnconfiguredVariables(skillName) {
+    const skill = this.skills.get(skillName);
+    if (!skill?.variables) return [];
+    return skill.variables.filter((v) => {
+      if (!v.required) return false;
+      const value = skill.config?.[v.name];
+      return value === void 0 || value === null || value === "";
+    });
+  }
 };
+function substituteVariables(content, config, variables) {
+  if (!content.includes("{{")) return content;
+  return content.replace(/\{\{(\w+)\}\}/g, (match, varName) => {
+    const value = config?.[varName];
+    if (value !== void 0 && value !== null) {
+      if (Array.isArray(value)) return value.join(", ");
+      return String(value);
+    }
+    const varDef = variables?.find((v) => v.name === varName);
+    if (varDef?.default !== void 0) return varDef.default;
+    return `{{${varName}: [NOT CONFIGURED]}}`;
+  });
+}
 function substituteArguments(content, args) {
   const parts = args.split(/\s+/);
   content = content.replace(/\$ARGUMENTS/g, args);
@@ -2976,12 +3044,24 @@ function createAgentToolsServer(deps) {
       ),
       tool(
         "skill_create",
-        "Create a new skill and add it to the user's collection. Returns the skill ID on success.",
+        "Create a new skill and add it to the user's collection. Returns the skill ID on success. Use {{variable_name}} syntax in instructions for user-specific data (e.g. {{github_repos}}, {{slack_channel}}).",
         {
           name: z.string().describe("Skill name in kebab-case, e.g. 'flight-booking'"),
           description: z.string().describe("One-line description of what this skill does"),
-          instructions: z.string().describe("Markdown step-by-step instructions"),
-          emoji: z.string().optional().describe("Single emoji representing this skill")
+          instructions: z.string().describe(
+            "Markdown step-by-step instructions. Use {{variable_name}} placeholders for user-specific data (e.g. {{github_repos}}, {{trello_board}}, {{slack_channel}}). These will be resolved with user's config at invoke time."
+          ),
+          emoji: z.string().optional().describe("Single emoji representing this skill"),
+          variables: z.array(z.object({
+            name: z.string().describe("Variable name matching {{name}} in instructions"),
+            description: z.string().describe("Human-readable description of what this variable is for"),
+            type: z.enum(["string", "string[]", "number", "boolean"]).describe("Data type"),
+            required: z.boolean().describe("Whether the skill needs this to function"),
+            default: z.string().optional().describe("Default value if user doesn't configure"),
+            example: z.string().optional().describe("Example value to guide the user")
+          })).optional().describe(
+            "Variables that need user-specific configuration. Define one for each {{variable}} used in instructions."
+          )
         },
         async (args) => {
           const existing = skillManager.findSimilar(args.name);
@@ -2999,7 +3079,11 @@ function createAgentToolsServer(deps) {
             args.name,
             args.description,
             args.instructions,
-            { source: "manual", emoji: args.emoji }
+            {
+              source: "manual",
+              emoji: args.emoji,
+              variables: args.variables
+            }
           );
           if (!result) {
             return {
@@ -3014,17 +3098,30 @@ function createAgentToolsServer(deps) {
             {
               source: "manual",
               emoji: args.emoji,
-              sourceSkillId: result.id
+              sourceSkillId: result.id,
+              variables: args.variables
             }
           );
+          let responseText = `Skill "${args.name}" created and added to your collection (ID: ${result.id}).`;
+          if (args.variables && args.variables.length > 0) {
+            const requiredVars = args.variables.filter((v) => v.required);
+            if (requiredVars.length > 0) {
+              responseText += `
+
+**Variables that need configuration:**
+`;
+              for (const v of requiredVars) {
+                const example = v.example ? ` (e.g. ${v.example})` : "";
+                responseText += `- \`{{${v.name}}}\`: ${v.description}${example}
+`;
+              }
+              responseText += `
+Use \`skill_configure\` to set these values for the user, or ask the user to provide them.`;
+            }
+          }
           log.success(`Skill "${args.name}" created and added to collection`);
           return {
-            content: [
-              {
-                type: "text",
-                text: `Skill "${args.name}" created and added to your collection (ID: ${result.id}).`
-              }
-            ]
+            content: [{ type: "text", text: responseText }]
           };
         }
       ),
@@ -3096,6 +3193,7 @@ function createAgentToolsServer(deps) {
             };
           }
           let content = skill.content;
+          content = substituteVariables(content, skill.config, skill.variables);
           if (args.arguments) {
             content = substituteArguments(content, args.arguments);
           }
@@ -3114,6 +3212,18 @@ ${content}`;
 **Allowed tools for this skill:** ${skill.allowedTools.join(", ")}
 `;
           }
+          const unconfigured = skillManager.getUnconfiguredVariables(args.name);
+          if (unconfigured.length > 0) {
+            response += `
+
+**\u26A0 Unconfigured variables \u2014 use \`skill_configure\` to set these:**
+`;
+            for (const v of unconfigured) {
+              const example = v.example ? ` (e.g. ${v.example})` : "";
+              response += `- \`{{${v.name}}}\`: ${v.description}${example}
+`;
+            }
+          }
           log.info(`Skill invoked: "${args.name}"`);
           skillManager.logInvocation(args.name, {
             messageId: taskId,
@@ -3153,6 +3263,53 @@ ${content}`;
           return { content: [{ type: "text", text: response }] };
         }
       ),
+      tool(
+        "skill_configure",
+        "Set user-specific variable values for a skill. Variables are defined in the skill template (e.g. {{github_repos}}) and need to be configured with the user's actual data before the skill can work properly.",
+        {
+          name: z.string().describe("Name of the skill to configure"),
+          config: z.record(z.unknown()).describe(
+            'Key-value pairs of variable values. Keys must match variable names defined in the skill. Example: {"github_repos": ["octocat/hello-world", "myorg/myrepo"], "github_username": "octocat"}'
+          )
+        },
+        async (args) => {
+          const skill = skillManager.get(args.name);
+          if (!skill) {
+            const available = skillManager.getAll().map((s) => s.name).join(", ");
+            return {
+              content: [{
+                type: "text",
+                text: `Skill "${args.name}" not found. Available: ${available}`
+              }]
+            };
+          }
+          const updated = await skillManager.updateConfig(args.name, args.config);
+          if (!updated) {
+            return {
+              content: [{ type: "text", text: `Failed to update config for "${args.name}".` }]
+            };
+          }
+          const unconfigured = skillManager.getUnconfiguredVariables(args.name);
+          let responseText = `Configuration updated for skill "${args.name}".`;
+          if (unconfigured.length > 0) {
+            responseText += `
+
+**Still needs configuration:**
+`;
+            for (const v of unconfigured) {
+              const example = v.example ? ` (e.g. ${v.example})` : "";
+              responseText += `- \`{{${v.name}}}\`: ${v.description}${example}
+`;
+            }
+          } else {
+            responseText += ` All required variables are configured.`;
+          }
+          log.info(`Config updated for skill "${args.name}": ${Object.keys(args.config).join(", ")}`);
+          return {
+            content: [{ type: "text", text: responseText }]
+          };
+        }
+      ),
       tool(
         "skill_generate",
         "Prepare context for generating skills from a job description. Returns existing skills and job info so you can analyze the job and create skills using skill_create (which auto-adds to user's collection). After creating all skills, call skill_link_job to link them to the job and mark it as analyzed.",
@@ -3201,6 +3358,8 @@ ${content}`;
           response += `- instructions: detailed step-by-step markdown instructions the agent can follow
 `;
           response += `- emoji: a single emoji representing the skill
+`;
+          response += `- variables: define user-specific data needed by the skill (see below)
 
 `;
           response += `skill_create automatically adds the skill to the user's collection \u2014 no need to call skill_add.
@@ -3216,10 +3375,60 @@ ${content}`;
           response += `- Reference browser tools (browser_navigate, browser_click, browser_read_page, etc.) for web tasks
 `;
           response += `- Include error handling steps
-`;
-          response += `- Use placeholders like {query}, {date} for variable inputs
 `;
           response += `- Each skill should be a single, well-defined workflow (10-25 steps)
+
+`;
+          response += `**IMPORTANT \u2014 Use {{variables}} for user-specific data:**
+`;
+          response += `Skills often need user-specific information (accounts, repos, boards, channels, etc.).
+`;
+          response += `Instead of hardcoding or asking at runtime, use \`{{variable_name}}\` placeholders in instructions.
+
+`;
+          response += `Example: A GitHub PR review skill should use \`{{github_repos}}\` in its instructions:
+`;
+          response += `  "Navigate to each repository in {{github_repos}} and check for open PRs..."
+
+`;
+          response += `For each \`{{variable}}\` used in instructions, add a matching entry in the \`variables\` array:
+`;
+          response += `\`\`\`json
+`;
+          response += `{
+`;
+          response += `  "name": "github_repos",
+`;
+          response += `  "description": "GitHub repositories to monitor (owner/repo format)",
+`;
+          response += `  "type": "string[]",
+`;
+          response += `  "required": true,
+`;
+          response += `  "example": "octocat/hello-world, myorg/myrepo"
+`;
+          response += `}
+`;
+          response += `\`\`\`
+
+`;
+          response += `Common variables by platform:
+`;
+          response += `- GitHub: github_repos, github_username, github_org
+`;
+          response += `- Trello: trello_board_url, trello_list_names
+`;
+          response += `- Slack: slack_channels, slack_workspace_url
+`;
+          response += `- Email: email_labels, email_filters
+`;
+          response += `- E-commerce: store_url, competitor_urls, product_categories
+`;
+          response += `- General: timezone, language, notification_channel
+
+`;
+          response += `After creating skills, if any have required variables, call \`skill_configure\` to set initial values `;
+          response += `(ask the user for the values first).
 `;
           return { content: [{ type: "text", text: response }] };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assistme",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "AssistMe CLI Agent - AI-powered assistant that controls your real browser",
   "type": "module",
   "main": "dist/index.js",

package/src/agent/mcp-servers.ts

@@ -8,8 +8,8 @@ import { executeTool } from "../tools/index.js";
 import { getLimiterForTool } from "../utils/rate-limiter.js";
 import { log } from "../utils/logger.js";
 import type { MemoryManager, MemoryCategory } from "./memory.js";
-import type { SkillManager } from "./skills.js";
-import { substituteArguments, preprocessDynamicContext } from "./skills.js";
+import type { SkillManager, SkillVariable } from "./skills.js";
+import { substituteArguments, substituteVariables, preprocessDynamicContext } from "./skills.js";
 import { getSupabase, emitEvent, setActionRequest, pollActionResponse } from "../db/supabase.js";
 import { JobRunner } from "./job-runner.js";
 import {
@@ -214,12 +214,26 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
       ),
       tool(
         "skill_create",
-        "Create a new skill and add it to the user's collection. Returns the skill ID on success.",
+        "Create a new skill and add it to the user's collection. Returns the skill ID on success. " +
+          "Use {{variable_name}} syntax in instructions for user-specific data (e.g. {{github_repos}}, {{slack_channel}}).",
         {
           name: z.string().describe("Skill name in kebab-case, e.g. 'flight-booking'"),
           description: z.string().describe("One-line description of what this skill does"),
-          instructions: z.string().describe("Markdown step-by-step instructions"),
+          instructions: z.string().describe(
+            "Markdown step-by-step instructions. Use {{variable_name}} placeholders for user-specific data " +
+              "(e.g. {{github_repos}}, {{trello_board}}, {{slack_channel}}). These will be resolved with user's config at invoke time."
+          ),
           emoji: z.string().optional().describe("Single emoji representing this skill"),
+          variables: z.array(z.object({
+            name: z.string().describe("Variable name matching {{name}} in instructions"),
+            description: z.string().describe("Human-readable description of what this variable is for"),
+            type: z.enum(["string", "string[]", "number", "boolean"]).describe("Data type"),
+            required: z.boolean().describe("Whether the skill needs this to function"),
+            default: z.string().optional().describe("Default value if user doesn't configure"),
+            example: z.string().optional().describe("Example value to guide the user"),
+          })).optional().describe(
+            "Variables that need user-specific configuration. Define one for each {{variable}} used in instructions."
+          ),
         },
         async (args) => {
           // Check for duplicates in user's collection
@@ -240,7 +254,11 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
             args.name,
             args.description,
             args.instructions,
-            { source: "manual", emoji: args.emoji }
+            {
+              source: "manual",
+              emoji: args.emoji,
+              variables: args.variables as SkillVariable[] | undefined,
+            }
           );
 
           if (!result) {
@@ -259,17 +277,27 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
               source: "manual",
               emoji: args.emoji,
               sourceSkillId: result.id,
+              variables: args.variables as SkillVariable[] | undefined,
             }
           );
 
+          // Build response with variable info
+          let responseText = `Skill "${args.name}" created and added to your collection (ID: ${result.id}).`;
+          if (args.variables && args.variables.length > 0) {
+            const requiredVars = args.variables.filter((v) => v.required);
+            if (requiredVars.length > 0) {
+              responseText += `\n\n**Variables that need configuration:**\n`;
+              for (const v of requiredVars) {
+                const example = v.example ? ` (e.g. ${v.example})` : "";
+                responseText += `- \`{{${v.name}}}\`: ${v.description}${example}\n`;
+              }
+              responseText += `\nUse \`skill_configure\` to set these values for the user, or ask the user to provide them.`;
+            }
+          }
+
           log.success(`Skill "${args.name}" created and added to collection`);
           return {
-            content: [
-              {
-                type: "text",
-                text: `Skill "${args.name}" created and added to your collection (ID: ${result.id}).`,
-              },
-            ],
+            content: [{ type: "text", text: responseText }],
           };
         }
       ),
@@ -354,6 +382,9 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
 
           let content = skill.content;
 
+          // Substitute {{variable}} placeholders with user config values
+          content = substituteVariables(content, skill.config, skill.variables);
+
           // Substitute $ARGUMENTS placeholders
           if (args.arguments) {
             content = substituteArguments(content, args.arguments);
@@ -374,6 +405,16 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
             response += `\n\n**Allowed tools for this skill:** ${skill.allowedTools.join(", ")}\n`;
           }
 
+          // Warn about unconfigured required variables
+          const unconfigured = skillManager.getUnconfiguredVariables(args.name);
+          if (unconfigured.length > 0) {
+            response += `\n\n**⚠ Unconfigured variables — use \`skill_configure\` to set these:**\n`;
+            for (const v of unconfigured) {
+              const example = v.example ? ` (e.g. ${v.example})` : "";
+              response += `- \`{{${v.name}}}\`: ${v.description}${example}\n`;
+            }
+          }
+
           log.info(`Skill invoked: "${args.name}"`);
 
           // Log invocation to DB (fire-and-forget)
@@ -416,6 +457,56 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
           return { content: [{ type: "text", text: response }] };
         }
       ),
+      tool(
+        "skill_configure",
+        "Set user-specific variable values for a skill. Variables are defined in the skill template (e.g. {{github_repos}}) " +
+          "and need to be configured with the user's actual data before the skill can work properly.",
+        {
+          name: z.string().describe("Name of the skill to configure"),
+          config: z.record(z.unknown()).describe(
+            "Key-value pairs of variable values. Keys must match variable names defined in the skill. " +
+              "Example: {\"github_repos\": [\"octocat/hello-world\", \"myorg/myrepo\"], \"github_username\": \"octocat\"}"
+          ),
+        },
+        async (args) => {
+          const skill = skillManager.get(args.name);
+          if (!skill) {
+            const available = skillManager.getAll().map((s) => s.name).join(", ");
+            return {
+              content: [{
+                type: "text",
+                text: `Skill "${args.name}" not found. Available: ${available}`,
+              }],
+            };
+          }
+
+          const updated = await skillManager.updateConfig(args.name, args.config);
+          if (!updated) {
+            return {
+              content: [{ type: "text", text: `Failed to update config for "${args.name}".` }],
+            };
+          }
+
+          // Check if there are still unconfigured required variables
+          const unconfigured = skillManager.getUnconfiguredVariables(args.name);
+          let responseText = `Configuration updated for skill "${args.name}".`;
+
+          if (unconfigured.length > 0) {
+            responseText += `\n\n**Still needs configuration:**\n`;
+            for (const v of unconfigured) {
+              const example = v.example ? ` (e.g. ${v.example})` : "";
+              responseText += `- \`{{${v.name}}}\`: ${v.description}${example}\n`;
+            }
+          } else {
+            responseText += ` All required variables are configured.`;
+          }
+
+          log.info(`Config updated for skill "${args.name}": ${Object.keys(args.config).join(", ")}`);
+          return {
+            content: [{ type: "text", text: responseText }],
+          };
+        }
+      ),
       tool(
         "skill_generate",
         "Prepare context for generating skills from a job description. Returns existing skills and job info " +
@@ -451,15 +542,39 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
           response += `- name: kebab-case name (e.g. "slack-message-check")\n`;
           response += `- description: one-line description\n`;
           response += `- instructions: detailed step-by-step markdown instructions the agent can follow\n`;
-          response += `- emoji: a single emoji representing the skill\n\n`;
+          response += `- emoji: a single emoji representing the skill\n`;
+          response += `- variables: define user-specific data needed by the skill (see below)\n\n`;
           response += `skill_create automatically adds the skill to the user's collection — no need to call skill_add.\n\n`;
           response += `After ALL skills are created, call \`skill_link_job\` with job_name="${args.job_name}" and the list of created skill names to link them and mark the job as analyzed.\n\n`;
           response += `**Guidelines for skill instructions:**\n`;
           response += `- Write clear, actionable markdown steps\n`;
           response += `- Reference browser tools (browser_navigate, browser_click, browser_read_page, etc.) for web tasks\n`;
           response += `- Include error handling steps\n`;
-          response += `- Use placeholders like {query}, {date} for variable inputs\n`;
-          response += `- Each skill should be a single, well-defined workflow (10-25 steps)\n`;
+          response += `- Each skill should be a single, well-defined workflow (10-25 steps)\n\n`;
+          response += `**IMPORTANT — Use {{variables}} for user-specific data:**\n`;
+          response += `Skills often need user-specific information (accounts, repos, boards, channels, etc.).\n`;
+          response += `Instead of hardcoding or asking at runtime, use \`{{variable_name}}\` placeholders in instructions.\n\n`;
+          response += `Example: A GitHub PR review skill should use \`{{github_repos}}\` in its instructions:\n`;
+          response += `  "Navigate to each repository in {{github_repos}} and check for open PRs..."\n\n`;
+          response += `For each \`{{variable}}\` used in instructions, add a matching entry in the \`variables\` array:\n`;
+          response += `\`\`\`json\n`;
+          response += `{\n`;
+          response += `  "name": "github_repos",\n`;
+          response += `  "description": "GitHub repositories to monitor (owner/repo format)",\n`;
+          response += `  "type": "string[]",\n`;
+          response += `  "required": true,\n`;
+          response += `  "example": "octocat/hello-world, myorg/myrepo"\n`;
+          response += `}\n`;
+          response += `\`\`\`\n\n`;
+          response += `Common variables by platform:\n`;
+          response += `- GitHub: github_repos, github_username, github_org\n`;
+          response += `- Trello: trello_board_url, trello_list_names\n`;
+          response += `- Slack: slack_channels, slack_workspace_url\n`;
+          response += `- Email: email_labels, email_filters\n`;
+          response += `- E-commerce: store_url, competitor_urls, product_categories\n`;
+          response += `- General: timezone, language, notification_channel\n\n`;
+          response += `After creating skills, if any have required variables, call \`skill_configure\` to set initial values `;
+          response += `(ask the user for the values first).\n`;
 
           return { content: [{ type: "text", text: response }] };
         }

package/src/agent/skills.ts

@@ -67,6 +67,26 @@ export interface SkillMetadata {
   skillKey?: string;
 }
 
+/**
+ * A variable that a skill requires from the user.
+ * Variables are defined in the skill template (e.g. `{{github_repos}}`)
+ * and resolved with user-specific values stored in agent_skills.config.
+ */
+export interface SkillVariable {
+  /** Variable name used in templates, e.g. "github_repos" */
+  name: string;
+  /** Human-readable description, e.g. "GitHub repositories to monitor" */
+  description: string;
+  /** Data type of the variable */
+  type: "string" | "string[]" | "number" | "boolean";
+  /** Whether the skill cannot function without this variable */
+  required: boolean;
+  /** Default value if not configured by user */
+  default?: string;
+  /** Example value to guide the user, e.g. "octocat/hello-world, myorg/myrepo" */
+  example?: string;
+}
+
 export interface Skill {
   name: string;
   description: string;
@@ -83,6 +103,10 @@ export interface Skill {
   source: "bundled" | "manual" | "external" | "auto_extracted" | "auto_improved" | "job_generated";
   dbId?: string; // UUID from agent_skills table
   sourceSkillId?: string; // UUID from skills table (origin)
+  /** Variable definitions declared by the skill template */
+  variables?: SkillVariable[];
+  /** User-specific variable values (from agent_skills.config) */
+  config?: Record<string, unknown>;
 }
 
 /**
@@ -174,6 +198,15 @@ export class SkillManager {
    * Convert a DB row to a Skill object.
    */
   private rowToSkill(row: Record<string, unknown>): Skill {
+    // Parse variables from metadata.variables or top-level variables column
+    const meta = (row.metadata || {}) as Record<string, unknown>;
+    const rawVars = (row.variables || meta.variables) as SkillVariable[] | undefined;
+    const variables = Array.isArray(rawVars) ? rawVars : undefined;
+
+    // Parse user config (variable values) from config column
+    const rawConfig = row.config as Record<string, unknown> | undefined;
+    const config = rawConfig && typeof rawConfig === "object" ? rawConfig : undefined;
+
     return {
       name: row.name as string,
       description: (row.description as string) || "",
@@ -190,6 +223,8 @@ export class SkillManager {
       source: (row.source as Skill["source"]) || "manual",
       dbId: row.id as string,
       sourceSkillId: (row.source_skill_id as string) || undefined,
+      variables,
+      config,
     };
   }
 
@@ -360,16 +395,20 @@ export class SkillManager {
     name: string,
     description: string,
     content: string,
-    options?: { source?: string; emoji?: string; keywords?: string[] }
+    options?: { source?: string; emoji?: string; keywords?: string[]; variables?: SkillVariable[] }
   ): Promise<{ id: string; name: string } | null> {
     if (!this.userId) return null;
 
     try {
       const sb = getSupabase();
       const source = options?.source || "manual";
-      const metadata = options?.emoji
-        ? { openclaw: { emoji: options.emoji } }
-        : {};
+      const metadata: Record<string, unknown> = {};
+      if (options?.emoji) {
+        metadata.openclaw = { emoji: options.emoji };
+      }
+      if (options?.variables && options.variables.length > 0) {
+        metadata.variables = options.variables;
+      }
 
       const { data, error } = await sb.rpc("create_skill", {
         p_user_id: this.userId,
@@ -607,12 +646,20 @@ export class SkillManager {
       keywords?: string[];
       changeSummary?: string;
       sourceSkillId?: string;
+      variables?: SkillVariable[];
     }
   ): Promise<void> {
     if (!this.userId) return;
 
     try {
       const sb = getSupabase();
+
+      // Store variables in metadata for agent_skills
+      const metadata: Record<string, unknown> = {};
+      if (options?.variables && options.variables.length > 0) {
+        metadata.variables = options.variables;
+      }
+
       const { data, error } = await sb.rpc("upsert_agent_skill", {
         p_user_id: this.userId,
         p_name: name,
@@ -624,6 +671,7 @@ export class SkillManager {
         p_keywords: options?.keywords || [],
         p_change_summary: options?.changeSummary || null,
         p_source_skill_id: options?.sourceSkillId || null,
+        p_metadata: Object.keys(metadata).length > 0 ? metadata : null,
       });
 
       if (error) {
@@ -631,11 +679,14 @@ export class SkillManager {
         return;
       }
 
-      // Update in-memory dbId if returned
+      // Update in-memory skill with dbId and variables
       const skill = this.skills.get(name);
       if (skill && data && typeof data === "object" && "id" in (data as Record<string, unknown>)) {
         skill.dbId = (data as Record<string, unknown>).id as string;
       }
+      if (skill && options?.variables) {
+        skill.variables = options.variables;
+      }
 
       log.debug(`Skill "${name}" synced to agent_skills`);
     } catch (err) {
@@ -861,10 +912,90 @@ export class SkillManager {
       return [];
     }
   }
+
+  // ── Variable Configuration ──────────────────────────────────────────
+
+  /**
+   * Update user-specific variable values (config) for a skill.
+   * Persists to agent_skills.config in DB and updates in-memory.
+   */
+  async updateConfig(
+    skillName: string,
+    config: Record<string, unknown>
+  ): Promise<boolean> {
+    const skill = this.skills.get(skillName);
+    if (!skill) return false;
+
+    // Merge with existing config
+    const merged = { ...(skill.config || {}), ...config };
+    skill.config = merged;
+
+    // Persist to DB
+    if (this.userId && skill.dbId) {
+      try {
+        const sb = getSupabase();
+        await sb
+          .from("agent_skills")
+          .update({ config: merged })
+          .eq("id", skill.dbId)
+          .eq("user_id", this.userId);
+        log.debug(`Config updated for skill "${skillName}"`);
+      } catch (err) {
+        log.debug(`Config update failed for "${skillName}": ${err}`);
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get the unresolved (unconfigured) variables for a skill.
+   * Returns variables that are required but have no value in config.
+   */
+  getUnconfiguredVariables(skillName: string): SkillVariable[] {
+    const skill = this.skills.get(skillName);
+    if (!skill?.variables) return [];
+
+    return skill.variables.filter((v) => {
+      if (!v.required) return false;
+      const value = skill.config?.[v.name];
+      return value === undefined || value === null || value === "";
+    });
+  }
 }
 
 // ── Exported Utility Functions ─────────────────────────────────────
 
+/**
+ * Substitute {{variable_name}} placeholders in skill content with user config values.
+ * Also handles array values by joining with ", ".
+ *
+ * Unresolved variables are left as-is with a note: {{variable_name: [NOT CONFIGURED]}}
+ */
+export function substituteVariables(
+  content: string,
+  config: Record<string, unknown> | undefined,
+  variables?: SkillVariable[]
+): string {
+  if (!content.includes("{{")) return content;
+
+  return content.replace(/\{\{(\w+)\}\}/g, (match, varName: string) => {
+    const value = config?.[varName];
+
+    if (value !== undefined && value !== null) {
+      if (Array.isArray(value)) return value.join(", ");
+      return String(value);
+    }
+
+    // Check for default value in variable definitions
+    const varDef = variables?.find((v) => v.name === varName);
+    if (varDef?.default !== undefined) return varDef.default;
+
+    // Leave as-is with warning for unresolved
+    return `{{${varName}: [NOT CONFIGURED]}}`;
+  });
+}
+
 /**
  * Substitute $ARGUMENTS, $ARGUMENTS[N], and $N placeholders in skill content.
  */