@denizokcu/haze 0.0.1 → 0.0.2

package/dist/llm/hazeTools.js

@@ -40,6 +40,91 @@ function truncate(text, maxChars = MAX_OUTPUT_CHARS) {
 function numberLines(lines, startLine) {
     return lines.map((line, index) => `${String(startLine + index).padStart(4, ' ')} | ${line}`).join('\n');
 }
+function toolCallKey(toolName, input) {
+    return `${toolName}:${JSON.stringify(input)}`;
+}
+function hazeContext(context) {
+    return typeof context.experimental_context === 'object' && context.experimental_context != null
+        ? context.experimental_context
+        : undefined;
+}
+function isMutatingTool(toolName) {
+    return ['editFile', 'replaceLines', 'writeFile'].includes(toolName);
+}
+function isReadOnlyFileTool(toolName) {
+    return ['listFiles', 'readFile'].includes(toolName);
+}
+function inputPath(input) {
+    return typeof input === 'object' && input != null && 'path' in input && typeof input.path === 'string'
+        ? input.path
+        : undefined;
+}
+async function runDedupedTool(toolName, input, context, execute) {
+    const ctx = hazeContext(context);
+    if (!ctx)
+        return execute();
+    ctx.inFlightToolCalls ??= new Map();
+    ctx.completedToolCalls ??= new Map();
+    ctx.failedMutationPaths ??= new Set();
+    ctx.pathsReadAfterFailedMutation ??= new Set();
+    ctx.mutationEpoch ??= 0;
+    const key = toolCallKey(toolName, input);
+    const pathForInput = inputPath(input);
+    if (isMutatingTool(toolName) && pathForInput && ctx.failedMutationPaths.has(pathForInput) && !ctx.pathsReadAfterFailedMutation.has(pathForInput)) {
+        throw new Error(`Read ${pathForInput} before attempting another edit after the previous edit failure.`);
+    }
+    const completedAt = ctx.completedToolCalls.get(key);
+    const readAfterFailedMutation = toolName === 'readFile' && pathForInput && ctx.failedMutationPaths.has(pathForInput) && !ctx.pathsReadAfterFailedMutation.has(pathForInput);
+    if ((isReadOnlyFileTool(toolName) || toolName === 'bash') && completedAt === ctx.mutationEpoch && !readAfterFailedMutation) {
+        return {
+            ok: true,
+            duplicateSkipped: true,
+            toolName,
+            reason: toolName === 'bash'
+                ? 'Skipped duplicate bash command; no files changed since the previous run.'
+                : 'Skipped duplicate read-only tool call with identical input; no files changed since the previous call.',
+        };
+    }
+    if (ctx.inFlightToolCalls.has(key)) {
+        return {
+            ok: true,
+            duplicateSkipped: true,
+            toolName,
+            reason: 'Skipped duplicate in-flight tool call with identical input.',
+        };
+    }
+    const promise = execute();
+    ctx.inFlightToolCalls.set(key, promise);
+    try {
+        const result = await promise;
+        if (toolName === 'readFile' && pathForInput)
+            ctx.pathsReadAfterFailedMutation.add(pathForInput);
+        if (isMutatingTool(toolName)) {
+            ctx.mutationEpoch += 1;
+            if (pathForInput) {
+                ctx.failedMutationPaths.delete(pathForInput);
+                ctx.pathsReadAfterFailedMutation.delete(pathForInput);
+            }
+        }
+        ctx.completedToolCalls.set(key, ctx.mutationEpoch);
+        return result;
+    }
+    catch (error) {
+        if (isMutatingTool(toolName) && pathForInput) {
+            ctx.failedMutationPaths.add(pathForInput);
+            ctx.pathsReadAfterFailedMutation.delete(pathForInput);
+        }
+        throw error;
+    }
+    finally {
+        ctx.inFlightToolCalls.delete(key);
+    }
+}
+function looksLikeShellFileMutation(command) {
+    return /(^|[;&|]\s*)(sed\s+-i|perl\s+-pi|tee\b|chmod\b|mv\b|cp\b|rm\b|mkdir\b|touch\b)/.test(command)
+        || /(^|\s)(>|>>)(\s|\S)/.test(command)
+        || /\b(File\.write|writeFileSync|writeFile|appendFileSync|appendFile)\b/.test(command);
+}
 export const hazeTools = {
     listFiles: tool({
         description: 'List files and directories in the current workspace. Prefer this over bash ls/find for discovering project structure.',
@@ -47,21 +132,24 @@ export const hazeTools = {
             path: z.string().default('.').describe('Directory path relative to the current workspace'),
             recursive: z.boolean().default(false).describe('Whether to list files recursively'),
             maxEntries: z.number().int().positive().max(500).default(100).describe('Maximum number of entries to return'),
+            cursor: z.string().optional().describe('Pagination cursor from a previous listFiles result. Continue after that entry.'),
             includeIgnored: z.boolean().default(false).describe('Include files ignored by .gitignore. Use only when explicitly needed.'),
         }),
-        execute: async ({ path: dirPath, recursive, maxEntries, includeIgnored }) => {
+        execute: async ({ path: dirPath, recursive, maxEntries, cursor, includeIgnored }, context) => runDedupedTool('listFiles', { path: dirPath, recursive, maxEntries, cursor, includeIgnored }, context, async () => {
             const absolutePath = resolveWorkspacePath(dirPath);
             await assertNotIgnored(absolutePath, dirPath, includeIgnored);
             const entries = [];
             let ignoredSkipped = 0;
-            const walked = await walkDir(absolutePath, { recursive, maxEntries, filter: async (entry) => {
+            const walked = await walkDir(absolutePath, { recursive, maxEntries: maxEntries + 1, cursor, filter: async (entry) => {
                     if (!includeIgnored && await isGitIgnored(entry.absolutePath)) {
                         ignoredSkipped++;
                         return false;
                     }
                     return true;
                 } });
-            for (const entry of walked) {
+            const page = walked.slice(0, maxEntries);
+            const hasMore = walked.length > maxEntries;
+            for (const entry of page) {
                 if (entry.isDirectory) {
                     entries.push({ path: entry.path, type: 'directory' });
                 }
@@ -70,8 +158,8 @@ export const hazeTools = {
                     entries.push({ path: entry.path, type: 'file', size: stat.size });
                 }
             }
-            return { path: dirPath, recursive, includeIgnored, ignoredSkipped, entries, truncated: entries.length >= maxEntries };
-        },
+            return { path: dirPath, recursive, includeIgnored, cursor, nextCursor: hasMore ? page.at(-1)?.path : undefined, ignoredSkipped, entries, truncated: hasMore };
+        }),
     }),
     readFile: tool({
         description: 'Read a UTF-8 text file from the current workspace. Supports optional 1-based line offset and line limit.',
@@ -81,7 +169,7 @@ export const hazeTools = {
             limit: z.number().int().positive().max(2000).optional().describe('Maximum number of lines to return'),
             allowIgnored: z.boolean().default(false).describe('Read the file even if it is ignored by .gitignore. Use only when explicitly needed.'),
         }),
-        execute: async ({ path: filePath, offset, limit, allowIgnored }) => {
+        execute: async ({ path: filePath, offset, limit, allowIgnored }, context) => runDedupedTool('readFile', { path: filePath, offset, limit, allowIgnored }, context, async () => {
             const absolutePath = resolveWorkspacePath(filePath);
             await assertNotIgnored(absolutePath, filePath, allowIgnored);
             const content = await fs.readFile(absolutePath, 'utf8');
@@ -98,20 +186,18 @@ export const hazeTools = {
                 lineNumberedText: numberLines(selectedLines, start + 1),
                 ...truncate(selected),
             };
-        },
+        }),
     }),
     replaceLines: tool({
         description: 'Replace a 1-based inclusive line range in an existing UTF-8 text file. Prefer this after reading a file when exact editFile replacements are ambiguous or fail.',
         inputSchema: z.object({
             path: z.string().describe('File path relative to the current workspace'),
             startLine: z.number().int().positive().describe('First 1-based line number to replace'),
-            endLine: z.number().int().positive().describe('Last 1-based line number to replace, inclusive'),
+            endLine: z.number().int().nonnegative().describe('Last 1-based line number to replace, inclusive. To append at EOF, use startLine=totalLines+1 and endLine=totalLines.'),
             content: z.string().describe('Replacement content for the line range'),
             allowIgnored: z.boolean().default(false).describe('Edit the file even if it is ignored by .gitignore. Use only when explicitly needed.'),
         }),
-        execute: async ({ path: filePath, startLine, endLine, content, allowIgnored }) => {
-            if (endLine < startLine)
-                throw new Error('endLine must be greater than or equal to startLine');
+        execute: async ({ path: filePath, startLine, endLine, content, allowIgnored }, context) => runDedupedTool('replaceLines', { path: filePath, startLine, endLine, content, allowIgnored }, context, async () => {
             const absolutePath = resolveWorkspacePath(filePath);
             await assertNotIgnored(absolutePath, filePath, allowIgnored);
             const original = await fs.readFile(absolutePath, 'utf8');
@@ -119,31 +205,51 @@ export const hazeTools = {
             const lines = original.split(/\r?\n/);
             if (hasTrailingNewline)
                 lines.pop();
+            const isAppend = startLine === lines.length + 1 && endLine === lines.length;
+            if (!isAppend && endLine < startLine)
+                throw new Error('endLine must be greater than or equal to startLine, except when appending at EOF with startLine=totalLines+1 and endLine=totalLines');
             if (startLine > lines.length + 1)
                 throw new Error(`startLine ${startLine} is beyond end of file (${lines.length} lines)`);
             if (endLine > lines.length)
                 throw new Error(`endLine ${endLine} is beyond end of file (${lines.length} lines)`);
             const replacementLines = content.length === 0 ? [] : content.split(/\r?\n/);
-            lines.splice(startLine - 1, endLine - startLine + 1, ...replacementLines);
+            if (isAppend) {
+                lines.push(...replacementLines);
+            }
+            else {
+                lines.splice(startLine - 1, endLine - startLine + 1, ...replacementLines);
+            }
             const updated = lines.join('\n') + (hasTrailingNewline ? '\n' : '');
             await fs.writeFile(absolutePath, updated, 'utf8');
-            return { ok: true, path: filePath, startLine, endLine, replacementLines: replacementLines.length };
-        },
+            return { ok: true, path: filePath, startLine, endLine, replacementLines: replacementLines.length, appended: isAppend };
+        }),
     }),
     writeFile: tool({
-        description: 'Create or overwrite a UTF-8 text file in the current workspace. Creates parent directories as needed. Use for new files or after smaller edit tools are not suitable.',
+        description: 'Create a UTF-8 text file in the current workspace. For existing files, prefer editFile/replaceLines; set overwriteExisting=true only for an intentional complete rewrite.',
         inputSchema: z.object({
             path: z.string().describe('File path relative to the current workspace'),
             content: z.string().describe('Complete file contents to write'),
+            overwriteExisting: z.boolean().default(false).describe('Required to overwrite an existing file. Prefer editFile or replaceLines for existing files unless a complete rewrite is intentional.'),
             allowIgnored: z.boolean().default(false).describe('Write the file even if it is ignored by .gitignore. Use only when explicitly needed.'),
         }),
-        execute: async ({ path: filePath, content, allowIgnored }) => {
+        execute: async ({ path: filePath, content, overwriteExisting, allowIgnored }, context) => runDedupedTool('writeFile', { path: filePath, content, overwriteExisting, allowIgnored }, context, async () => {
             const absolutePath = resolveWorkspacePath(filePath);
             await assertNotIgnored(absolutePath, filePath, allowIgnored);
+            try {
+                await fs.access(absolutePath);
+                if (!overwriteExisting) {
+                    throw new Error(`Refusing to overwrite existing file: ${filePath}. Use editFile/replaceLines for targeted edits, or set overwriteExisting=true for an intentional complete rewrite.`);
+                }
+            }
+            catch (error) {
+                const code = typeof error === 'object' && error != null && 'code' in error ? error.code : undefined;
+                if (code !== 'ENOENT')
+                    throw error;
+            }
             await fs.mkdir(path.dirname(absolutePath), { recursive: true });
             await fs.writeFile(absolutePath, content, 'utf8');
-            return { ok: true, path: filePath, bytes: Buffer.byteLength(content, 'utf8') };
-        },
+            return { ok: true, path: filePath, bytes: Buffer.byteLength(content, 'utf8'), overwritten: overwriteExisting };
+        }),
     }),
     editFile: tool({
         description: 'Edit a text file using exact replacements. Each oldText must match exactly once in the original file and edits must not overlap. If this fails because text is missing or not unique, do not retry; use replaceLines instead.',
@@ -155,7 +261,7 @@ export const hazeTools = {
             })).min(1).describe('One or more non-overlapping exact replacements'),
             allowIgnored: z.boolean().default(false).describe('Edit the file even if it is ignored by .gitignore. Use only when explicitly needed.'),
         }),
-        execute: async ({ path: filePath, edits, allowIgnored }) => {
+        execute: async ({ path: filePath, edits, allowIgnored }, context) => runDedupedTool('editFile', { path: filePath, edits, allowIgnored }, context, async () => {
             const absolutePath = resolveWorkspacePath(filePath);
             await assertNotIgnored(absolutePath, filePath, allowIgnored);
             const original = await fs.readFile(absolutePath, 'utf8');
@@ -179,15 +285,19 @@ export const hazeTools = {
             }
             await fs.writeFile(absolutePath, updated, 'utf8');
             return { ok: true, path: filePath, edits: edits.length };
-        },
+        }),
     }),
     bash: tool({
-        description: 'Run a bash command in the current workspace. Use for inspecting files, running tests, builds, and other shell tasks. Avoid destructive commands unless the user explicitly asked.',
+        description: 'Run a bash command in the current workspace. Use for tests, builds, validation, and inspection. Do not use bash to edit files; use file tools instead unless the user explicitly requested a shell mutation.',
         inputSchema: z.object({
             command: z.string().min(1).describe('Command to execute with bash -lc'),
             timeoutSeconds: z.number().int().positive().max(600).optional().describe('Timeout in seconds; defaults to 60'),
+            allowMutation: z.boolean().default(false).describe('Allow shell commands that mutate files (chmod, redirection, tee, sed -i, File.write, etc.). Use only when explicitly requested or when file tools cannot do the job.'),
         }),
-        execute: async ({ command, timeoutSeconds }, { abortSignal }) => {
+        execute: async ({ command, timeoutSeconds, allowMutation }, context) => runDedupedTool('bash', { command, timeoutSeconds, allowMutation }, context, async () => {
+            if (!allowMutation && looksLikeShellFileMutation(command)) {
+                throw new Error('Refusing to mutate files via bash. Use writeFile/editFile/replaceLines, or set allowMutation=true only when shell mutation is explicitly required.');
+            }
             const timeoutMs = (timeoutSeconds ?? 60) * 1000;
             return await new Promise(resolve => {
                 const child = spawn('bash', ['-lc', command], { cwd: workspaceRoot(), stdio: ['ignore', 'pipe', 'pipe'] });
@@ -199,13 +309,13 @@ export const hazeTools = {
                         child.kill('SIGTERM');
                 }, timeoutMs);
                 const abort = () => child.kill('SIGTERM');
-                abortSignal?.addEventListener('abort', abort, { once: true });
+                context.abortSignal?.addEventListener('abort', abort, { once: true });
                 child.stdout.on('data', data => stdout += data.toString());
                 child.stderr.on('data', data => stderr += data.toString());
                 child.on('close', code => {
                     settled = true;
                     clearTimeout(timer);
-                    abortSignal?.removeEventListener('abort', abort);
+                    context.abortSignal?.removeEventListener('abort', abort);
                     resolve({
                         ok: code === 0,
                         code,
@@ -217,10 +327,10 @@ export const hazeTools = {
                 child.on('error', error => {
                     settled = true;
                     clearTimeout(timer);
-                    abortSignal?.removeEventListener('abort', abort);
+                    context.abortSignal?.removeEventListener('abort', abort);
                     resolve({ ok: false, command, error: error.message });
                 });
             });
-        },
+        }),
     }),
 };

package/dist/llm/initPrompt.js

@@ -2,8 +2,8 @@ export function buildInitPrompt() {
     return `Initialize this repository for Haze by creating a best-practice AGENTS.md file.
 
 Explore the codebase first, respecting .gitignore:
-1. Use listFiles recursively from the workspace root.
-2. Read only the files needed to understand project conventions, commands, architecture, and release workflow. Usually read package/config files, README, and key source entrypoints.
+1. Start with exactly one listFiles call from the workspace root. Do not announce that you are starting before the tool call.
+2. After listFiles returns, do not call listFiles with the same input again. Immediately read the files needed to understand project conventions, commands, architecture, and release workflow. Usually read package/config files, README, AGENTS.md if present, and key source entrypoints.
 3. Do not read ignored files unless truly necessary.
 
 Create or update AGENTS.md at the workspace root. It should be concise and useful for future coding agents. Include sections when known:

package/dist/llm/systemPrompt.js

@@ -5,26 +5,40 @@ export function buildSystemPrompt(contextFiles = []) {
     return `You are Haze, an expert coding assistant operating inside a terminal-based agent CLI. You help users build apps by understanding the current conversation, inspecting projects, running commands, and editing files.
 
 Available tools:
-- listFiles: List files and directories in the current workspace. Prefer this over bash ls/find for project discovery.
+- listFiles: List files and directories in the current workspace. Supports recursive listings and cursor pagination. Prefer this over bash ls/find for project discovery.
 - readFile: Read UTF-8 files with optional line ranges. Returns lineNumberedText for line-based edits.
 - editFile: Edit files with exact unique text replacements. Use only for small, unambiguous replacements.
-- replaceLines: Replace a 1-based inclusive line range. Use when editFile is ambiguous or has failed once.
-- writeFile: Create or overwrite files. Use for new files or intentional complete rewrites.
-- bash: Run shell commands for tests, builds, scripts, and inspection that cannot be done with file tools.
+- replaceLines: Replace a 1-based inclusive line range. Use when editFile is ambiguous or has failed once. To append at EOF, use startLine=totalLines+1 and endLine=totalLines from the latest readFile result.
+- writeFile: Create files, or overwrite existing files only when overwriteExisting=true is intentionally set for a complete rewrite. Prefer editFile/replaceLines for existing files.
+- bash: Run shell commands for tests, builds, scripts, and inspection that cannot be done with file tools. Do not use bash to mutate files unless explicitly requested or file tools cannot do the job.
+- skill_*: Markdown skills installed in ~/.haze/skills. Use a skill tool when its description matches the user's request; it returns workflow instructions and explicitly referenced files.
 
 Guidelines:
 - Be concise, technical, and practical.
+- You have access to the tools listed above. Never claim that you cannot inspect files, run shell commands, or make file changes when an available tool can do it.
+- Skills are optional instruction bundles. Call a skill tool only when relevant, then follow the returned SKILL.md instructions and references.
+- If answering requires current workspace information, inspect it with tools instead of guessing or saying you cannot access it.
+- When the user asks you to run a command, inspect command output, or reason about local project state, use bash or file tools rather than only explaining what the user could run.
 - Preserve user-provided content exactly. When the user asks to add, modify, or use "this", "that", "it", or previous content, refer to the current conversation and do not substitute different text.
-- Use listFiles for project discovery instead of bash ls/find.
+- Use listFiles for project discovery instead of bash ls/find. Start non-recursive, use recursive for focused directories, and follow nextCursor only when more listing is genuinely needed.
 - Do not list or read the same path repeatedly unless the file changed or the previous result was insufficient.
 - Read only directly relevant files, usually once. Do not read README/package files unless needed for the task.
 - File tools follow .gitignore by default. Only set includeIgnored/allowIgnored when the user explicitly asks or the task truly requires ignored files, and say why.
 - Prefer editFile for existing files when one small exact replacement is unique.
 - If editFile fails because oldText is missing or not unique, do not retry editFile for the same change; use replaceLines with lineNumberedText from readFile.
-- Use writeFile only for new files or complete rewrites.
-- Use bash mainly for tests, builds, package scripts, and commands that are not covered by file tools.
-- After making changes, validate with the project's relevant test/typecheck/build command when practical.
-- After tool use, always respond with a concise summary of what changed or what failed.
+- Use writeFile for new files. For existing files, prefer editFile or replaceLines; only set writeFile overwriteExisting=true when a complete rewrite is intentional and safer than targeted edits.
+- Use bash mainly for tests, builds, package scripts, and commands that are not covered by file tools. Do not combine validation with file mutation in one shell command; use file tools for edits and bash only for validation/inspection.
+- After making changes, validate with the project's relevant test/typecheck/build command when practical. After editing source or test files in languages with syntax checkers, run the syntax check before the full test command when practical. Once a requested change is edited and validation passes, summarize; do not continue inspecting files.
+- For action requests such as "add", "create", "write", "implement", "update", "fix", "test", or "document", do not stop after only inspecting files. Make the requested file/code changes unless blocked or clarification is required.
+- Requests like "create a plan", "make a plan", or "outline a plan" are planning requests, not implementation requests. If you create a plan document, summarize it; do not start implementing or validating unless asked.
+- If editFile or replaceLines fails, read the affected file again with readFile before another edit attempt, then make one smaller targeted change; do not batch speculative replacements. Bash/cat does not satisfy this recovery step.
+- For plan-only requests, stop after creating/updating the plan artifact and summarize it; do not edit source files or run validation in the same turn.
+- When asked to implement a plan, identify the concrete required checklist items first and compare them with the current files. Do not edit source or tests when the required behavior is already present. Implement the smallest clearly required phase or required items, skip optional/design-question items unless explicitly requested, prefer adding tests over exploratory one-off scripts, validate once after code/test edits, and do not edit the plan file itself unless asked or unless marking completed items after validation passes.
+- After tool use, always respond with a concise summary of what changed or what failed for the current user request only. Do not recap unrelated earlier tasks unless directly relevant.
+- Do not call ordinary unfinished work or unresolved optional scope a blocker. A blocker is a concrete tool failure, missing/ambiguous requirement, permission problem, or unavailable dependency.
+- For Ruby ad-hoc checks, prefer adding/running Minitest tests. If a one-liner is truly useful, use ruby -I. -e with require "file" rather than require_relative from -e.
+- Do not say tools are unavailable just because a tool budget or loop guard was mentioned; if you can still call tools in the current turn, continue the requested work.
+- Do not claim tests passed or commands succeeded unless you actually ran them in the current turn and saw success.
 - Ask before destructive actions.
 - Show file paths clearly when working with files.${projectContext}
 

package/dist/skills/SkillLoader.d.ts

@@ -1,2 +1,12 @@
-import type { LoadedSkill } from './types.js';
-export declare function loadSkill(dir: string, source: 'global' | 'local'): Promise<LoadedSkill | null>;
+import type { LoadedSkill, SkillFrontmatter } from './types.js';
+declare function parseSkillMarkdown(content: string): {
+    frontmatter: SkillFrontmatter;
+    body: string;
+};
+declare function referencedPaths(body: string): string[];
+export declare function loadSkill(dir: string, source?: 'global'): Promise<LoadedSkill | null>;
+export declare const internals: {
+    parseSkillMarkdown: typeof parseSkillMarkdown;
+    referencedPaths: typeof referencedPaths;
+};
+export {};

package/dist/skills/SkillLoader.js

@@ -1,22 +1,68 @@
 import fs from 'fs-extra';
 import path from 'node:path';
-import { readYaml } from '../utils/yaml.js';
-import { skillManifestSchema } from './manifestSchema.js';
-export async function loadSkill(dir, source) {
-    const manifestPath = path.join(dir, 'skill.yaml');
-    if (!(await fs.pathExists(manifestPath)))
+import YAML from 'yaml';
+const MAX_REFERENCE_BYTES = 50_000;
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+const MARKDOWN_LINK_RE = /\[[^\]]*\]\(([^)]+)\)/g;
+const PLAIN_REFERENCE_RE = /(?:^|\n)\s*(?:[-*]\s+)?((?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+\.[A-Za-z0-9]+)\s*(?=\n|$)/g;
+function validateFrontmatter(value) {
+    if (typeof value !== 'object' || value == null)
+        throw new Error('SKILL.md frontmatter must be an object');
+    const frontmatter = value;
+    if (typeof frontmatter.name !== 'string' || frontmatter.name.trim().length === 0)
+        throw new Error('SKILL.md frontmatter requires name');
+    if (!/^[a-zA-Z0-9_-]+$/.test(frontmatter.name))
+        throw new Error('Skill name may only contain letters, numbers, hyphens, and underscores');
+    if (typeof frontmatter.description !== 'string' || frontmatter.description.trim().length === 0)
+        throw new Error('SKILL.md frontmatter requires description');
+    return { name: frontmatter.name.trim(), description: frontmatter.description.trim() };
+}
+function parseSkillMarkdown(content) {
+    const match = FRONTMATTER_RE.exec(content);
+    if (!match)
+        throw new Error('SKILL.md must start with YAML frontmatter delimited by ---');
+    const frontmatter = validateFrontmatter(YAML.parse(match[1] ?? ''));
+    return { frontmatter, body: content.slice(match[0].length).trim() };
+}
+function normalizeReference(reference) {
+    const withoutAnchor = reference.split('#')[0]?.split('?')[0]?.trim() ?? '';
+    return withoutAnchor.replace(/^<|>$/g, '');
+}
+function referencedPaths(body) {
+    const refs = new Set();
+    for (const match of body.matchAll(MARKDOWN_LINK_RE)) {
+        const ref = normalizeReference(match[1] ?? '');
+        if (ref && !ref.includes('://'))
+            refs.add(ref);
+    }
+    for (const match of body.matchAll(PLAIN_REFERENCE_RE)) {
+        const ref = normalizeReference(match[1] ?? '');
+        if (ref)
+            refs.add(ref);
+    }
+    return [...refs];
+}
+async function loadReference(dir, referencePath) {
+    if (path.isAbsolute(referencePath))
+        throw new Error(`Skill reference must be relative: ${referencePath}`);
+    const absolutePath = path.resolve(dir, referencePath);
+    const relative = path.relative(dir, absolutePath);
+    if (relative.startsWith('..') || path.isAbsolute(relative))
+        throw new Error(`Skill reference escapes skill directory: ${referencePath}`);
+    const stat = await fs.stat(absolutePath);
+    if (!stat.isFile())
+        throw new Error(`Skill reference is not a file: ${referencePath}`);
+    if (stat.size > MAX_REFERENCE_BYTES)
+        throw new Error(`Skill reference is too large: ${referencePath}`);
+    return { path: referencePath, absolutePath, content: await fs.readFile(absolutePath, 'utf8') };
+}
+export async function loadSkill(dir, source = 'global') {
+    const skillPath = path.join(dir, 'SKILL.md');
+    if (!(await fs.pathExists(skillPath)))
         return null;
-    const raw = await readYaml(manifestPath);
-    const manifest = skillManifestSchema.parse(raw);
-    const prompts = await Promise.all((manifest.prompts ?? []).map(async (p) => {
-        const absolutePath = path.resolve(dir, p.path);
-        return { ...p, absolutePath, content: await fs.readFile(absolutePath, 'utf8') };
-    }));
-    const tools = (manifest.tools ?? []).map(t => ({
-        ...t,
-        id: `${manifest.name}.${t.name}`,
-        skillName: manifest.name,
-        absolutePath: path.resolve(dir, t.path)
-    }));
-    return { dir, manifestPath, manifest, prompts, tools, source };
+    const content = await fs.readFile(skillPath, 'utf8');
+    const { frontmatter, body } = parseSkillMarkdown(content);
+    const references = await Promise.all(referencedPaths(body).map(ref => loadReference(dir, ref)));
+    return { dir, path: skillPath, name: frontmatter.name, description: frontmatter.description, body, references, source };
 }
+export const internals = { parseSkillMarkdown, referencedPaths };

package/dist/skills/SkillRegistry.d.ts

@@ -1,6 +1,2 @@
-import type { LoadedSkill, LoadedTool } from './types.js';
-export interface SkillRegistry {
-    skills: Map<string, LoadedSkill>;
-    tools: Map<string, LoadedTool>;
-}
+import type { SkillRegistry } from './types.js';
 export declare function loadSkillRegistry(): Promise<SkillRegistry>;

package/dist/skills/SkillRegistry.js

@@ -1,28 +1,17 @@
 import fs from 'fs-extra';
 import path from 'node:path';
-import { GLOBAL_SKILLS_DIR, LOCAL_SKILLS_DIR } from '../config/paths.js';
+import { GLOBAL_SKILLS_DIR } from '../config/paths.js';
 import { loadSkill } from './SkillLoader.js';
 export async function loadSkillRegistry() {
     const skills = new Map();
-    const tools = new Map();
-    async function scanDir(root, source) {
-        if (!(await fs.pathExists(root)))
-            return;
-        for (const name of await fs.readdir(root)) {
-            const dir = path.join(root, name);
-            if (!(await fs.stat(dir)).isDirectory())
-                continue;
-            const skill = await loadSkill(dir, source);
-            if (skill)
-                skills.set(skill.manifest.name, skill);
-        }
-    }
     await fs.ensureDir(GLOBAL_SKILLS_DIR);
-    await fs.ensureDir(LOCAL_SKILLS_DIR);
-    await scanDir(GLOBAL_SKILLS_DIR, 'global');
-    await scanDir(LOCAL_SKILLS_DIR, 'local');
-    for (const skill of skills.values())
-        for (const tool of skill.tools)
-            tools.set(tool.id, tool);
-    return { skills, tools };
+    for (const name of await fs.readdir(GLOBAL_SKILLS_DIR)) {
+        const dir = path.join(GLOBAL_SKILLS_DIR, name);
+        if (!(await fs.stat(dir)).isDirectory())
+            continue;
+        const skill = await loadSkill(dir, 'global');
+        if (skill)
+            skills.set(skill.name, skill);
+    }
+    return { skills };
 }

package/dist/skills/builder/SkillBuilder.d.ts

@@ -1 +1,25 @@
-export declare function buildSkill(description: string): Promise<void>;
+type GeneratedSkillFile = {
+    path: string;
+    content: string;
+};
+type GeneratedSkill = {
+    name: string;
+    files: GeneratedSkillFile[];
+};
+export declare function slug(s: string): string;
+declare function fallbackSkill(description: string): GeneratedSkill;
+declare function withStandardRequirements(content: string): string;
+declare function parseGeneratedSkill(text: string, description: string): GeneratedSkill;
+export declare function createSkill(description: string): Promise<{
+    name: string;
+    dir: string;
+    file: string;
+}>;
+export declare const internals: {
+    SKILL_CREATOR_SKILL: string;
+    STANDARD_SKILL_REQUIREMENTS: string;
+    parseGeneratedSkill: typeof parseGeneratedSkill;
+    fallbackSkill: typeof fallbackSkill;
+    withStandardRequirements: typeof withStandardRequirements;
+};
+export {};