🤖 feat: unify include_files and <@path> context tags

Author: ammar-agent

bun.lock

@@ -57,6 +57,7 @@ Optional fields:
 - `license`
 - `compatibility`
 - `metadata` (string key/value map)
+- `include_files` (glob patterns, relative to the skill directory, for files to inline when the skill is loaded)
 
 Mux ignores unknown frontmatter keys (for example `allowed-tools`).
 
@@ -69,6 +70,8 @@ description: Build and validate a release branch.
 license: MIT
 metadata:
   owner: platform
+include_files:
+  - references/**/*.md
 ---
 
 # My Skill

docs/agent-skills.mdx

@@ -76,6 +76,11 @@ name: My Agent # Display name in UI
 
 # Optional
 description: What this agent does # Shown in tooltips
+
+# Auto-include file context (workspace-root relative globs)
+include_files:
+  - docs/**/*.md
+  - src/**/*.ts
 base: exec # Inherit from another agent (exec, plan, or custom agent id)
 
 # UI settings

docs/agents.mdx

@@ -101,6 +101,7 @@
     "ollama-ai-provider-v2": "^1.5.4",
     "openai": "^6.9.1",
     "parse-duration": "^2.1.4",
+    "picomatch": "^4.0.3",
     "posthog-node": "^5.17.0",
     "quickjs-emscripten": "^0.31.0",
     "quickjs-emscripten-core": "^0.31.0",
@@ -147,6 +148,7 @@
     "@types/katex": "^0.16.7",
     "@types/markdown-it": "^14.1.2",
     "@types/minimist": "^1.2.5",
+    "@types/picomatch": "^4.0.2",
     "@types/react": "^18.2.0",
     "@types/react-dom": "^18.2.0",
     "@types/turndown": "^5.0.6",

package.json

@@ -45,6 +45,9 @@ export {
   AgentSkillFrontmatterSchema,
   AgentSkillPackageSchema,
   AgentSkillScopeSchema,
+  IncludeFileGlobSchema,
+  IncludedFileSchema,
+  IncludeFilesContextSchema,
   SkillNameSchema,
 } from "./schemas/agentSkill";
 

src/common/orpc/schemas.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+import { IncludeFileGlobSchema } from "./agentSkill";
+
 export const AgentDefinitionScopeSchema = z.enum(["built-in", "project", "global"]);
 
 // Agent IDs come from filenames (<agentId>.md).
@@ -46,7 +48,7 @@ const AgentDefinitionAiDefaultsSchema = z
 
 const AgentDefinitionPromptSchema = z
   .object({
-    // When true, append this agent's body to the base agent's body (default: false = replace)
+    // When true, append this agent's body to the base agent's body (default: true); set false to replace.
     append: z.boolean().optional(),
   })
   .strip();
@@ -67,6 +69,12 @@ export const AgentDefinitionFrontmatterSchema = z
     name: z.string().min(1).max(128),
     description: z.string().min(1).max(1024).optional(),
 
+    /**
+     * Glob patterns for files to automatically include in context when this agent runs.
+     * Patterns are relative to the workspace root (where tools run).
+     * Example: ["docs/**", "src/**"]
+     */
+    include_files: z.array(IncludeFileGlobSchema).max(20).optional(),
     // Inheritance: reference a built-in or custom agent ID
     base: AgentIdSchema.optional(),
 

src/common/orpc/schemas/agentDefinition.ts

@@ -15,12 +15,35 @@ export const SkillNameSchema = z
   .max(64)
   .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
 
