Agent Skills

agents-cli/src/commands/pull-v3/__tests__/test-introspect-cli.ts

@@ -472,6 +472,7 @@ async function main(): Promise<void> {
     credentialsDir: join(testDir, 'credentials'),
     contextConfigsDir: join(testDir, 'context-configs'),
     externalAgentsDir: join(testDir, 'external-agents'),
+    skillsDir: join(testDir, 'skills'),
   };
 
   try {

agents-cli/src/commands/pull-v3/components/mcp-tool-generator.ts

@@ -79,7 +79,7 @@ export function generateMcpToolDefinition(
   const q = quotes === 'single' ? "'" : '"';
   const semi = semicolons ? ';' : '';
 
-  const toolVarName = toCamelCase(toolId);
+  const toolVarName = registry?.getVariableName?.(toolId, 'tools') ?? toCamelCase(toolId);
   const lines: string[] = [];
 
   lines.push(`export const ${toolVarName} = mcpTool({`);

agents-cli/src/commands/pull-v3/components/project-generator.ts

@@ -75,6 +75,12 @@ export function generateProjectDefinition(
     lines.push(`${indentation}models: ${formatObject(projectData.models, style, 2)},`);
   }
 
+  if (shouldInclude(projectData.skills)) {
+    lines.push(
+      `${indentation}skills: () => loadSkills(path.join(${formatString(projectId, q)}, 'skills')),`
+    );
+  }
+
   // stopWhen configuration - project-level limits
   if (shouldInclude(projectData.stopWhen)) {
     lines.push(`${indentation}stopWhen: {`);
@@ -183,7 +189,16 @@ export function generateProjectImports(
   const imports: string[] = [];
 
   // Always import project from SDK
-  imports.push(generateImport(['project'], '@inkeep/agents-sdk', style));
+  const sdkImports = ['project'];
+  if (shouldInclude(projectData.skills)) {
+    sdkImports.push('loadSkills');
+  }
+  imports.push(generateImport(sdkImports, '@inkeep/agents-sdk', style));
+  if (shouldInclude(projectData.skills)) {
+    const q = style.quotes === 'single' ? "'" : '"';
+    const semi = style.semicolons ? ';' : '';
+    imports.push(`import path from ${q}node:path${q}${semi}`);
+  }
 
   // Generate imports for referenced components if registry is available
   if (registry) {
@@ -216,9 +231,9 @@ export function generateProjectImports(
       for (const toolId of toolIds) {
         // Determine the actual component type by checking what's in the registry
         let componentType: ComponentType = 'tools';
-        if (registry?.get(toolId, 'functionTools')) {
+        if (registry.get(toolId, 'functionTools')) {
           componentType = 'functionTools';
-        } else if (registry?.get(toolId, 'tools')) {
+        } else if (registry.get(toolId, 'tools')) {
           componentType = 'tools';
         }
 
@@ -300,5 +315,9 @@ export function generateProjectFile(
   const imports = generateProjectImports(projectData, style, registry);
   const definition = generateProjectDefinition(projectId, projectData, style, registry);
 
-  return generateFileContent(imports, [definition]);
+  const definitions: string[] = [];
+
+  definitions.push(definition);
+
+  return generateFileContent(imports, definitions);
 }

agents-cli/src/commands/pull-v3/components/skill-generator.ts

@@ -0,0 +1,44 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { stringify } from 'yaml';
+
+type SkillMap = Record<
+  string,
+  {
+    name: string;
+    description?: string | null;
+    content: string;
+    metadata?: Record<string, unknown> | null;
+  }
+>;
+
+function formatMetadata(metadata: Record<string, unknown>): string {
+  const yaml = stringify(metadata);
+  const indented = yaml
+    .split('\n')
+    .filter((line) => line.trim() !== '')
+    .map((line) => `  ${line}`)
+    .join('\n');
+  return `metadata:\n${indented}`;
+}
+
+export async function generateSkills(skills: SkillMap, skillsDir: string): Promise<void> {
+  await mkdir(skillsDir, { recursive: true });
+
+  for (const [skillId, skill] of Object.entries(skills)) {
+    const parts: string[] = ['---', `name: ${JSON.stringify(skill.name)}`];
+    parts.push(`description: ${JSON.stringify(skill.description ?? '')}`);
+
+    if (skill.metadata && Object.keys(skill.metadata).length > 0) {
+      parts.push(formatMetadata(skill.metadata));
+    }
+
+    parts.push('---', '', skill.content || '');
+
+    const skillDir = join(skillsDir, skillId);
+    await mkdir(skillDir, { recursive: true });
+
+    const filePath = join(skillDir, 'SKILL.md');
+    await writeFile(filePath, parts.join('\n'), 'utf8');
+  }
+}

agents-cli/src/commands/pull-v3/components/sub-agent-generator.ts

@@ -198,6 +198,20 @@ export function generateSubAgentDefinition(
     lines.push(`${indentation}},`);
   }
 
+  // skills - ordered skill attachments by id
+  if (agentData.skills && Array.isArray(agentData.skills) && agentData.skills.length > 0) {
+    lines.push(`${indentation}skills: () => [`);
+    for (const skill of agentData.skills) {
+      const parts = [`id: ${formatString(skill.id, q)}`];
+      parts.push(`index: ${skill.index}`);
+      if (skill.alwaysLoaded) {
+        parts.push(`alwaysLoaded: ${skill.alwaysLoaded}`);
+      }
+      lines.push(`${indentation}${indentation}{ ${parts.join(', ')} },`);
+    }
+    lines.push(`${indentation}],`);
+  }
+
   // canUse - tools that this agent can use directly (with .with() configuration if present)
   if (agentData.canUse && Array.isArray(agentData.canUse) && agentData.canUse.length > 0) {
     const toolReferences: string[] = [];

agents-cli/src/commands/pull-v3/index.ts

@@ -90,6 +90,7 @@ interface ProjectPaths {
   credentialsDir: string;
   contextConfigsDir: string;
   externalAgentsDir: string;
+  skillsDir: string;
 }
 
 /**
@@ -109,6 +110,7 @@ function createProjectStructure(projectDir: string): ProjectPaths {
     credentialsDir: join(projectRoot, 'credentials'),
     contextConfigsDir: join(projectRoot, 'context-configs'),
     externalAgentsDir: join(projectRoot, 'external-agents'),
+    skillsDir: join(projectRoot, 'skills'),
   };
 
   // Ensure all directories exist
@@ -447,6 +449,11 @@ export async function pullV3Command(options: PullV3Options): Promise<PullResult
     // Step 5: Set up project structure
     const paths = createProjectStructure(projectDir);
 
+    if (remoteProject.skills && Object.keys(remoteProject.skills).length) {
+      const { generateSkills } = await import('./components/skill-generator');
+      await generateSkills(remoteProject.skills, paths.skillsDir);
+    }
+
     // Step 6: Introspect mode - skip comparison, regenerate everything
     if (options.introspect) {
       console.log(chalk.yellow('\n🔍 Introspect mode: Regenerating all files from scratch'));

agents-cli/src/commands/pull-v3/introspect-generator.ts

@@ -39,6 +39,7 @@ interface ProjectPaths {
   credentialsDir: string;
   contextConfigsDir: string;
   externalAgentsDir: string;
+  skillsDir: string;
 }
 
 interface IntrospectOptions {

agents-cli/src/commands/pull-v3/new-component-generator.ts

@@ -34,6 +34,7 @@ interface ProjectPaths {
   credentialsDir: string;
   contextConfigsDir: string;
   externalAgentsDir: string;
+  skillsDir: string;
 }
 
 interface NewComponentResult {
@@ -199,6 +200,7 @@ export async function createNewComponents(
         credentialsDir: join(paths.projectRoot, tempDirName, 'credentials'),
         contextConfigsDir: join(paths.projectRoot, tempDirName, 'context-configs'),
         externalAgentsDir: join(paths.projectRoot, tempDirName, 'external-agents'),
+        skillsDir: join(paths.projectRoot, tempDirName, 'skills'),
       }
     : paths;
 

agents-cli/src/commands/pull-v3/utils/component-registry.ts

@@ -25,7 +25,8 @@ export type ComponentType =
   | 'fetchDefinitions'
   | 'headers'
   | 'models'
-  | 'project';
+  | 'project'
+  | 'skills';
 
 export interface ComponentInfo {
   id: string; // Original component ID
@@ -577,6 +578,13 @@ export function registerAllComponents(
     }
   }
 
+  // Register skills
+  if (project.skills) {
+    for (const skillId of Object.keys(project.skills)) {
+      registry.register(skillId, 'skills', `skills/${skillId}.md`);
+    }
+  }
+
   // Register extracted status components
   const statusComponents = extractStatusComponents(project);
   for (const statusId of Object.keys(statusComponents)) {

agents-cookbook/template-projects/activities-planner-advanced/agents/activities-planner-advanced.ts

@@ -122,6 +122,10 @@ const activitiesPlanner = subAgent({
   )} in the timezone ${headersSchema.toTemplate(
     'tz'
   )}. When the user asks about activities in a given location, first ask the coordinates agent for the coordinates, and then pass those coordinates to the weather forecast agent to get the weather forecast. Then based on the weather forecast, ask the websearch MCP tool to search the web for good activities given the weather. Once you have the activities, use the calculate-activity-score tool to calculate a score for one of the activities based on the weather conditions- and then show the user the activity score in your response. When you receive web search results, create citation artifacts to document your sources.`,
+  skills: () => [
+    { id: 'weather-safety', index: 0 },
+    { id: 'formatting-itinerary-structure', index: 1 },
+  ],
   canDelegateTo: () => [weatherForecaster, coordinatesAgent],
   canUse: () => [calculateActivityScore, exaMcpTool.with({ selectedTools: ['web_search_exa'] })],
   dataComponents: () => [activities],

agents-cookbook/template-projects/activities-planner-advanced/index.ts

@@ -1,15 +1,23 @@
-import { project } from '@inkeep/agents-sdk';
-import { activitiesPlannerAdvancedAgent } from './agents/activities-planner-advanced.js';
-import { exaMcpTool } from './tools/exa-mcp.js';
-import { weatherMcpTool } from './tools/weather-mcp.js';
+import path from 'node:path';
+import { loadSkills, project } from '@inkeep/agents-sdk';
+import { activitiesPlannerAdvancedAgent } from './agents/activities-planner-advanced';
+import { citation } from './artifact-components/citation';
+import { activities } from './data-components/activities';
+import { exaMcpTool } from './tools/exa-mcp';
+import { weatherMcpTool } from './tools/weather-mcp';
 
-export const myProject = project({
+export const activitiesPlannerAdvanced = project({
   id: 'activities-planner-advanced',
   name: 'Activities planner advanced',
   description: 'Activities planner project template',
   agents: () => [activitiesPlannerAdvancedAgent],
-  tools: () => [weatherMcpTool, exaMcpTool],
+  skills: () => loadSkills(path.join('activities-planner-advanced/skills')),
   models: {
-    base: { model: 'openai/gpt-4o-mini' },
+    base: {
+      model: 'openai/gpt-4o-mini',
+    },
   },
+  tools: () => [weatherMcpTool, exaMcpTool],
+  dataComponents: () => [activities],
+  artifactComponents: () => [citation],
 });

agents-cookbook/template-projects/activities-planner-advanced/skills/structured-itinerary-responses/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: structured-itinerary-responses
+description: Present time-aware itineraries with clear actions and citations
+metadata:
+  author: example-org
+  version: "1.0"
+---
+
+- Start with a one-sentence summary tailored to the user’s location and weather window.
+- Provide 3–5 time-blocked suggestions with clear actions, durations, and required items; highlight indoor pivots when weather shifts.
+- End with a concise checklist plus source/citation references when web results influence recommendations.

agents-cookbook/template-projects/activities-planner-advanced/skills/weather-safety-guardrails/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: weather-safety-guardrails
+description: "Keep activity suggestions safe and respect local conditions"
+metadata:
+  author: example-org
+  version: "1.0"
+---
+
+- Avoid outdoor or risky activities when storms, extreme temperatures, or hazardous air quality are present.
+- Offer indoor or low-exposure alternatives when precipitation probability exceeds 40% or heat index is above 32°C/90°F.
+- Remind users to check local advisories and venue constraints (permits, hours, accessibility) before committing.

agents-docs/content/deployment/vercel.mdx

@@ -22,7 +22,7 @@ Create a Doltgres database at [**DoltHub**](https://hosted.doltdb.com).
 
 Set your database connection string as an environment variable:
 
-```
+```dotenv
 # Doltgres Database
 INKEEP_AGENTS_MANAGE_DATABASE_URL=
 # Postgres Database

agents-docs/content/visual-builder/meta.json

@@ -1,3 +1,11 @@
 {
-  "pages": ["sub-agents", "tools", "headers", "structured-outputs", "context-fetchers", "..."]
+  "pages": [
+    "sub-agents",
+    "tools",
+    "headers",
+    "structured-outputs",
+    "context-fetchers",
+    "skills",
+    "..."
+  ]
 }

agents-docs/content/visual-builder/skills.mdx

@@ -0,0 +1,35 @@
+---
+title: Skills
+description: Reusable instruction blocks you can attach to sub-agents
+icon: LuHexagon
+keywords: skills, prompts, instructions, reuse, sub-agents
+---
+
+## Overview
+
+Skills are reusable instruction blocks that you can attach to multiple sub-agents. They help you keep shared rules,
+tone, and formatting consistent across the agent graph while still allowing each sub-agent to focus on its own role.
+
+## Create a skill
+
+1. Go to **Skills** in the left sidebar.
+2. Click **Create skill**.
+3. Fill in the required fields and save.
+
+## Fields
+
+- [**Name**](https://agentskills.io/specification#name-field): A short identifier.
+- [**Description**](https://agentskills.io/specification#description-field): When to use this skill.
+- [**Content**](https://agentskills.io/specification#body-content): The Markdown body, write whatever helps agents perform the task effectively.
+- [**Metadata (JSON)**](https://agentskills.io/specification#metadata-field): Additional properties not defined by [the Agent Skills spec](https://agentskills.io/home).
+
+## Attach skills to sub-agents
+
+Open an agent in the Visual Builder, select a sub-agent node, and use the **Skills** picker to attach one or more
+skills. You can drag to reorder them and control their priority.
+
+Use **Always loaded** to include a skill in every prompt. It's off by default so skills load on demand unless you
+enable it.
+
+On-demand skills appear as an outline in the system prompt and can be loaded when needed via the built-in
+`load_skill` tool.