@aigne/core 1.72.0-beta.2 → 1.72.0-beta.4

package/lib/esm/loader/schema.d.ts

@@ -1,4 +1,6 @@
 import { type ZodType, z } from "zod";
+import { type Role } from "../agents/chat-model.js";
+import { PromptBuilder } from "../prompt/prompt-builder.js";
 export declare const inputOutputSchema: ({ path }: {
     path: string;
 }) => z.ZodUnion<[ZodType<any, z.ZodTypeDef, any>, z.ZodEffects<z.ZodObject<{
@@ -55,9 +57,9 @@ declare const chatModelObjectSchema: z.ZodObject<{
     } | undefined, z.ZodTypeDef, number | {
         $get: string;
     } | undefined>;
-    thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+    thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
-    } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+    } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
     } | undefined>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
@@ -86,9 +88,9 @@ declare const chatModelObjectSchema: z.ZodObject<{
     } | undefined, z.ZodTypeDef, number | {
         $get: string;
     } | undefined>;
-    thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+    thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
-    } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+    } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
     } | undefined>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
@@ -117,9 +119,9 @@ declare const chatModelObjectSchema: z.ZodObject<{
     } | undefined, z.ZodTypeDef, number | {
         $get: string;
     } | undefined>;
-    thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+    thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
-    } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+    } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
     } | undefined>;
 }, z.ZodTypeAny, "passthrough">>;
@@ -149,4 +151,17 @@ export declare function camelizeSchema<T extends ZodType>(schema: T, { shallow }
     shallow?: boolean;
 }): T;
 export declare function preprocessSchema<T extends ZodType>(fn: (data: unknown) => unknown, schema: T): T;
+export type Instructions = {
+    role: Exclude<Role, "tool">;
+    content: string;
+    path: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h";
+    };
+}[];
+export declare const getInstructionsSchema: ({ filepath }: {
+    filepath: string;
+}) => ZodType<Instructions>;
+export declare function instructionsToPromptBuilder(instructions: Instructions | string): PromptBuilder;
 export {};

package/lib/esm/loader/schema.js

@@ -2,6 +2,9 @@ import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import { parse } from "yaml";
 import { z } from "zod";
 import { getterSchema } from "../agents/agent.js";
