diff --git a/CLAUDE.md b/CLAUDE.md index ea62970..df048e8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -80,7 +80,9 @@ Read `docs/architecture.md` first. Key points: - **System prompt** pulls project context from the working directory: `AGENTS.md`, or `CLAUDE.md` if there is no `AGENTS.md` (never both), plus `PERSONA.md` and `MEMORY.md`. File names match case-insensitively. `SkillCatalog` lists the cwd's Agent Skills (`.volcanic/skills//SKILL.md`, frontmatter `name`/`description`) in a `` - section on every run; the model reads a SKILL.md with `read`. Only the cwd, so chats never see each other's skills. + section on every run; the model reads a SKILL.md with `read`. A skill dir's optional `INSTRUCTIONS.md` (even without + SKILL.md) goes in full into `` on every run (16 KB/file, 64 KB total, truncation noted). + Only the cwd, so chats never see each other's skills. The Claude Code provider keeps the CLI's own skills off (`--setting-sources ""`, `--disable-slash-commands`). - **Extension discovery**: host code, then `/.volcanic/settings.json` / `.volcanic/extensions/*.dll`, then the same under `~/.volcanic/agent`. Earlier sources win name collisions. Each assembly loads in its own diff --git a/README.md b/README.md index e6e0524..c66451a 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,8 @@ event model; slash commands; provider registration; API key resolution; built-in Beyond pi: the working directory may also hold `PERSONA.md` (the agent's personality) and `MEMORY.md` (memories the agent maintains itself with `edit`/`write`); both are appended to the system prompt when present. File names match case-insensitively. Agent Skills (Anthropic's `SKILL.md` format) in `/.volcanic/skills//SKILL.md` are -listed by name and description in the system prompt on every run; the model reads a skill's file when it needs it. +listed by name and description in the system prompt on every run; the model reads a skill's file when it needs it. An +`INSTRUCTIONS.md` next to it (or alone in the directory) goes into the prompt in full on every run (16 KB per file, 64 KB total). Not ported (by design): the terminal UI, themes, keybindings, renderers, prompt templates, OAuth logins, image generation models, session tree navigation commands. diff --git a/docs/telegram-bot.md b/docs/telegram-bot.md index 987566f..0b42490 100644 --- a/docs/telegram-bot.md +++ b/docs/telegram-bot.md @@ -188,6 +188,16 @@ description and path, re-read on every run, so a skill the agent (or you) just w on, no `/new` needed. The model reads the full SKILL.md with `read` when a task matches. Skills without a `description` are skipped. A chat only sees the skills in its own workspace. `/skills` lists them. +A skill directory may also hold an `INSTRUCTIONS.md` (name matched case-insensitively): standing rules that apply all +the time, not only when the skill is used. Its whole body (a leading YAML frontmatter is cut) goes into every system +prompt in a `` section after ``, as `` +blocks in directory order. It is re-read on every run, so an edit counts from the next message. The name is the +SKILL.md `name`, else the directory name. A directory may hold only an `INSTRUCTIONS.md`; it is then not listed among +the skills, but its rules still apply. Limits: 16 KB (16,384 characters) per file and 64 KB (65,536) for all +files together; a file over its share is cut and the prompt says `[…truncated, read the full file at ]`, and +once the total is used up, later files appear with only that note. Empty and unreadable files are skipped. `/skills` +marks skills with `(+ INSTRUCTIONS.md)` and lists instruction-only directories as `INSTRUCTIONS.md only`. + ```markdown --- name: trip-planner diff --git a/hosts/Volcanic.AgenticCore.Telegram/Chats/ChatCommands.cs b/hosts/Volcanic.AgenticCore.Telegram/Chats/ChatCommands.cs index 3265251..95bf4b3 100644 --- a/hosts/Volcanic.AgenticCore.Telegram/Chats/ChatCommands.cs +++ b/hosts/Volcanic.AgenticCore.Telegram/Chats/ChatCommands.cs @@ -226,9 +226,15 @@ public sealed class ChatCommands(TelegramSender sender, ChatTimeZoneService? zon private static string Skills(ChatContext chat) { var skills = SkillCatalog.Load(chat.Session.Cwd); + var instructions = SkillCatalog.LoadInstructions(chat.Session.Cwd); var where = $"`{Path.GetRelativePath(chat.Session.Cwd, SkillCatalog.Directory(chat.Session.Cwd))}//SKILL.md`"; - if (skills.Count == 0) return $"No skills yet. Ask me to write one, or put it in {where}."; - return $"**Skills** ({where})\n" + string.Join('\n', skills.Select(s => $"• **{s.Name}** – {s.Description}")); + if (skills.Count == 0 && instructions.Count == 0) return $"No skills yet. Ask me to write one, or put it in {where}."; + + static string Mark(SkillInstructions i) => i.Truncated ? " (+ INSTRUCTIONS.md, truncated in the prompt)" : " (+ INSTRUCTIONS.md)"; + var byDir = instructions.ToDictionary(i => Path.GetDirectoryName(i.Path)!, StringComparer.Ordinal); + var lines = skills.Select(s => $"• **{s.Name}** – {s.Description}" + (byDir.Remove(Path.GetDirectoryName(s.Path)!, out var i) ? Mark(i) : "")) + .Concat(byDir.Values.Select(i => $"• **{i.Name}** – INSTRUCTIONS.md only" + (i.Truncated ? " (truncated in the prompt)" : ""))); + return $"**Skills** ({where})\n" + string.Join('\n', lines); } private string Jobs(ChatContext chat) diff --git a/src/Volcanic.AgenticCore/Features/SystemPrompt/DefaultPrompts.cs b/src/Volcanic.AgenticCore/Features/SystemPrompt/DefaultPrompts.cs index e627f8d..35c8099 100644 --- a/src/Volcanic.AgenticCore/Features/SystemPrompt/DefaultPrompts.cs +++ b/src/Volcanic.AgenticCore/Features/SystemPrompt/DefaultPrompts.cs @@ -35,5 +35,14 @@ public static class DefaultPrompts When a task matches a skill's description, read its SKILL.md with the read tool before you start and follow it. Resolve relative paths in a skill against the skill's directory. To create or improve a skill, write or edit its SKILL.md; the list below is re-read on every run. + A skill directory may also hold an INSTRUCTIONS.md (with or without a SKILL.md): rules that apply all the time. + Its body is always in your system prompt (), re-read on every run, so you never read it + yourself unless it is marked truncated. Keep it short (it is capped at 16 KB per file, 64 KB in total) and put + task-specific detail in SKILL.md instead. + """; + + public const string SkillInstructionsPreamble = """ + Standing instructions from the skill directories' INSTRUCTIONS.md files. Follow them at all times, not only + when a skill is in use. Resolve relative paths against the file's directory. """; } diff --git a/src/Volcanic.AgenticCore/Features/SystemPrompt/SkillCatalog.cs b/src/Volcanic.AgenticCore/Features/SystemPrompt/SkillCatalog.cs index 270ee13..81f84e0 100644 --- a/src/Volcanic.AgenticCore/Features/SystemPrompt/SkillCatalog.cs +++ b/src/Volcanic.AgenticCore/Features/SystemPrompt/SkillCatalog.cs @@ -5,36 +5,40 @@ namespace Volcanic.AgenticCore.Features.SystemPrompt; /// A skill found in the workspace: frontmatter name and description, and the absolute path of its SKILL.md. public sealed record Skill(string Name, string Description, string Path); +/// +/// The always-on part of a skill directory: the body of its INSTRUCTIONS.md (frontmatter cut), already capped. +/// when the per-file or the total limit cut it. +/// +public sealed record SkillInstructions(string Name, string Path, string Content, bool Truncated); + /// /// Agent Skills (Anthropic's format) from the working directory only: <cwd>/.volcanic/skills/<dir>/SKILL.md, /// a YAML frontmatter with name and description, then the instructions. Scanned on every call, so a skill /// written by the agent shows up in the next run's system prompt. Skills without a description are skipped; the name /// defaults to the directory name. The model only sees the list and reads a SKILL.md itself (progressive disclosure). +/// A skill directory may also hold an INSTRUCTIONS.md, with or without a SKILL.md: its body goes into every system +/// prompt in full (), up to per file and +/// in total. /// public static class SkillCatalog { public const int MaxSkills = 100; public const int MaxDescriptionLength = 1024; + public const int MaxInstructionsLength = 16 * 1024; + public const int MaxTotalInstructionsLength = 64 * 1024; + public const string SkillFile = "SKILL.md"; + public const string InstructionsFile = "INSTRUCTIONS.md"; private const int MaxFrontmatterBytes = 16 * 1024; public static string Directory(string cwd) => System.IO.Path.Combine(cwd, ".volcanic", "skills"); public static IReadOnlyList Load(string cwd) { - var root = Directory(cwd); - IEnumerable dirs; - try - { - if (!System.IO.Directory.Exists(root)) return []; - dirs = System.IO.Directory.EnumerateDirectories(root).Order(StringComparer.Ordinal).ToList(); - } - catch (Exception e) when (e is IOException or UnauthorizedAccessException) { return []; } - var skills = new List(); - foreach (var dir in dirs) + foreach (var dir in SkillDirectories(cwd)) { if (skills.Count >= MaxSkills) break; - var file = SystemPromptBuilder.FindFile(dir, "SKILL.md"); + var file = SystemPromptBuilder.FindFile(dir, SkillFile); if (file is null || Parse(file, System.IO.Path.GetFileName(dir)) is not { } skill) continue; if (skills.Any(s => string.Equals(s.Name, skill.Name, StringComparison.OrdinalIgnoreCase))) continue; skills.Add(skill); @@ -42,18 +46,37 @@ public static class SkillCatalog return skills; } + /// + /// The INSTRUCTIONS.md of every skill directory, in directory order, read fresh on every call. Empty and unreadable + /// files are skipped. The name is the SKILL.md frontmatter name when there is one, else the directory name. + /// Each body is capped at ; once is used + /// up, the next file is cut to what is left and later ones come with an empty body, all marked truncated. + /// + public static IReadOnlyList LoadInstructions(string cwd) + { + var result = new List(); + var budget = MaxTotalInstructionsLength; + foreach (var dir in SkillDirectories(cwd)) + { + if (result.Count >= MaxSkills) break; + var file = SystemPromptBuilder.FindFile(dir, InstructionsFile); + if (file is null || ReadPrefix(file, MaxFrontmatterBytes + MaxInstructionsLength + 1) is not { } text) continue; + var body = StripFrontmatter(text).Trim(); + if (body.Length == 0) continue; + + var limit = Math.Min(MaxInstructionsLength, budget); + var truncated = body.Length > limit; + if (truncated) body = body[..limit].TrimEnd(); + budget -= body.Length; + result.Add(new SkillInstructions(NameOf(dir), file, body, truncated)); + } + return result; + } + /// Reads the frontmatter of one SKILL.md. Null when it is unreadable or has no description. public static Skill? Parse(string path, string fallbackName) { - string text; - try - { - using var reader = new StreamReader(path); - var buffer = new char[MaxFrontmatterBytes]; - text = new string(buffer, 0, reader.ReadBlock(buffer, 0, buffer.Length)); - } - catch (Exception e) when (e is IOException or UnauthorizedAccessException) { return null; } - + if (ReadPrefix(path, MaxFrontmatterBytes) is not { } text) return null; var fields = Frontmatter(text); var name = fields.GetValueOrDefault("name"); var description = fields.GetValueOrDefault("description"); @@ -78,6 +101,66 @@ public static class SkillCatalog return sb.Append("\n").ToString(); } + /// The always-on section: one <instructions> block per file. Empty when there are none. + public static string RenderInstructions(IReadOnlyList instructions) + { + if (instructions.Count == 0) return ""; + var sb = new StringBuilder(DefaultPrompts.SkillInstructionsPreamble); + foreach (var item in instructions) + { + sb.Append("\n\n\n"); + if (item.Content.Length > 0) sb.Append(item.Content).Append('\n'); + if (item.Truncated) sb.Append("[…truncated, read the full file at ").Append(item.Path).Append("]\n"); + sb.Append(""); + } + return sb.ToString(); + } + + /// Text after a leading --- frontmatter block; the whole text when there is none or it never closes. + internal static string StripFrontmatter(string text) + { + var normalized = text.Replace("\r\n", "\n"); + if (normalized.StartsWith('\uFEFF')) normalized = normalized[1..]; + var lines = normalized.Split('\n'); + if (lines[0].Trim() != "---") return normalized; + for (var i = 1; i < lines.Length; i++) + { + if (lines[i].Trim() == "---") return string.Join('\n', lines[(i + 1)..]); + } + return normalized; + } + + private static IReadOnlyList SkillDirectories(string cwd) + { + var root = Directory(cwd); + try + { + return System.IO.Directory.Exists(root) ? System.IO.Directory.EnumerateDirectories(root).Order(StringComparer.Ordinal).ToList() : []; + } + catch (Exception e) when (e is IOException or UnauthorizedAccessException) { return []; } + } + + /// The SKILL.md frontmatter name, with or without a description, else the directory name. + private static string NameOf(string dir) + { + var fallback = System.IO.Path.GetFileName(dir); + var file = SystemPromptBuilder.FindFile(dir, SkillFile); + var name = file is null || ReadPrefix(file, MaxFrontmatterBytes) is not { } text ? null : Frontmatter(text).GetValueOrDefault("name"); + return string.IsNullOrWhiteSpace(name) ? fallback : Collapse(name); + } + + private static string? ReadPrefix(string path, int maxChars) + { + try + { + using var reader = new StreamReader(path); + var buffer = new char[maxChars]; + return new string(buffer, 0, reader.ReadBlock(buffer, 0, buffer.Length)); + } + catch (Exception e) when (e is IOException or UnauthorizedAccessException) { return null; } + } + /// /// Top-level key: value pairs between the leading --- lines. Handles quoted values, |/> /// block scalars and indented continuation lines; anything else YAML can do is ignored. @@ -123,4 +206,6 @@ public static class SkillCatalog private static string Collapse(string value) => string.Join(' ', value.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries)); private static string Escape(string value) => value.Replace("&", "&").Replace("<", "<").Replace(">", ">"); + + private static string EscapeAttribute(string value) => Escape(value).Replace("\"", """); } diff --git a/src/Volcanic.AgenticCore/Features/SystemPrompt/SystemPromptBuilder.cs b/src/Volcanic.AgenticCore/Features/SystemPrompt/SystemPromptBuilder.cs index d261771..103efbe 100644 --- a/src/Volcanic.AgenticCore/Features/SystemPrompt/SystemPromptBuilder.cs +++ b/src/Volcanic.AgenticCore/Features/SystemPrompt/SystemPromptBuilder.cs @@ -9,7 +9,7 @@ namespace Volcanic.AgenticCore.Features.SystemPrompt; /// /// Composes the system prompt: base prompt, tools section (from ), guidelines, /// extra sections, project context files (AGENTS.md, else CLAUDE.md, per directory walking up from cwd), the agent's -/// persona (PERSONA.md in cwd), its memory (MEMORY.md in cwd), its skills (), then date, time zone and cwd. File names match case-insensitively. +/// persona (PERSONA.md in cwd), its memory (MEMORY.md in cwd), its skills and their always-on INSTRUCTIONS.md (), then date, time zone and cwd. File names match case-insensitively. /// public sealed class SystemPromptBuilder { @@ -70,6 +70,9 @@ public sealed class SystemPromptBuilder if (memory.Path is not null) AppendSection(sb, "memory", DefaultPrompts.MemoryPreamble(memory.Path) + (string.IsNullOrWhiteSpace(memory.Content) ? "" : "\n\n" + memory.Content)); AppendSection(sb, "skills", SkillCatalog.Render(_cwd, SkillCatalog.Load(_cwd))); + + var instructions = SkillCatalog.RenderInstructions(SkillCatalog.LoadInstructions(_cwd)); + if (instructions.Length > 0) AppendSection(sb, "skill_instructions", instructions); } AppendSection(sb, "environment", EnvironmentSection(_time.GetUtcNow(), _zone(), _cwd)); diff --git a/tests/Volcanic.AgenticCore.Telegram.Tests/SkillsChatTests.cs b/tests/Volcanic.AgenticCore.Telegram.Tests/SkillsChatTests.cs index 3f98524..909a6b6 100644 --- a/tests/Volcanic.AgenticCore.Telegram.Tests/SkillsChatTests.cs +++ b/tests/Volcanic.AgenticCore.Telegram.Tests/SkillsChatTests.cs @@ -45,4 +45,26 @@ public sealed class SkillsChatTests Assert.Contains(Path.Combine(host.WorkspaceOf(), ".volcanic", "skills", "trips", "SKILL.md"), prompt); Assert.DoesNotContain("other-chat", prompt); } + + [Fact] + public async Task Skills_marks_instructions_and_lists_instruction_only_folders() + { + await using var host = new ChatHost(); + var root = Path.Combine(host.WorkspaceOf(), ".volcanic", "skills"); + WriteSkill(host.WorkspaceOf(), "trips", "trip-planner", "Plans trips"); + WriteSkill(host.WorkspaceOf(), "mail", "mailer", "Sends mail"); + File.WriteAllText(Path.Combine(root, "trips", "INSTRUCTIONS.md"), "Prices in EUR."); + Directory.CreateDirectory(Path.Combine(root, "house-rules")); + File.WriteAllText(Path.Combine(root, "house-rules", "Instructions.md"), "Be brief."); + host.Faux.Enqueue(FauxTurn.Say("ok")); + + await host.SendAsync("/skills"); + Assert.Equal("Skills (.volcanic/skills//SKILL.md)\n• mailer – Sends mail\n• trip-planner – Plans trips (+ INSTRUCTIONS.md)\n• house-rules – INSTRUCTIONS.md only", host.LastReply()); + + await host.SendAsync("hi"); + await host.SettleAsync(); + var prompt = host.Faux.Requests.Last().SystemPrompt!; + Assert.Contains("tags as is."); + try + { + var builder = new SystemPromptBuilder(dir, () => [], new FakeTimeProvider(DateTimeOffset.UnixEpoch), () => TimeZoneInfo.Utc); + var prompt = builder.Render(builder.DefaultOptions("BASE")); + + Assert.Equal(["a-rules", "trip-planner", "named \\\"rules\\\""], SkillCatalog.LoadInstructions(dir).Select(i => i.Name)); + Assert.Contains($"\nNever book before 9:00.\n", prompt); + Assert.Contains($"\nAlways quote prices in EUR.\n", prompt); + Assert.Contains("skill=\"named \\"rules\\"\"", prompt); + Assert.Contains("Use tags as is.", prompt); + Assert.DoesNotContain("ignored", prompt); + Assert.DoesNotContain("c-empty", prompt); + Assert.DoesNotContain("Lazy body", prompt); + Assert.Equal(["trip-planner"], SkillCatalog.Load(dir).Select(s => s.Name)); + var order = new[] { "\n\n", "\n\n", "\n\n" }.Select(t => prompt.IndexOf(t, StringComparison.Ordinal)).ToList(); + Assert.Equal(order.Order(), order); + Assert.True(order[0] >= 0); + + File.WriteAllText(Path.Combine(skills, "a-rules", "INSTRUCTIONS.md"), "Never book before 10:00."); + Assert.Contains("Never book before 10:00.", builder.Render(builder.DefaultOptions("BASE"))); + + var narrow = builder.DefaultOptions("BASE"); + narrow.IncludeProjectContext = false; + Assert.DoesNotContain("", builder.Render(narrow)); + } + finally { Directory.Delete(dir, true); } + } + + [Fact] + public void Without_instructions_there_is_no_instructions_section() + { + var dir = Path.Combine(Path.GetTempPath(), "volcanic-prompt", Guid.NewGuid().ToString("N")); + Directory.CreateDirectory(dir); + try + { + var builder = new SystemPromptBuilder(dir, () => [], new FakeTimeProvider(DateTimeOffset.UnixEpoch), () => TimeZoneInfo.Utc); + Assert.DoesNotContain("\n\n", builder.Render(builder.DefaultOptions("BASE"))); + } + finally { Directory.Delete(dir, true); } + } + + [Fact] + public void Instructions_are_capped_per_file_and_in_total_with_a_pointer_to_the_file() + { + var dir = Path.Combine(Path.GetTempPath(), "volcanic-prompt", Guid.NewGuid().ToString("N")); + var skills = Path.Combine(dir, ".volcanic", "skills"); + var per = SkillCatalog.MaxInstructionsLength; + // 3 full files use 48 KB, the fourth is cut by its own cap, the fifth gets nothing. + for (var i = 0; i < 5; i++) + { + Directory.CreateDirectory(Path.Combine(skills, $"s{i}")); + File.WriteAllText(Path.Combine(skills, $"s{i}", "INSTRUCTIONS.md"), new string((char)('a' + i), i == 3 ? per + 500 : per)); + } + Directory.CreateDirectory(Path.Combine(skills, "s5")); + File.WriteAllText(Path.Combine(skills, "s5", "INSTRUCTIONS.md"), "late"); + try + { + var loaded = SkillCatalog.LoadInstructions(dir); + Assert.Equal([per, per, per, per, 0, 0], loaded.Select(i => i.Content.Length)); + Assert.Equal([false, false, false, true, true, true], loaded.Select(i => i.Truncated)); + Assert.Equal(SkillCatalog.MaxTotalInstructionsLength, loaded.Sum(i => i.Content.Length)); + + var section = SkillCatalog.RenderInstructions(loaded); + Assert.Contains($"[…truncated, read the full file at {Path.Combine(skills, "s3", "INSTRUCTIONS.md")}]", section); + Assert.Contains($"location=\"{Path.Combine(skills, "s5", "INSTRUCTIONS.md")}\">\n[…truncated, read the full file at {Path.Combine(skills, "s5", "INSTRUCTIONS.md")}]\n", section); + Assert.DoesNotContain("late", section); + } + finally { Directory.Delete(dir, true); } + } + + [Theory] + [InlineData("---\na: b\n---\nbody", "body")] + [InlineData("\uFEFF---\r\na: b\r\n---\r\nbody", "body")] + [InlineData("---\nnever closed\nbody", "---\nnever closed\nbody")] + [InlineData("plain\n---\nrule", "plain\n---\nrule")] + public void StripFrontmatter_cuts_only_a_leading_closed_block(string text, string expected) => + Assert.Equal(expected, SkillCatalog.StripFrontmatter(text)); } public class CompactorTests