+/**
+ * Glob pattern for include_files.
+ * Patterns must be relative (no absolute paths, no ~, no ..).
+ */
+export const IncludeFileGlobSchema = z
+  .string()
+  .min(1)
+  .max(256)
+  .refine(
+    (pattern) =>
+      !pattern.startsWith("/") &&
+      !pattern.startsWith("~") &&
+      !pattern.includes("..") &&
+      !/^[A-Za-z]:[\\/]/.test(pattern),
+    { message: "Pattern must be relative (no absolute paths, ~, or ..)" }
+  );
+
 export const AgentSkillFrontmatterSchema = z.object({
   name: SkillNameSchema,
   description: z.string().min(1).max(1024),
   license: z.string().optional(),
   compatibility: z.string().min(1).max(500).optional(),
   metadata: z.record(z.string(), z.string()).optional(),
+  /**
+   * Glob patterns for files to automatically include in context when the skill is read.
+   * Patterns are relative to the skill directory (where SKILL.md lives).
+   * Example: ["examples/*.ts", "schemas/**\/*.json"]
+   */
+  include_files: z.array(IncludeFileGlobSchema).max(20).optional(),
 });
 
 export const AgentSkillDescriptorSchema = z.object({
@@ -29,12 +52,39 @@ export const AgentSkillDescriptorSchema = z.object({
   scope: AgentSkillScopeSchema,
 });
 
+/**
+ * Resolved file from include_files expansion.
+ */
+export const IncludedFileSchema = z.object({
+  /** Path relative to skill directory */
+  path: z.string(),
+  /** File content (may be truncated) */
+  content: z.string(),
+  /** Whether content was truncated due to size/line limits */
+  truncated: z.boolean(),
+});
+
+/**
+ * Context representation for files included via include_files.
+ * Rendered as XML using the `<@path>` tag format.
+ */
+export const IncludeFilesContextSchema = z.object({
+  /** Successfully resolved files */
+  files: z.array(IncludedFileSchema),
+  /** Patterns/files that had errors during resolution */
+  errors: z.array(z.object({ pattern: z.string(), error: z.string() })),
+  /** Pre-rendered XML context (for direct injection) */
+  rendered: z.string(),
+});
+
 export const AgentSkillPackageSchema = z
   .object({
     scope: AgentSkillScopeSchema,
     directoryName: SkillNameSchema,
     frontmatter: AgentSkillFrontmatterSchema,
     body: z.string(),
+    /** Resolved include_files context (present when frontmatter.include_files is set) */
+    includeFilesContext: IncludeFilesContextSchema.optional(),
   })
   .refine((value) => value.directoryName === value.frontmatter.name, {
     message: "SKILL.md frontmatter.name must match the parent directory name",

src/common/orpc/schemas/agentSkill.ts

@@ -10,6 +10,7 @@ import {
   discoverAgentDefinitions,
   readAgentDefinition,
   resolveAgentBody,
+  resolveAgentIncludeFilesPatterns,
 } from "./agentDefinitionsService";
 
 async function writeAgent(root: string, id: string, name: string): Promise<void> {
@@ -129,4 +130,68 @@ Replaced body.
     expect(replacerBody).toBe("Replaced body.\n");
     expect(replacerBody).not.toContain("Base instructions");
   });
+
+  test("resolveAgentIncludeFilesPatterns inherits by default, stops when prompt.append is false", async () => {
+    using tempDir = new DisposableTempDir("agent-include-files-patterns");
+    const agentsRoot = path.join(tempDir.path, ".mux", "agents");
+    await fs.mkdir(agentsRoot, { recursive: true });
+
+    await fs.writeFile(
+      path.join(agentsRoot, "base.md"),
+      `---
+name: Base
+include_files:
+  - "README.md"
+  - "src/*.ts"
+---
+Base instructions.
+`,
+      "utf-8"
+    );
+
+    await fs.writeFile(
+      path.join(agentsRoot, "child.md"),
+      `---
+name: Child
+base: base
+include_files:
+  - "src/*.ts"
+  - "docs/**/*.md"
+---
+Child instructions.
+`,
+      "utf-8"
+    );
+
+    await fs.writeFile(
+      path.join(agentsRoot, "replacer.md"),
+      `---
+name: Replacer
+base: base
+prompt:
+  append: false
+include_files:
+  - "only-child.txt"
+---
+Replaced body.
+`,
+      "utf-8"
+    );
+
+    const roots = { projectRoot: agentsRoot, globalRoot: agentsRoot };
+    const runtime = new LocalRuntime(tempDir.path);
+
+    const childPatterns = await resolveAgentIncludeFilesPatterns(runtime, tempDir.path, "child", {
+      roots,
+    });
+    expect(childPatterns).toEqual(["README.md", "src/*.ts", "docs/**/*.md"]);
+
+    const replacerPatterns = await resolveAgentIncludeFilesPatterns(
+      runtime,
+      tempDir.path,
+      "replacer",
+      { roots }
+    );
+    expect(replacerPatterns).toEqual(["only-child.txt"]);
+  });
 });

src/node/services/agentDefinitions/agentDefinitionsService.test.ts

@@ -412,3 +412,46 @@ export async function resolveAgentBody(
 
   return resolve(agentId, 0);
 }
+
+/**
+ * Resolve include_files patterns for an agent, including inherited patterns.
+ *
+ * Inheritance behavior mirrors resolveAgentBody:
+ * - If `prompt.append` is false, we do NOT inherit include_files from the base.
+ * - Otherwise, base patterns are prepended (base first, then child).
+ */
+export async function resolveAgentIncludeFilesPatterns(
+  runtime: Runtime,
+  workspacePath: string,
+  agentId: AgentId,
+  options?: { roots?: AgentDefinitionsRoots }
+): Promise<string[]> {
+  const visited = new Set<AgentId>();
+
+  async function resolve(id: AgentId, depth: number): Promise<string[]> {
+    checkInheritanceChain(visited, id, depth);
+
+    const pkg = await readAgentDefinition(runtime, workspacePath, id, options);
+    const baseId = pkg.frontmatter.base;
+    const shouldAppend = pkg.frontmatter.prompt?.append !== false;
+
+    const patterns = pkg.frontmatter.include_files ?? [];
+
+    if (!baseId || !shouldAppend) {
+      return patterns;
+    }
+
+    const basePatterns = await resolve(baseId, depth + 1);
+    return [...basePatterns, ...patterns];
+  }
+
+  const patterns = await resolve(agentId, 0);
+
+  // Preserve order while deduplicating.
+  const seen = new Set<string>();
+  return patterns.filter((pattern) => {
+    if (seen.has(pattern)) return false;
+    seen.add(pattern);
+    return true;
+  });
+}

src/node/services/agentDefinitions/agentDefinitionsService.ts

@@ -73,6 +73,58 @@ Body
     ).toThrow(AgentDefinitionParseError);
   });
 