+import { roleSchema } from "../agents/chat-model.js";
+import { PromptBuilder } from "../prompt/prompt-builder.js";
+import { ChatMessagesTemplate, parseChatMessages } from "../prompt/template.js";
 import { camelize } from "../utils/camelize.js";
 import { isRecord } from "../utils/type-utils.js";
 export const inputOutputSchema = ({ path }) => {
@@ -94,3 +97,57 @@ export function camelizeSchema(schema, { shallow = true } = {}) {
 export function preprocessSchema(fn, schema) {
     return z.preprocess(fn, schema);
 }
+const instructionItemSchema = camelizeSchema(z.union([
+    z.object({
+        role: roleSchema.default("system"),
+        url: z.string(),
+        cacheControl: optionalize(z.object({
+            type: z.literal("ephemeral"),
+            ttl: optionalize(z.union([z.literal("5m"), z.literal("1h")])),
+        })),
+    }),
+    z.object({
+        role: roleSchema.default("system"),
+        content: z.string(),
+        cacheControl: optionalize(z.object({
+            type: z.literal("ephemeral"),
+            ttl: optionalize(z.union([z.literal("5m"), z.literal("1h")])),
+        })),
+    }),
+]));
+const parseInstructionItem = ({ filepath }) => async ({ role, cacheControl, ...v }) => {
+    if (role === "tool")
+        throw new Error(`'tool' role is not allowed in instruction item in agent file ${filepath}`);
+    if ("content" in v && typeof v.content === "string") {
+        return { role, content: v.content, path: filepath, cacheControl };
+    }
+    if ("url" in v && typeof v.url === "string") {
+        const url = nodejs.path.isAbsolute(v.url)
+            ? v.url
+            : nodejs.path.join(nodejs.path.dirname(filepath), v.url);
+        return nodejs.fs
+            .readFile(url, "utf8")
+            .then((content) => ({ role, content, path: url, cacheControl }));
+    }
+    throw new Error(`Invalid instruction item in agent file ${filepath}. Expected 'content' or 'url' property`);
+};
+export const getInstructionsSchema = ({ filepath }) => z
+    .union([z.string(), instructionItemSchema, z.array(instructionItemSchema)])
+    .transform(async (v) => {
+    if (typeof v === "string")
+        return [{ role: "system", content: v, path: filepath }];
+    if (Array.isArray(v)) {
+        return Promise.all(v.map((item) => parseInstructionItem({ filepath })(item)));
+    }
+    return [await parseInstructionItem({ filepath })(v)];
+});
+export function instructionsToPromptBuilder(instructions) {
+    return new PromptBuilder({
+        instructions: typeof instructions === "string"
+            ? instructions
+            : ChatMessagesTemplate.from(parseChatMessages(instructions.map((i) => ({
+                ...i,
+                options: { workingDir: nodejs.path.dirname(i.path) },
+            })))),
+    });
+}

package/lib/esm/prompt/prompt-builder.js

@@ -10,7 +10,7 @@ import { optionalize } from "../loader/schema.js";
 import { outputSchemaToResponseFormatSchema } from "../utils/json-schema.js";
 import { checkArguments, flat, isNonNullable, isRecord, partition, unique, } from "../utils/type-utils.js";
 import { createPromptBuilderContext } from "./context/index.js";
-import { AFS_EXECUTABLE_TOOLS_PROMPT_TEMPLATE, getAFSSystemPrompt, } from "./prompts/afs-builtin-prompt.js";
+import { AFS_EXECUTABLE_TOOLS_PROMPT_TEMPLATE } from "./prompts/afs-builtin-prompt.js";
 import { MEMORY_MESSAGE_TEMPLATE } from "./prompts/memory-message-template.js";
 import { STRUCTURED_STREAM_INSTRUCTIONS } from "./prompts/structured-stream-instructions.js";
 import { getAFSSkills } from "./skills/afs/index.js";
@@ -116,7 +116,6 @@ export class PromptBuilder {
         const afs = options.agent?.afs;
         if (afs && options.agent?.historyConfig?.disabled !== true) {
             const historyModule = (await afs.listModules()).find((m) => m.module instanceof AFSHistory);
-            messages.push(await SystemMessageTemplate.from(await getAFSSystemPrompt(afs)).format({}));
             if (historyModule) {
                 const history = await afs.list(historyModule.path, {
                     limit: options.agent?.maxRetrieveMemoryCount || 10,

package/lib/esm/prompt/skills/afs/agent-skill/agent-skill.d.ts

@@ -0,0 +1,17 @@
+import { Agent, type AgentOptions, type Message } from "../../../../agents/agent.js";
+import type { Skill } from "./skill-loader.js";
+export interface SkillToolInput extends Message {
+    skill: string;
+    args?: string;
+}
+export interface SkillToolOutput extends Message {
+    result: string;
+}
+export interface SkillToolOptions extends AgentOptions<SkillToolInput, SkillToolOutput> {
+    agentSkills: Skill[];
+}
+export declare class AgentSkill extends Agent<SkillToolInput, SkillToolOutput> {
+    constructor(options: SkillToolOptions);
+    private agentSkills;
+    process(input: SkillToolInput): Promise<SkillToolOutput>;
+}

package/lib/esm/prompt/skills/afs/agent-skill/agent-skill.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { Agent } from "../../../../agents/agent.js";
+const skillToolInputSchema = z.object({
+    skill: z.string().describe("The name of the skill agent to invoke."),
+    args: z.string().optional().describe("The arguments to pass to the skill."),
+});
+export class AgentSkill extends Agent {
+    constructor(options) {
+        super({
+            name: "Skill",
+            taskTitle: "Invoke {{skill}}: {{args}}",
+            ...options,
+            description: `\
+Execute a skill within the main conversation
+
+<skills_instructions>
+When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.
+
+When users ask you to run a "slash command" or reference "/" (e.g., "/commit", "/review-pr"), they are referring to a skill. Use this tool to invoke the corresponding skill.
+
+User: "run /commit" Assistant: [Calls Skill tool with skill: "commit"]
+How to invoke:
+
+Use this tool with the skill name and optional arguments
+
+Important:
+
+When a skill is relevant, you must invoke this tool IMMEDIATELY as your first action
+NEVER just announce or mention a skill in your text response without actually calling this tool
+This is a BLOCKING REQUIREMENT: invoke the relevant Skill tool BEFORE generating any other response about the task
+Only use skills listed in <available_skills> below
+Do not invoke a skill that is already running
+Do not use this tool for built-in CLI commands (like /help, /clear, etc.)
+</skills_instructions>
+
+<available_skills>
+${options.agentSkills.map((s) => `${s.name}: ${s.description}`).join("\n\n")}
+</available_skills>
+`,
+            inputSchema: skillToolInputSchema,
+        });
+        this.agentSkills = options.agentSkills;
+    }
+    agentSkills;
+    async process(input) {
+        const skill = this.agentSkills.find((s) => s.name === input.skill);
+        if (!skill)
+            throw new Error(`Skill not found: ${input.skill}`);
+        return {
+            result: `\
+Base directory for this skill: ${skill.path}
+
+${skill.content}
+
+${input.args ? `ARGUMENTS: ${input.args ?? "None"}` : ""}
+`,
+        };
+    }
+}

package/lib/esm/prompt/skills/afs/agent-skill/skill-loader.d.ts

@@ -0,0 +1,13 @@
+import type { AFS } from "@aigne/afs";
+import { AgentSkill } from "./agent-skill.js";
+export interface Skill {
+    path: string;
+    name: string;
+    description: string;
+    content: string;
+}
+export declare function loadSkill(path: string): Promise<Skill>;
+export declare function loadSkills(paths: string[]): Promise<Skill[]>;
+export declare function loadAgentSkillFromAFS({ afs, }: {
+    afs: AFS;
+}): Promise<AgentSkill | undefined>;

package/lib/esm/prompt/skills/afs/agent-skill/skill-loader.js

@@ -0,0 +1,53 @@
+import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
+import fm from "front-matter";
+import { AgentSkill } from "./agent-skill.js";
+function parseSkill(content, path) {
+    const meta = fm(content);
+    return {
+        path,
+        name: meta.attributes.name,
+        description: meta.attributes.description,
+        content: meta.body,
+    };
+}
+export async function loadSkill(path) {
+    const entry = nodejs.path.join(path, "SKILL.md");
+    const skill = await nodejs.fs.readFile(entry, "utf-8");
+    return parseSkill(skill, path);
+}
+export async function loadSkills(paths) {
+    const skills = [];
+    for (const path of paths) {
+        const skill = await loadSkill(path);
+        skills.push(skill);
+    }
+    return skills;
+}
+export async function loadAgentSkillFromAFS({ afs, }) {
+    const modules = await afs.listModules();
+    const filtered = modules.filter(({ module: m }) => "options" in m &&
+        typeof m.options === "object" &&
+        m.options &&
+        "agentSkills" in m.options &&
+        m.options.agentSkills === true);
+    if (!filtered.length)
+        return;
+    const skills = [];
+    for (const module of filtered) {
+        const data = (await afs.list(module.path, {
+            pattern: "**/SKILL.md",
+        })).data;
+        for (const entry of data) {
+            const { data: file } = await afs.read(entry.path);
+            if (typeof file?.content !== "string")
+                continue;
+            const skill = parseSkill(file.content, nodejs.path.dirname(entry.path));
+            skills.push(skill);
+        }
+    }
+    if (!skills.length)
+        return;
+    return new AgentSkill({
+        agentSkills: skills,
+    });
+}

package/lib/esm/prompt/skills/afs/delete.js

@@ -4,15 +4,27 @@ export class AFSDeleteAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_delete",
-            description: "Permanently delete files or directories. Use when removing unwanted files or cleaning up temporary data.",
+            description: `Permanently delete files or directories from the Agentic File System (AFS)
+- Removes files or directories at the specified AFS path
+- Supports recursive deletion for directories with contents
+- Use with caution as deletion is permanent
+
+Usage:
+- The path must be an absolute AFS path starting with "/" (e.g., "/docs/old-file.md", "/temp")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- To delete a directory, you MUST set recursive=true
+- Deleting a non-empty directory without recursive=true will fail
+- This operation cannot be undone`,
             ...options,
             inputSchema: z.object({
-                path: z.string().describe("Absolute file or directory path to delete"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path to delete (e.g., '/docs/old-file.md', '/temp'). Must start with '/'"),
                 recursive: z
                     .boolean()
                     .optional()
                     .default(false)
-                    .describe("Allow directory deletion (default: false, required for directories)"),
+                    .describe("MUST be set to true to delete directories. Default: false (files only)"),
             }),
             outputSchema: z.object({
                 status: z.string(),

package/lib/esm/prompt/skills/afs/edit.js

@@ -4,19 +4,42 @@ export class AFSEditAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_edit",
-            description: "Apply precise line-based patches to modify file content. Use when making targeted changes without rewriting the entire file.",
+            description: `Apply precise line-based patches to modify files in the Agentic File System (AFS)
+- Performs targeted edits using line numbers without rewriting the entire file
+- Supports both replacing and deleting line ranges
+- Multiple patches can be applied in a single operation
+
+Usage:
+- The path must be an absolute AFS path starting with "/" (e.g., "/docs/readme.md")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- IMPORTANT: You MUST use afs_read with withLineNumbers=true before editing to get accurate line numbers
+- Line numbers are 0-based: first line is 0, second line is 1, etc.
+- The range [start_line, end_line) is exclusive on end_line`,
             ...options,
             inputSchema: z.object({
-                path: z.string().describe("Absolute file path to edit"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path to the file to edit (e.g., '/docs/readme.md'). Must start with '/'"),
                 patches: z
                     .array(z.object({
-                    start_line: z.number().int().describe("Start line number (0-based, inclusive)"),
-                    end_line: z.number().int().describe("End line number (0-based, exclusive)"),
-                    replace: z.string().optional().describe("New content to replace the line range"),
-                    delete: z.boolean().describe("Delete mode: true to delete lines, false to replace"),
+                    start_line: z
+                        .number()
+                        .int()
+                        .describe("Start line number (0-based, inclusive). First line is 0"),
+                    end_line: z
+                        .number()
+                        .int()
+                        .describe("End line number (0-based, exclusive). To edit line 5 only, use start_line=5, end_line=6"),
+                    replace: z
+                        .string()
+                        .optional()
+                        .describe("New content to insert. Omit when delete=true"),
+                    delete: z
+                        .boolean()
+                        .describe("Set to true to delete the line range. Set to false to replace with 'replace' content"),
                 }))
                     .min(1)
-                    .describe("List of patches to apply sequentially"),
+                    .describe("Array of patches to apply. Each patch specifies a line range and the operation (delete or replace)"),
             }),
             outputSchema: z.object({
                 status: z.string(),

package/lib/esm/prompt/skills/afs/exec.js

@@ -4,14 +4,25 @@ export class AFSExecAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_exec",
-            description: `
-Execute files marked as executable in the Agentic File System (AFS).
-Use this to run executable files registered at a given path with specified arguments.
-      `.trim(),
+            description: `Execute files marked as executable in the Agentic File System (AFS)
+- Runs executable entries (functions, agents, skills) registered at a given AFS path
+- Passes arguments to the executable and returns its output
+- Use this to invoke dynamic functionality stored in AFS
+
+Usage:
+- The path must be an absolute AFS path to an executable entry (e.g., "/skills/summarize", "/agents/translator")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- Use afs_list to discover available executables (look for entries with execute metadata)
+- Arguments must be a valid JSON string matching the executable's input schema
+- The executable's input/output schema can be found in its metadata`,
             ...options,
             inputSchema: z.object({
-                path: z.string().describe("Absolute path to the executable file in AFS"),
-                args: z.string().describe("JSON string of arguments matching the function's input schema"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path to the executable (e.g., '/skills/summarize'). Must start with '/'"),
+                args: z
+                    .string()
+                    .describe('JSON string of arguments matching the executable\'s input schema (e.g., \'{"text": "hello"}\')'),
             }),
             outputSchema: z.object({
                 data: z.record(z.any()),

package/lib/esm/prompt/skills/afs/index.js

@@ -1,3 +1,5 @@
+import { isNonNullable } from "../../../utils/type-utils.js";
+import { loadAgentSkillFromAFS } from "./agent-skill/skill-loader.js";
 import { AFSDeleteAgent } from "./delete.js";
 import { AFSEditAgent } from "./edit.js";
 import { AFSExecAgent } from "./exec.js";
@@ -16,5 +18,6 @@ export async function getAFSSkills(afs) {
         new AFSDeleteAgent({ afs }),
         new AFSRenameAgent({ afs }),
         new AFSExecAgent({ afs }),
-    ];
+        await loadAgentSkillFromAFS({ afs }),
+    ].filter(isNonNullable);
 }

package/lib/esm/prompt/skills/afs/list.js

@@ -4,26 +4,42 @@ export class AFSListAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_list",
-            description: "Browse directory structure as a tree view. Use when exploring directory contents or understanding file organization.",
+            description: `List contents within the Agentic File System (AFS)
+- Returns files and directories at the specified AFS path
+- Supports recursive listing with configurable depth
+- Supports glob pattern filtering to match specific files
+- By default respects .gitignore rules to filter out ignored files
+- Use this tool when you need to explore AFS contents or understand file organization
+
+Usage:
+- The path must be an absolute AFS path starting with "/" (e.g., "/", "/docs", "/memory/user")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- Use maxDepth to control recursion depth (default: 1, current directory only)
+- Use pattern to filter entries by glob pattern:
+  - "*.ts" - match TypeScript files in current directory
+  - "**/*.js" - match all JavaScript files recursively
+  - "src/**/*.{ts,tsx}" - match TypeScript files in src directory
+- Results are filtered by .gitignore by default; set disableGitignore to include ignored files`,
             ...options,
             inputSchema: z.object({
-                path: z.string().describe("Absolute directory path to browse"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path to list (e.g., '/', '/docs', '/memory/user'). Must start with '/'"),
                 options: z
                     .object({
-                    maxDepth: z.number().optional().describe("Tree depth limit (default: 1)"),
+                    maxDepth: z
+                        .number()
+                        .optional()
+                        .describe("Maximum depth of directory recursion. 1 = current directory only, 2 = include subdirectories, etc. Default: 1"),
                     disableGitignore: z
                         .boolean()
                         .optional()
-                        .describe("Disable .gitignore filtering, default is enabled"),
+                        .describe("Set to true to include files normally ignored by .gitignore rules. Default: false (respects .gitignore)"),
                     maxChildren: z
                         .number()
                         .optional()
-                        .describe("Maximum number of children to list per directory"),
-                    format: z
-                        .union([z.literal("simple-list"), z.literal("tree")])
-                        .optional()
-                        .default("simple-list")
-                        .describe("Output format, either 'simple-list', or 'tree', default is 'simple-list'"),
+                        .describe("Maximum number of entries to return per directory. Useful for large directories to avoid overwhelming output"),
+                    pattern: z.string().optional().describe("Glob pattern to filter entries by path"),
                 })
                     .optional(),
             }),

package/lib/esm/prompt/skills/afs/read.js

@@ -4,14 +4,25 @@ export class AFSReadAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_read",
-            description: "Read complete file contents. Use when you need to review, analyze, or understand file content before making changes.",
+            description: `Read file contents from the Agentic File System (AFS)
+- Returns the complete content of a file at the specified AFS path
+- Supports line numbers output for precise editing references
+- Use this tool when you need to review, analyze, or understand file content
+
+Usage:
+- The path must be an absolute AFS path starting with "/" (e.g., "/docs/readme.md", "/memory/user/notes")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- IMPORTANT: You MUST set withLineNumbers to true before using afs_edit, as line numbers are required for precise edits
+- Returns the file's content along with metadata (id, path, timestamps, etc.)`,
             ...options,
             inputSchema: z.object({
-                path: z.string().describe("Absolute file path to read"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path to the file to read (e.g., '/docs/readme.md'). Must start with '/'"),
                 withLineNumbers: z
                     .boolean()
                     .optional()
-                    .describe("Include line numbers in output (required when planning to edit the file)"),
+                    .describe("MUST be set to true before using afs_edit. Adds line numbers to output (format: '1| line content')"),
             }),
             outputSchema: z.object({
                 status: z.string(),

package/lib/esm/prompt/skills/afs/rename.js

@@ -4,16 +4,30 @@ export class AFSRenameAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_rename",
-            description: "Rename or move files and directories. Use when reorganizing files, changing names, or moving to different locations.",
+            description: `Rename or move files and directories within the Agentic File System (AFS)
+- Renames a file or directory to a new name
+- Can also move files/directories to a different location
+- Optionally overwrites existing files at the destination
+
+Usage:
+- Both paths must be absolute AFS paths starting with "/" (e.g., "/docs/old-name.md" -> "/docs/new-name.md")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- To move a file, specify a different directory in newPath (e.g., "/docs/file.md" -> "/archive/file.md")
+- If newPath already exists, the operation will fail unless overwrite=true
+- Moving directories moves all contents recursively`,
             ...options,
             inputSchema: z.object({
-                oldPath: z.string().describe("Absolute current file or directory path"),
-                newPath: z.string().describe("Absolute new file or directory path"),
+                oldPath: z
+                    .string()
+                    .describe("Current absolute AFS path (e.g., '/docs/old-name.md'). Must start with '/'"),
+                newPath: z
+                    .string()
+                    .describe("New absolute AFS path (e.g., '/docs/new-name.md'). Must start with '/'"),
                 overwrite: z
                     .boolean()
                     .optional()
                     .default(false)
-                    .describe("Overwrite if destination exists (default: false)"),
+                    .describe("Set to true to overwrite if destination already exists. Default: false (fails if exists)"),
             }),
             outputSchema: z.object({
                 status: z.string(),

package/lib/esm/prompt/skills/afs/search.js

@@ -4,18 +4,34 @@ export class AFSSearchAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_search",
-            description: "Search file contents by keywords. Use when finding files containing specific text or code patterns.",
+            description: `Search file contents within the Agentic File System (AFS)
+- Searches for files containing specific text, keywords, or patterns
+- Returns matching entries with their content and metadata
+- Supports case-sensitive and case-insensitive search modes
+- Use this tool when you need to find files by their content
+
+Usage:
+- The path must be an absolute AFS path starting with "/" (e.g., "/", "/docs", "/memory")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- The query can be keywords, phrases, or text patterns to search for
+- Use limit to control the number of results returned
+- Search is case-insensitive by default; set caseSensitive to true for exact case matching`,
             ...options,
             inputSchema: z.object({
-                path: z.string().describe("Absolute directory path to search in"),
-                query: z.string().describe("Search keywords or patterns"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path to search in (e.g., '/', '/docs', '/memory'). Must start with '/'"),
+                query: z.string().describe("Text, keywords, or patterns to search for in file contents"),
                 options: z
                     .object({
-                    limit: z.number().optional().describe("Max results to return"),
+                    limit: z
+                        .number()
+                        .optional()
+                        .describe("Maximum number of results to return. Useful for limiting output size"),
                     caseSensitive: z
                         .boolean()
                         .optional()
-                        .describe("Case-sensitive search (default: false)"),
+                        .describe("Set to true for case-sensitive matching. Default: false (case-insensitive)"),
                 })
                     .optional(),
             }),

package/lib/esm/prompt/skills/afs/write.js

@@ -4,16 +4,30 @@ export class AFSWriteAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_write",
-            description: "Create new file or append content to existing file. Use when creating files, rewriting entire files, or appending to files.",
+            description: `Write or create files in the Agentic File System (AFS)
+- Creates a new file or overwrites an existing file with the provided content
+- Supports append mode to add content to the end of existing files
+- Use this tool when creating new files or completely replacing file contents
+
+Usage:
+- The path must be an absolute AFS path starting with "/" (e.g., "/docs/new-file.md", "/memory/user/notes")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- By default, this tool overwrites the entire file content
+- Use append mode to add content to the end of an existing file without replacing it
+- For partial edits to existing files, prefer using afs_edit instead`,
             ...options,
             inputSchema: z.object({
-                path: z.string().describe("Absolute file path to write"),
-                content: z.string().describe("Complete file content or content to append"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path for the file to write (e.g., '/docs/new-file.md'). Must start with '/'"),
+                content: z
+                    .string()
+                    .describe("The content to write to the file. In overwrite mode, this replaces the entire file"),
                 append: z
                     .boolean()
                     .optional()
                     .default(false)
-                    .describe("Append mode: add content to end of file (default: false, overwrites file)"),
+                    .describe("Set to true to append content to the end of an existing file. Default: false (overwrites entire file)"),
             }),
             outputSchema: z.object({
                 status: z.string(),