Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

skills: read a workspace's .agents/skills, and advertise workspace skills under --lean

justrachb7f9f5cde079
diff --git a/src/native_fold.zig b/src/native_fold.zig
index c14f9685..574d0051 100644
--- a/src/native_fold.zig
+++ b/src/native_fold.zig
@@ -75,6 +75,9 @@ pub const folded = [_][]const u8{
/// structured-only catalog and the meta-tool listing stay unchanged.
pub fn isFolded(name: []const u8) bool {
if (std.mem.eql(u8, name, "rlm")) return @import("rlm_spec.zig").available;
+ // The workspace ships skills (its catalog is in the prompt): loading one
+ // is the task's first step, so `skill` is not worth a load_tool_schemas trip.
+ if (std.mem.eql(u8, name, "skill") and @import("skill_docs.zig").g_workspace_skills) return false;
for (folded) |tool| {
if (std.mem.eql(u8, name, tool)) return true;
}
diff --git a/src/no_local_tools.zig b/src/no_local_tools.zig
index 1ba224ea..0e8c95ca 100644
--- a/src/no_local_tools.zig
+++ b/src/no_local_tools.zig
@@ -110,7 +110,8 @@ pub fn leanKeeps(name: []const u8) bool {
for (lean_tools) |tool| {
if (std.mem.eql(u8, name, tool)) return true;
}
- return false;
+ // A workspace that ships skills keeps `skill` beside its catalog.
+ return @import("skill_docs.zig").g_workspace_skills and std.mem.eql(u8, name, "skill");
}
/// schema.zig chains this after filterRootSpecs (a tool may survive one and
diff --git a/src/skill_docs.zig b/src/skill_docs.zig
index 0a630f50..fdf68faa 100644
--- a/src/skill_docs.zig
+++ b/src/skill_docs.zig
@@ -68,7 +68,7 @@ const desc_cap = 160; // per-skill description budget in the system prompt — t
/// a schema.ToolSpec) so schema.zig's catalog needs one entry and no import
/// cycle. The description must stay free of characters needing JSON escapes.
pub const tool_name = "skill";
-pub const tool_desc = "Load a skill: the full instructions for one kind of task, kept out of your context until you need them. The system prompt lists only skill names and descriptions, so call this to read the body BEFORE doing work a skill covers, then follow it. Omit name to list every available skill. Skills come from .harness/skills/, ~/.harness/skills/, .claude/skills/, Cursor/Claude/Grok/Codex plugin trees (including Claude commands/*.md and a root SKILL.md), plus bundled skill-creator, mcp-config, mcp, jspace, and workspace.";
+pub const tool_desc = "Load a skill: the full instructions for one kind of task, kept out of your context until you need them. The system prompt lists only skill names and descriptions, so call this to read the body BEFORE doing work a skill covers, then follow it. Omit name to list every available skill. Skills come from .harness/skills/, ~/.harness/skills/, .claude/skills/, .agents/skills/, Cursor/Claude/Grok/Codex plugin trees (including Claude commands/*.md and a root SKILL.md), plus bundled skill-creator, mcp-config, mcp, jspace, and workspace.";
pub const tool_schema =
\\{"type": "object", "properties": {"name": {"type": "string", "description": "Skill name to load; omit to list every available skill"}}}
;
@@ -132,12 +132,35 @@ pub var g_skills: []const Skill = &builtins;
/// Resolved HOME for the personal tier, so execSkill's rescan finds the same
/// set the startup scan did.
pub var g_home: ?[]const u8 = null; // pub: split-out tests save/restore it
+/// Startup found skills the workspace itself ships (project tier). Their
+/// catalog is in the prompt, so `skill` stays on the wire (no fold, kept
+/// under --lean) and loading one costs a single call.
+pub var g_workspace_skills: bool = false;
pub fn load(io: Io, arena: Allocator, home: ?[]const u8) []const Skill {
g_home = home;
return scan(io, arena, home);
}
+/// Only the skills the workspace ships (the project tier, same precedence as
+/// `collect`), for --lean: no personal dirs, no plugin walk. A repo or task
+/// skill is part of the job, so lean still advertises it.
+pub fn loadProject(io: Io, arena: Allocator, home: ?[]const u8) []const Skill {
+ g_home = home;
+ return projectSkills(io, arena, "");
+}
+
+/// The project tier under `root` ("" = the working directory).
+pub fn projectSkills(io: Io, arena: Allocator, root: []const u8) []const Skill {
+ var list: std.ArrayList(Skill) = .empty;
+ for ([_][]const u8{ compat_dir, ".grok/skills", ".codex/skills", ".agents/skills", ".cursor/skills", project_dir }) |dir| {
+ const path = if (root.len == 0) dir else std.fmt.allocPrint(arena, "{s}/{s}", .{ root, dir }) catch continue;
+ loadDir(io, arena, &list, path, .project);
+ }
+ applyDisabled(io, arena, &list);
+ return list.items;
+}
+
/// Re-scan after the installed set may have changed — a `/skills remove` opt-out
/// landing in settings, or a SKILL.md written this session — so `/skills` and
/// any later prompt build stay honest without a restart.
@@ -178,6 +201,7 @@ fn collect(io: Io, arena: Allocator, home: ?[]const u8) std.ArrayList(Skill) {
loadDir(io, arena, &list, compat_dir, .project);
loadDir(io, arena, &list, ".grok/skills", .project);
loadDir(io, arena, &list, ".codex/skills", .project);
+ loadDir(io, arena, &list, ".agents/skills", .project);
loadDir(io, arena, &list, ".cursor/skills", .project);
for (plugs) |p| {
if (p.personal) continue;
diff --git a/src/skill_docs_tests.zig b/src/skill_docs_tests.zig
index 60809c2d..945e5c65 100644
--- a/src/skill_docs_tests.zig
+++ b/src/skill_docs_tests.zig
@@ -58,3 +58,42 @@ test "#730: a SKILL.md over 8 KB stays in the catalog and loads whole" {
try std.testing.expect(!out.is_error);
try std.testing.expect(std.mem.indexOf(u8, out.text, "TAIL_MARKER_PAST_THE_HEAD_CAP") != null);
}
+
+// A workspace's .agents/skills (the cross-tool location Antigravity, Codex and
+// Harbor tasks use) is project tier, and --lean still advertises it.
+test "project .agents/skills loads, reaches the catalog, and keeps `skill` unfolded" {
+ var tmp = std.testing.tmpDir(.{});
+ defer tmp.cleanup();
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const arena = arena_state.allocator();
+ const io = std.testing.io;
+ var buf: [std.fs.max_path_bytes]u8 = undefined;
+ const n = try tmp.dir.realPath(io, &buf);
+ const root = try arena.dupe(u8, buf[0..n]);
+ const dir = try std.fmt.allocPrint(arena, "{s}/.agents/skills/generate-greeting", .{root});
+ try Io.Dir.cwd().createDirPath(io, dir);
+ try Io.Dir.cwd().writeFile(io, .{
+ .sub_path = try std.fmt.allocPrint(arena, "{s}/SKILL.md", .{dir}),
+ .data = "---\nname: generate-greeting\ndescription: Write the greeting file.\n---\n\nWrite the greeting.\n",
+ });
+
+ const list = skill_docs.projectSkills(io, arena, root);
+ try std.testing.expectEqual(@as(usize, 1), list.len);
+ try std.testing.expectEqualStrings("generate-greeting", list[0].name);
+ try std.testing.expect(list[0].source == .project);
+ const catalog = skill_docs.promptCatalog(arena, list);
+ try std.testing.expect(std.mem.indexOf(u8, catalog, "- generate-greeting (project): Write the greeting file.") != null);
+
+ const nlt = @import("no_local_tools.zig");
+ const fold = @import("native_fold.zig");
+ const saved = skill_docs.g_workspace_skills;
+ defer skill_docs.g_workspace_skills = saved;
+ skill_docs.g_workspace_skills = false;
+ try std.testing.expect(!nlt.leanKeeps("skill"));
+ try std.testing.expect(fold.isFolded("skill"));
+ skill_docs.g_workspace_skills = true;
+ try std.testing.expect(nlt.leanKeeps("skill"));
+ try std.testing.expect(!fold.isFolded("skill"));
+ try std.testing.expect(!nlt.leanKeeps("workflow") and fold.isFolded("workflow"));
+}
diff --git a/src/startup.zig b/src/startup.zig
index 5aba65a9..f5b26c26 100644
--- a/src/startup.zig
+++ b/src/startup.zig
@@ -168,6 +168,18 @@ pub fn buildSystemPrompt(
if (skill_catalog.len > 0) {
sys_normal = try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ sys_normal, skill_catalog });
}
+ for (skill_docs.g_skills) |sk| if (sk.source == .project) {
+ skill_docs.g_workspace_skills = true;
+ };
+ } else {
+ // Lean leaves out the personal catalog, but not the skills this
+ // workspace ships: a task that says "use the X skill" must see it.
+ const local = skill_docs.loadProject(io, arena, fleet.g_home);
+ if (local.len > 0) {
+ skill_docs.g_skills = local;
+ skill_docs.g_workspace_skills = true;
+ sys_normal = try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ sys_normal, skill_docs.promptCatalog(arena, local) });
+ }
}
// #326: this returns the composed BASE only. prompts.setSystemPrompts()
// (called once by buildRootAgent, the sole consumer) derives