+  test("parses include_files patterns", () => {
+    const content = `---
+name: With Files
+include_files:
+  - "docs/**/*.md"
+  - "src/**/*.ts"
+---
+Body
+`;
+
+    const result = parseAgentDefinitionMarkdown({
+      content,
+      byteSize: Buffer.byteLength(content, "utf-8"),
+    });
+
+    expect(result.frontmatter.include_files).toEqual(["docs/**/*.md", "src/**/*.ts"]);
+  });
+
+  test("rejects absolute paths in include_files", () => {
+    const content = `---
+name: Bad Paths
+include_files:
+  - "/etc/passwd"
+---
+Body
+`;
+
+    expect(() =>
+      parseAgentDefinitionMarkdown({
+        content,
+        byteSize: Buffer.byteLength(content, "utf-8"),
+      })
+    ).toThrow(AgentDefinitionParseError);
+  });
+
+  test("rejects path traversal in include_files", () => {
+    const content = `---
+name: Traversal
+include_files:
+  - "../secret.txt"
+---
+Body
+`;
+
+    expect(() =>
+      parseAgentDefinitionMarkdown({
+        content,
+        byteSize: Buffer.byteLength(content, "utf-8"),
+      })
+    ).toThrow(AgentDefinitionParseError);
+  });
+
   test("parses tools as add/remove patterns", () => {
     const content = `---
 name: Regex Tools