Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

perf(prompt): empty per-agent skill allowlist on provision

Yuting Zhongb79f0728955d
diff --git a/src/app/(app)/[project]/agents/[agent]/skills/page.tsx b/src/app/(app)/[project]/agents/[agent]/skills/page.tsx
index c45dde54..71d0a4d1 100644
--- a/src/app/(app)/[project]/agents/[agent]/skills/page.tsx
+++ b/src/app/(app)/[project]/agents/[agent]/skills/page.tsx
@@ -2,6 +2,7 @@ import { notFound } from "next/navigation";
import { Card, CardContent } from "@/components/ui/card";
import { getProject } from "@/server/db/projects";
import { resolveAgentBySlug } from "@/server/agent-meta";
+import { readAgentSkillAllowlist } from "@/server/agent-templates";
import { getSkillStatus } from "@/server/openclaw/gateway-rpc";
import { SkillsList } from "@/components/skills-list";
@@ -27,6 +28,12 @@ export default async function AgentSkillsPage({
error = err instanceof Error ? err.message : String(err);
}
+ // Source-of-truth read for the per-agent allowlist. The gateway RPC
+ // returns `agentSkillFilter: []` for both "empty allowlist" (block all)
+ // and "no allowlist" (allow all), which makes the UI lie. Pull from
+ // openclaw.json directly so the page can distinguish the two.
+ const allowlist = await readAgentSkillAllowlist(agentFullId);
+
const skills = report?.skills ?? [];
return (
@@ -36,9 +43,11 @@ export default async function AgentSkillsPage({
<h2 className="text-lg font-semibold tracking-tight">Skills</h2>
<p className="text-sm text-muted-foreground">
Capabilities OpenClaw exposes to {resolved.display_name}.
- {report?.agentSkillFilter?.length
- ? ` Filtered to this agent's allowlist (${report.agentSkillFilter.length}).`
- : " Workspace-wide; no per-agent filter."}
+ {allowlist === undefined
+ ? " Workspace-wide; no per-agent filter."
+ : allowlist.length === 0
+ ? " This agent has an empty allowlist — the model sees zero skills."
+ : ` This agent's allowlist permits ${allowlist.length} skill${allowlist.length === 1 ? "" : "s"}.`}
</p>
</header>
@@ -60,7 +69,11 @@ export default async function AgentSkillsPage({
)}
{!error && skills.length > 0 && (
- <SkillsList skills={skills} agentSlug={agentSlug} />
+ <SkillsList
+ skills={skills}
+ agentSlug={agentSlug}
+ agentAllowlist={allowlist}
+ />
)}
</div>
</div>
diff --git a/src/components/skills-list.tsx b/src/components/skills-list.tsx
index 26554e65..bb6848f2 100644
--- a/src/components/skills-list.tsx
+++ b/src/components/skills-list.tsx
@@ -9,17 +9,27 @@ import { toast } from "sonner";
import type { SkillEntry } from "@/server/openclaw/gateway-rpc";
import { setSkillEnabledAction } from "@/server/actions/skills";
-type FilterKey = "all" | "enabled" | "disabled";
+type FilterKey = "all" | "enabled" | "disabled" | "visible";
const FILTER_LABELS: Record<FilterKey, string> = {
all: "All",
enabled: "Enabled",
disabled: "Disabled",
+ visible: "Visible to model",
};
+
type Props = {
skills: SkillEntry[];
agentSlug: string;
+ /**
+ * Per-agent skill allowlist sourced from openclaw.json (not the gateway
+ * RPC, whose `agentSkillFilter` collapses "empty allowlist" and "no
+ * allowlist" to the same response). `undefined` = no allowlist applied
+ * (allow all enabled). `[]` = empty allowlist (block all). `[...]` =
+ * allow only listed.
+ */
+ agentAllowlist?: string[];
};
/**
@@ -30,24 +40,37 @@ type Props = {
* `eligible`. So our toggle binds to `!disabled`, and we surface ineligibility
* with a side badge instead of locking the switch.
*/
-export function SkillsList({ skills, agentSlug }: Props) {
+export function SkillsList({ skills, agentSlug, agentAllowlist }: Props) {
const [filter, setFilter] = useState<FilterKey>("all");
+ // Decide per skill whether the allowlist blocks it. The truth source is
+ // openclaw.json — we don't trust the RPC's `blockedByAgentFilter` here
+ // because it doesn't differentiate "empty allowlist" from "no allowlist."
+ const isBlockedByAllowlist = useMemo(() => {
+ if (agentAllowlist === undefined) return () => false; // no per-agent filter
+ const set = new Set(agentAllowlist);
+ return (s: SkillEntry) => !set.has(s.skillKey);
+ }, [agentAllowlist]);
+
const counts = useMemo(() => {
let enabled = 0;
let disabled = 0;
+ let visible = 0;
for (const s of skills) {
if (s.disabled) disabled++;
else enabled++;
+ if (!s.disabled && !isBlockedByAllowlist(s)) visible++;
}
- return { all: skills.length, enabled, disabled };
- }, [skills]);
+ return { all: skills.length, enabled, disabled, visible };
+ }, [skills, isBlockedByAllowlist]);
const filtered = useMemo(() => {
if (filter === "all") return skills;
if (filter === "enabled") return skills.filter((s) => !s.disabled);
+ if (filter === "visible")
+ return skills.filter((s) => !s.disabled && !isBlockedByAllowlist(s));
return skills.filter((s) => s.disabled);
- }, [skills, filter]);
+ }, [skills, filter, isBlockedByAllowlist]);
return (
<div className="space-y-4">
@@ -88,7 +111,12 @@ export function SkillsList({ skills, agentSlug }: Props) {
) : (
<ul className="divide-y rounded-lg border bg-card">
{filtered.map((s) => (
- <SkillRow key={s.skillKey} skill={s} agentSlug={agentSlug} />
+ <SkillRow
+ key={s.skillKey}
+ skill={s}
+ agentSlug={agentSlug}
+ blockedByAllowlist={isBlockedByAllowlist(s)}
+ />
))}
</ul>
)}
@@ -96,7 +124,15 @@ export function SkillsList({ skills, agentSlug }: Props) {
);
}
-function SkillRow({ skill, agentSlug }: { skill: SkillEntry; agentSlug: string }) {
+function SkillRow({
+ skill,
+ agentSlug,
+ blockedByAllowlist,
+}: {
+ skill: SkillEntry;
+ agentSlug: string;
+ blockedByAllowlist: boolean;
+}) {
const [pending, startTransition] = useTransition();
// Optimistic flag so the row reflects the toggle instantly while the server
// round-trip + revalidation finishes.
@@ -141,11 +177,20 @@ function SkillRow({ skill, agentSlug }: { skill: SkillEntry; agentSlug: string }
always-on
</Badge>
)}
- {isEnabled && !skill.eligible && (
+ {isEnabled && blockedByAllowlist && (
+ <Badge
+ variant="outline"
+ className="h-4 px-1 text-[9px] uppercase tracking-wide text-muted-foreground"
+ title="Workspace-enabled, but this agent's allowlist excludes it — the model does not see this skill."
+ >
+ excluded for this agent
+ </Badge>
+ )}
+ {isEnabled && !blockedByAllowlist && !skill.eligible && (
<Badge
variant="outline"
className="h-4 px-1 text-[9px] uppercase tracking-wide text-amber-600 dark:text-amber-400"
- title="Enabled in config, but a requirement is missing (binary, allowlist, agent filter)."
+ title="Enabled in config, but a requirement is missing (binary, allowlist)."
>
needs setup
</Badge>
diff --git a/src/server/agent-templates.ts b/src/server/agent-templates.ts
index a0d66efa..21cbbb4e 100644
--- a/src/server/agent-templates.ts
+++ b/src/server/agent-templates.ts
@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
import { homedir } from "node:os";
import { join } from "node:path";
import { openclaw } from "@/server/openclaw/cli";
@@ -248,6 +248,10 @@ export async function ensureProjectAgents(
template_key: template.key,
created_at: new Date().toISOString(),
});
+ // Also idempotent: keep this agent's skill allowlist empty so prompt
+ // size doesn't drift back up after an OpenClaw upgrade re-adds default
+ // skills. See setEmptySkillAllowlist for why.
+ await setEmptySkillAllowlist(name);
existed.push(name);
continue;
}
@@ -276,6 +280,7 @@ export async function ensureProjectAgents(
template_key: template.key,
created_at: new Date().toISOString(),
});
+ await setEmptySkillAllowlist(name);
created.push(name);
} catch (err) {
// Surface but don't crash the loop; partial provisioning recoverable on retry.
@@ -407,6 +412,116 @@ Empty by design — heartbeats are disabled. Cron-driven check-ins
arrive as normal "(task assignment)" turns instead.
`;
+/**
+ * Read this agent's skill allowlist from `~/.openclaw/openclaw.json`. Returns
+ * the array as stored (including an empty array, which is the "block all"
+ * sentinel) or `undefined` when the agent entry has no `skills` field
+ * (OpenClaw's default = "no per-agent filter").
+ *
+ * Why this exists alongside the gateway's `skills.status` RPC: that RPC
+ * doesn't differentiate empty allowlist from absent allowlist on its
+ * response payload, even though the runtime session loader and the
+ * `openclaw skills check` CLI both honor the difference. So the UI can't
+ * rely on the RPC alone to tell the user "this agent sees zero skills."
+ * Reading the source-of-truth JSON gives us an honest answer for the
+ * Skills page header + per-row "excluded for this agent" badges.
+ */
+export async function readAgentSkillAllowlist(
+ agent_id: string,
+): Promise<string[] | undefined> {
+ const cfgPath = join(
+ process.env.OPENCLAW_HOME ?? join(homedir(), ".openclaw"),
+ "openclaw.json",
+ );
+ let raw: string;
+ try {
+ raw = await readFile(cfgPath, "utf8");
+ } catch {
+ return undefined;
+ }
+ let cfg: { agents?: { list?: Array<{ id?: string; skills?: string[] }> } };
+ try {
+ cfg = JSON.parse(raw) as typeof cfg;
+ } catch {
+ return undefined;
+ }
+ const entry = cfg.agents?.list?.find((a) => a?.id === agent_id);
+ return Array.isArray(entry?.skills) ? entry.skills : undefined;
+}
+
+/**
+ * Set this agent's skill allowlist to `[]` inside `~/.openclaw/openclaw.json`.
+ *
+ * Why: OpenClaw bundles a 50+ skill catalog aimed at general-purpose
+ * assistants (1password, apple-notes, blogwatcher, camsnap, discord,
+ * gh-issues, healthcheck, slack, voice-call, etc.). When an agent has no
+ * `skills` field on its config entry, the default is "all visible-by-
+ * default skills are loaded" — which dumps the entire catalog into the
+ * system prompt's nonProjectContext (~5 KB of names + descriptions plus
+ * whatever each skill's instructions are). None of those apply to a
+ * marketing CMO/specialist whose entire tool surface is the orchestration
+ * MCP + the relevant domain MCP (Google Ads, GSC). Setting `skills: []`
+ * tells OpenClaw "this agent is allowed to see zero skills" so the catalog
+ * stops getting injected for this agent.
+ *
+ * We can't pipe this through `openclaw agents add` — there's no
+ * `--skills` flag. The supported escape hatch is `openclaw config patch`
+ * via dot/bracket paths, but those need numeric indices into
+ * `agents.list[]` which shift as agents come and go. A direct
+ * read-modify-write of the JSON file is the most robust option for what
+ * is functionally a single field flip on a known id, and it's idempotent
+ * (re-runs are no-ops once the field is already `[]`).
+ *
+ * Failure is non-fatal: if openclaw.json is missing, the agent entry
+ * isn't there yet, or the write throws, we log and continue. The agent
+ * will work — it just won't get the prompt-size benefit until next
+ * provision.
+ */
+async function setEmptySkillAllowlist(agent_id: string): Promise<void> {
+ const cfgPath = join(
+ process.env.OPENCLAW_HOME ?? join(homedir(), ".openclaw"),
+ "openclaw.json",
+ );
+ let raw: string;
+ try {
+ raw = await readFile(cfgPath, "utf8");
+ } catch (err) {
+ console.warn(
+ `[provision] couldn't read ${cfgPath} to set skills:[] for ${agent_id}:`,
+ err,
+ );
+ return;
+ }
+ let cfg: { agents?: { list?: Array<{ id?: string; skills?: string[] }> } };
+ try {
+ cfg = JSON.parse(raw) as typeof cfg;
+ } catch (err) {
+ console.warn(
+ `[provision] couldn't parse ${cfgPath} to set skills:[] for ${agent_id}:`,
+ err,
+ );
+ return;
+ }
+ const entry = cfg.agents?.list?.find((a) => a?.id === agent_id);
+ if (!entry) {
+ // Race: OpenClaw hasn't flushed the new agent to the config yet.
+ // Skip — the field can be backfilled on the next provision call.
+ return;
+ }
+ if (Array.isArray(entry.skills) && entry.skills.length === 0) {
+ return; // already empty; no write needed
+ }
+ entry.skills = [];
+ try {
+ await writeFile(cfgPath, JSON.stringify(cfg, null, 2), "utf8");
+ } catch (err) {
+ console.warn(
+ `[provision] couldn't write ${cfgPath} to set skills:[] for ${agent_id}:`,
+ err,
+ );
+ }
+}
+
/**
* Overwrite the OpenClaw-default workspace files with minimal stubs.
*