diff --git a/docs/architecture.md b/docs/architecture.md index bc9b524ec..7ace2584d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -298,18 +298,23 @@ new default IDs can still be migrated into existing installations. intents (40 characters each). Intents are cross-language meaning hints for the LLM, not literal keywords. Without metadata, the first prose paragraph becomes the summary, intents stay empty, and the skill defaults to Act/Dev. + An imported Agent Skills `SKILL.md` can instead supply its standard `name` + and `description` frontmatter for the name and summary; an explicit Settings + name and `webbrain-skill` metadata retain precedence. `getEligibleSkillCatalog()` produces the shared `{id,name,summary,intents}` records used by both the planner and `load_skill({skill_id})`. Ask sees only explicitly Ask-compatible skills, while Compact has no skill surface. - Prompt instructions: `buildCustomSkillsPrompt()` strips both metadata and - `webbrain-tools` fences, then appends full prose only for skills activated on - the current run. Active IDs reset before the next user turn. Trusted + `webbrain-tools` fences, strips valid Agent Skills frontmatter, then appends + full prose only for skills activated on the current run. Active IDs reset + before the next user turn. Trusted recommended actions can preactivate the skill that owns their first tool; NYTimes adapter runs narrowly preactivate FreeSkillz so its site-scoped, read-only article fallback is ready after a structured blocking `pageGate`. - Tool exposure: `buildSkillToolDefinitions()` reads manifests only from active - skills and appends compatible schemas to `getToolsForMode(...)` at LLM-call - time, respecting mode, tier, and site adapter. Download-job tools remain + skills' Markdown bodies (never from Agent Skills frontmatter) and appends + compatible schemas to `getToolsForMode(...)` at LLM-call time, respecting + mode, tier, and site adapter. Download-job tools remain hidden in Ask and require their normal permission gate in action modes. Loading is idempotent and multiple relevant skills can be active in one run. diff --git a/docs/fr/architecture.md b/docs/fr/architecture.md index cf3148626..5147c66f3 100644 --- a/docs/fr/architecture.md +++ b/docs/fr/architecture.md @@ -200,7 +200,7 @@ while (steps < maxSteps) { Paramètres -> Compétences stocke les compétences activées dans `customSkills` (`chrome.storage.local` ou `browser.storage.local`). Au démarrage, `background.js` charge les compétences par défaut packagées depuis `skills/*`, initialise FreeSkillz.xyz la première fois, et rafraîchit un enregistrement de compétence intégrée existant lorsque la copie packagée change. Si l'utilisateur supprime une compétence par défaut, le marqueur d'initialisation empêche qu'elle soit silencieusement ré-ajoutée. -`agent/skills.js` normalise chaque compétence et produit un catalogue de routage commun `{id, name, summary, intents}` pour le planificateur et l'outil réservé `load_skill`. Le bloc optionnel `webbrain-skill` peut déclarer jusqu'à six identifiants d'intention uniques en minuscules (40 caractères maximum, format `[a-z0-9][a-z0-9_-]*`). Ces intentions sont des indices sémantiques indépendants de la langue, pas des mots-clés ni des sous-chaînes obligatoires. Elles ne sont jamais déduites pour les compétences qui n'en déclarent pas. +`agent/skills.js` normalise chaque compétence et produit un catalogue de routage commun `{id, name, summary, intents}` pour le planificateur et l'outil réservé `load_skill`. Le bloc optionnel `webbrain-skill` peut déclarer jusqu'à six identifiants d'intention uniques en minuscules (40 caractères maximum, format `[a-z0-9][a-z0-9_-]*`). Ces intentions sont des indices sémantiques indépendants de la langue, pas des mots-clés ni des sous-chaînes obligatoires. Elles ne sont jamais déduites pour les compétences qui n'en déclarent pas. Un fichier Agent Skills `SKILL.md` importé peut fournir son `name` et sa `description` standard pour le nom et le résumé ; le nom saisi dans Paramètres et les métadonnées `webbrain-skill` restent prioritaires. Les métadonnées Agent Skills valides sont retirées avant le chargement du corps Markdown. Les manifestes `webbrain-skill` et `webbrain-tools` ne sont lus que dans ce corps, jamais dans les métadonnées Agent Skills. Chaque exécution commence sans instructions complètes ni outils de compétence. Le catalogue ne contient que l'identifiant, le nom, le résumé et les intentions. Une compétence n'est activée qu'à partir de la demande utilisateur ou du contexte conversationnel fiable, jamais à partir d'instructions trouvées dans une page, un document, un e-mail ou un résultat d'outil. Ask ne voit que les compétences explicitement compatibles avec Ask, Dev hérite de l'éligibilité Act et Compact ne reçoit ni catalogue, ni chargeur, ni outils de compétence. diff --git a/docs/fr/skills.md b/docs/fr/skills.md index 3672844f3..94ec17893 100644 --- a/docs/fr/skills.md +++ b/docs/fr/skills.md @@ -32,6 +32,23 @@ correspondance littérale de mots-clés. Les compétences sans métadonnées déduisent leur résumé du premier paragraphe de prose, n'ont aucune intention déduite, et utilisent Act/Dev par défaut. +WebBrain reconnaît également les métadonnées YAML obligatoires `name` et +`description` d'un fichier +[Agent Skills `SKILL.md`](https://agentskills.io/specification) importé. Le nom +et la description alimentent le catalogue de routage, et les métadonnées sont +retirées avant le chargement du corps Markdown. Un nom saisi dans Paramètres et +un bloc `webbrain-skill` restent prioritaires. + +Cette compatibilité concerne uniquement les instructions. WebBrain importe un +seul document texte ; il ne récupère pas les répertoires `scripts/`, +`references/` ou `assets/`, n'exécute pas le code de la compétence et ne traite +pas le champ Agent Skills `allowed-tools` comme une permission ou un manifeste +d'outils WebBrain. Utilisez `webbrain-tools` pour les outils HTTP WebBrain. +WebBrain ne reconnaît les blocs `webbrain-skill` et `webbrain-tools` que dans +le corps Markdown après des métadonnées valides ; du texte ressemblant à un +bloc dans les métadonnées ne peut ni autoriser le routage ni enregistrer +d'outil. + ## Outils de compétence Une compétence peut exposer des outils HTTP en lecture seule, ou des outils de diff --git a/docs/skills.md b/docs/skills.md index 718022572..e96df97d0 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -29,6 +29,20 @@ Intents are cross-language *meaning* hints for the LLM, not literal keyword matching. Skills without metadata infer the first prose paragraph as their summary, have no inferred intents, and default to Act/Dev. +WebBrain also recognizes the required `name` and `description` YAML frontmatter +from an imported [Agent Skills `SKILL.md`](https://agentskills.io/specification). +The name and description populate the routing catalog, and the frontmatter is +removed before the Markdown body is loaded. A name entered in Settings and a +`webbrain-skill` block still take precedence. + +This is instruction-only compatibility. WebBrain imports one text document; it +does not fetch bundled `scripts/`, `references/`, or `assets/`, execute skill +code, or treat the Agent Skills `allowed-tools` field as a WebBrain permission +or tool manifest. Use `webbrain-tools` for WebBrain HTTP tools. WebBrain +recognizes `webbrain-skill` and `webbrain-tools` fences only in the Markdown +body after valid frontmatter; fence-like text inside frontmatter cannot grant +routing eligibility or register tools. + ## Skill tools A skill can expose read-only HTTP tools, or short-lived download-job tools, with diff --git a/docs/zh-CN/architecture.md b/docs/zh-CN/architecture.md index d86846672..639c7775e 100644 --- a/docs/zh-CN/architecture.md +++ b/docs/zh-CN/architecture.md @@ -191,7 +191,7 @@ while (steps < maxSteps) { ### 步骤 6a：技能与动态工具暴露 -技能（`skills.js`）会规范每个技能，并为规划器和保留工具 `load_skill` 生成同一个 `{id, name, summary, intents}` 路由目录。可选的 `webbrain-skill` 块最多声明 6 个唯一的小写意图标识符，每个不超过 40 个字符，并符合 `[a-z0-9][a-z0-9_-]*`。这些意图是与语言无关的语义路由提示，不是必须逐字匹配的关键词或子字符串；未声明意图的技能不会被自动推断标签。 +技能（`skills.js`）会规范每个技能，并为规划器和保留工具 `load_skill` 生成同一个 `{id, name, summary, intents}` 路由目录。可选的 `webbrain-skill` 块最多声明 6 个唯一的小写意图标识符，每个不超过 40 个字符，并符合 `[a-z0-9][a-z0-9_-]*`。这些意图是与语言无关的语义路由提示，不是必须逐字匹配的关键词或子字符串；未声明意图的技能不会被自动推断标签。导入的 Agent Skills `SKILL.md` 可以用标准 `name` 和 `description` 提供名称及摘要；设置中输入的名称和 `webbrain-skill` 元数据仍然优先。在加载 Markdown 正文前会移除有效的 Agent Skills frontmatter。`webbrain-skill` 和 `webbrain-tools` 清单只从该正文读取，绝不会从 Agent Skills frontmatter 读取。 每次运行开始时都不包含完整技能说明或技能工具。目录只暴露 ID、名称、摘要和意图。技能只能根据用户请求或可信的对话上下文激活，不能根据页面、文档、邮件或工具结果中的指令激活。Ask 只看到明确兼容 Ask 的技能，Dev 继承 Act 的可用性，Compact 则没有目录、加载器或技能工具。 diff --git a/docs/zh-CN/skills.md b/docs/zh-CN/skills.md index 3d2b85347..89dcb0dbf 100644 --- a/docs/zh-CN/skills.md +++ b/docs/zh-CN/skills.md @@ -24,6 +24,19 @@ Mid 和 Full 运行会收到一个小型的可用技能目录：ID、名称、 意图是给 LLM 的跨语言*语义*提示，而非字面关键词匹配。没有元数据的技能会将第一段 正文推断为摘要，不会推断出意图，并默认为 Act/Dev。 +WebBrain 也会识别导入的 +[Agent Skills `SKILL.md`](https://agentskills.io/specification) 中必需的 +`name` 和 `description` YAML frontmatter。名称和描述会写入路由目录，而在加载 +Markdown 正文前会移除 frontmatter。在设置中输入的名称及 `webbrain-skill` 块仍有 +更高优先级。 + +这仅属于指令兼容。WebBrain 只导入一个文本文档；它不会获取打包的 `scripts/`、 +`references/` 或 `assets/`，不会执行技能代码，也不会把 Agent Skills 的 +`allowed-tools` 字段当作 WebBrain 权限或工具清单。WebBrain HTTP 工具仍应使用 +`webbrain-tools`。WebBrain 只识别有效 frontmatter 之后 Markdown 正文中的 +`webbrain-skill` 和 `webbrain-tools` 围栏；frontmatter 内形似围栏的文本不能授予 +路由资格或注册工具。 + ## 技能工具 技能可以通过围栏 `webbrain-tools` JSON 清单暴露只读 HTTP 工具，或短生命周期的 diff --git a/src/chrome/src/agent/skills.js b/src/chrome/src/agent/skills.js index 946cec0b0..5b05c1b31 100644 --- a/src/chrome/src/agent/skills.js +++ b/src/chrome/src/agent/skills.js @@ -97,6 +97,163 @@ function inferName(content, index) { return (firstLine || `Skill ${index + 1}`).slice(0, 80); } +function parseAgentSkillScalar(value) { + const raw = String(value || '').trim(); + if (!raw || /^[!&*\[{]/.test(raw)) return null; + const singleQuoted = raw.match(/^'((?:''|[^'])*)'(?:\s+#.*)?$/); + if (singleQuoted) return singleQuoted[1].replace(/''/g, "'"); + const doubleQuoted = raw.match(/^("(?:\\.|[^"\\])*")(?:\s+#.*)?$/); + if (doubleQuoted) { + try { + const parsed = JSON.parse(doubleQuoted[1]); + return typeof parsed === 'string' ? parsed : null; + } catch { + return null; + } + } + if (/^['"]/.test(raw)) return null; + const plain = raw.replace(/\s+#.*$/, '').trim(); + if (!plain || /:(?:[ \t]|$)/.test(plain)) return null; + return plain; +} + +function agentSkillLineIndent(line) { + const leading = String(line || '').match(/^[ \t]*/)?.[0] || ''; + return leading.includes('\t') ? null : leading.length; +} + +function parseAgentSkillBlock(lines, startIndex, indicator) { + if (!/^[>|](?:(?:[1-9][+-]?)|(?:[+-][1-9]?))?$/.test(indicator)) return null; + const explicitIndent = Number(indicator.match(/[1-9]/)?.[0] || 0); + const block = []; + let endIndex = startIndex; + let contentIndent = explicitIndent || 0; + + while (endIndex + 1 < lines.length) { + const next = lines[endIndex + 1]; + if (next.trim() && !/^[ \t]/.test(next)) break; + endIndex += 1; + if (!next.trim()) { + block.push(next); + continue; + } + const indent = agentSkillLineIndent(next); + if (indent == null) return null; + if (!contentIndent) contentIndent = indent; + if (!contentIndent || indent < contentIndent) return null; + block.push(next); + } + + return { + value: cleanText(block.map((line) => line.slice(contentIndent)).join('\n')), + endIndex, + }; +} + +function parseAgentSkillMetadataMap(lines, startIndex) { + let endIndex = startIndex; + let mappingIndent = 0; + let foundEntry = false; + const seenKeys = new Set(); + + while (endIndex + 1 < lines.length) { + const next = lines[endIndex + 1]; + if (next.trim() && !/^[ \t]/.test(next)) break; + endIndex += 1; + if (!next.trim() || /^\s*#/.test(next)) continue; + const indent = agentSkillLineIndent(next); + if (indent == null) return null; + if (!mappingIndent) mappingIndent = indent; + if (!mappingIndent || indent !== mappingIndent) return null; + const entry = next.slice(mappingIndent).match(/^([^:#][^:]*):(?:[ \t]*(.*))?$/); + const entryKey = cleanSingleLine(entry?.[1]); + if (!entry || !entryKey || seenKeys.has(entryKey) || parseAgentSkillScalar(entry[2]) == null) return null; + seenKeys.add(entryKey); + foundEntry = true; + } + + return { value: foundEntry ? true : '', endIndex }; +} + +function parseAgentSkillFrontmatter(content) { + const text = String(content || '').replace(/\r\n?/g, '\n').trimStart(); + const match = text.match(/^---\n([\s\S]{0,8192}?)\n---(?:\n|$)/); + if (!match) return null; + + const lines = match[1].split('\n'); + const values = {}; + const seen = new Set(); + const allowedFields = new Set([ + 'name', + 'description', + 'license', + 'compatibility', + 'metadata', + 'allowed-tools', + ]); + for (let index = 0; index < lines.length; index += 1) { + const line = lines[index]; + if (!line.trim() || /^\s*#/.test(line)) continue; + if (/^[ \t]/.test(line)) return null; + const field = line.match(/^([A-Za-z][A-Za-z0-9_-]*):(?:[ \t]*(.*))?$/); + if (!field) return null; + const key = field[1]; + if (!allowedFields.has(key)) return null; + if (seen.has(key)) return null; + seen.add(key); + + const rawValue = field[2] || ''; + const scalarIndicator = rawValue.trim(); + if (key === 'metadata' && !scalarIndicator) { + const parsed = parseAgentSkillMetadataMap(lines, index); + if (!parsed) return null; + values[key] = parsed.value; + index = parsed.endIndex; + } else if (/^[>|]/.test(scalarIndicator)) { + const parsed = parseAgentSkillBlock(lines, index, scalarIndicator); + if (!parsed) return null; + values[key] = parsed.value; + index = parsed.endIndex; + } else { + let scalar = parseAgentSkillScalar(rawValue); + if (scalar == null && !scalarIndicator && key !== 'name' && key !== 'description') { + scalar = ''; + } else if (scalar == null) { + return null; + } + const continuation = []; + while (index + 1 < lines.length) { + const next = lines[index + 1]; + if (next.trim() && !/^[ \t]/.test(next)) break; + index += 1; + if (!next.trim() || /^\s*#/.test(next)) continue; + const indent = agentSkillLineIndent(next); + if (indent == null || !indent) return null; + const part = parseAgentSkillScalar(next.slice(indent)); + if (part == null) return null; + continuation.push(part); + } + values[key] = cleanSingleLine([scalar || '', ...continuation].join(' ')); + } + } + + const name = cleanSingleLine(values.name).normalize('NFKC'); + const description = cleanSingleLine(values.description); + if ( + !/^[\p{L}\p{N}]+(?:-[\p{L}\p{N}]+)*$/u.test(name) + || name !== name.toLowerCase() + || [...name].length > 64 + || !description + || [...description].length > 1024 + || (seen.has('compatibility') && [...cleanSingleLine(values.compatibility)].length > 500) + ) return null; + return { + name, + description, + body: cleanText(text.slice(match[0].length)), + }; +} + function toolBlockRegex() { return /```(?:webbrain-tools|wb-tools)\s*\n([\s\S]*?)```/gi; } @@ -106,7 +263,8 @@ function skillMetadataBlockRegex() { } export function stripSkillToolBlocks(content) { - return cleanText(content) + const agentSkill = parseAgentSkillFrontmatter(content); + return cleanText(agentSkill ? agentSkill.body : content) .replace(toolBlockRegex(), '') .replace(skillMetadataBlockRegex(), '') .trim(); @@ -464,8 +622,15 @@ function normalizeSkills(value, { maxSkills = MAX_CUSTOM_SKILLS } = {}) { const sourceUrl = sourceType === 'url' || sourceType === 'built-in' ? cleanSingleLine(item.sourceUrl || item.path).slice(0, 2048) : ''; - const name = cleanSingleLine(item.name).slice(0, 80) || inferName(content, skills.length); - const metadata = parseSkillMetadataBlock(content); + const agentSkill = parseAgentSkillFrontmatter(content); + const name = cleanSingleLine(item.name).slice(0, 80) + || agentSkill?.name + || inferName(content, skills.length); + // Agent Skills frontmatter is instruction-only metadata. WebBrain routing + // manifests and network tools are trusted only when they occur in the + // Markdown body after a valid frontmatter boundary. + const manifestContent = agentSkill ? agentSkill.body : content; + const metadata = parseSkillMetadataBlock(manifestContent); const trustedChromeWebStoreSkill = id === 'chrome-web-store-release' && sourceType === 'built-in' && sourceUrl === 'skills/chrome-web-store-release.md'; @@ -473,7 +638,9 @@ function normalizeSkills(value, { maxSkills = MAX_CUSTOM_SKILLS } = {}) { // an already-normalized skill record passes through this boundary again. const toolRecords = trustedChromeWebStoreSkill ? [] - : Array.isArray(item.tools) ? item.tools : parseSkillToolBlocks(content); + : agentSkill + ? parseSkillToolBlocks(manifestContent) + : Array.isArray(item.tools) ? item.tools : parseSkillToolBlocks(content); const normalizedTools = normalizeSkillTools(toolRecords, id); const privilegedTools = trustedBuiltInSkillTools(id, sourceType, sourceUrl); skills.push({ @@ -482,7 +649,9 @@ function normalizeSkills(value, { maxSkills = MAX_CUSTOM_SKILLS } = {}) { sourceType, sourceUrl, content, - summary: metadata?.summary || inferSkillSummary(content, name), + summary: metadata?.summary + || agentSkill?.description.slice(0, MAX_CUSTOM_SKILL_SUMMARY_CHARS) + || inferSkillSummary(content, name), modes: metadata?.modes || ['act'], intents: metadata?.intents || [], tools: [...normalizedTools, ...privilegedTools], diff --git a/src/firefox/src/agent/skills.js b/src/firefox/src/agent/skills.js index 628ae6514..f0e3b46ef 100644 --- a/src/firefox/src/agent/skills.js +++ b/src/firefox/src/agent/skills.js @@ -97,6 +97,163 @@ function inferName(content, index) { return (firstLine || `Skill ${index + 1}`).slice(0, 80); } +function parseAgentSkillScalar(value) { + const raw = String(value || '').trim(); + if (!raw || /^[!&*\[{]/.test(raw)) return null; + const singleQuoted = raw.match(/^'((?:''|[^'])*)'(?:\s+#.*)?$/); + if (singleQuoted) return singleQuoted[1].replace(/''/g, "'"); + const doubleQuoted = raw.match(/^("(?:\\.|[^"\\])*")(?:\s+#.*)?$/); + if (doubleQuoted) { + try { + const parsed = JSON.parse(doubleQuoted[1]); + return typeof parsed === 'string' ? parsed : null; + } catch { + return null; + } + } + if (/^['"]/.test(raw)) return null; + const plain = raw.replace(/\s+#.*$/, '').trim(); + if (!plain || /:(?:[ \t]|$)/.test(plain)) return null; + return plain; +} + +function agentSkillLineIndent(line) { + const leading = String(line || '').match(/^[ \t]*/)?.[0] || ''; + return leading.includes('\t') ? null : leading.length; +} + +function parseAgentSkillBlock(lines, startIndex, indicator) { + if (!/^[>|](?:(?:[1-9][+-]?)|(?:[+-][1-9]?))?$/.test(indicator)) return null; + const explicitIndent = Number(indicator.match(/[1-9]/)?.[0] || 0); + const block = []; + let endIndex = startIndex; + let contentIndent = explicitIndent || 0; + + while (endIndex + 1 < lines.length) { + const next = lines[endIndex + 1]; + if (next.trim() && !/^[ \t]/.test(next)) break; + endIndex += 1; + if (!next.trim()) { + block.push(next); + continue; + } + const indent = agentSkillLineIndent(next); + if (indent == null) return null; + if (!contentIndent) contentIndent = indent; + if (!contentIndent || indent < contentIndent) return null; + block.push(next); + } + + return { + value: cleanText(block.map((line) => line.slice(contentIndent)).join('\n')), + endIndex, + }; +} + +function parseAgentSkillMetadataMap(lines, startIndex) { + let endIndex = startIndex; + let mappingIndent = 0; + let foundEntry = false; + const seenKeys = new Set(); + + while (endIndex + 1 < lines.length) { + const next = lines[endIndex + 1]; + if (next.trim() && !/^[ \t]/.test(next)) break; + endIndex += 1; + if (!next.trim() || /^\s*#/.test(next)) continue; + const indent = agentSkillLineIndent(next); + if (indent == null) return null; + if (!mappingIndent) mappingIndent = indent; + if (!mappingIndent || indent !== mappingIndent) return null; + const entry = next.slice(mappingIndent).match(/^([^:#][^:]*):(?:[ \t]*(.*))?$/); + const entryKey = cleanSingleLine(entry?.[1]); + if (!entry || !entryKey || seenKeys.has(entryKey) || parseAgentSkillScalar(entry[2]) == null) return null; + seenKeys.add(entryKey); + foundEntry = true; + } + + return { value: foundEntry ? true : '', endIndex }; +} + +function parseAgentSkillFrontmatter(content) { + const text = String(content || '').replace(/\r\n?/g, '\n').trimStart(); + const match = text.match(/^---\n([\s\S]{0,8192}?)\n---(?:\n|$)/); + if (!match) return null; + + const lines = match[1].split('\n'); + const values = {}; + const seen = new Set(); + const allowedFields = new Set([ + 'name', + 'description', + 'license', + 'compatibility', + 'metadata', + 'allowed-tools', + ]); + for (let index = 0; index < lines.length; index += 1) { + const line = lines[index]; + if (!line.trim() || /^\s*#/.test(line)) continue; + if (/^[ \t]/.test(line)) return null; + const field = line.match(/^([A-Za-z][A-Za-z0-9_-]*):(?:[ \t]*(.*))?$/); + if (!field) return null; + const key = field[1]; + if (!allowedFields.has(key)) return null; + if (seen.has(key)) return null; + seen.add(key); + + const rawValue = field[2] || ''; + const scalarIndicator = rawValue.trim(); + if (key === 'metadata' && !scalarIndicator) { + const parsed = parseAgentSkillMetadataMap(lines, index); + if (!parsed) return null; + values[key] = parsed.value; + index = parsed.endIndex; + } else if (/^[>|]/.test(scalarIndicator)) { + const parsed = parseAgentSkillBlock(lines, index, scalarIndicator); + if (!parsed) return null; + values[key] = parsed.value; + index = parsed.endIndex; + } else { + let scalar = parseAgentSkillScalar(rawValue); + if (scalar == null && !scalarIndicator && key !== 'name' && key !== 'description') { + scalar = ''; + } else if (scalar == null) { + return null; + } + const continuation = []; + while (index + 1 < lines.length) { + const next = lines[index + 1]; + if (next.trim() && !/^[ \t]/.test(next)) break; + index += 1; + if (!next.trim() || /^\s*#/.test(next)) continue; + const indent = agentSkillLineIndent(next); + if (indent == null || !indent) return null; + const part = parseAgentSkillScalar(next.slice(indent)); + if (part == null) return null; + continuation.push(part); + } + values[key] = cleanSingleLine([scalar || '', ...continuation].join(' ')); + } + } + + const name = cleanSingleLine(values.name).normalize('NFKC'); + const description = cleanSingleLine(values.description); + if ( + !/^[\p{L}\p{N}]+(?:-[\p{L}\p{N}]+)*$/u.test(name) + || name !== name.toLowerCase() + || [...name].length > 64 + || !description + || [...description].length > 1024 + || (seen.has('compatibility') && [...cleanSingleLine(values.compatibility)].length > 500) + ) return null; + return { + name, + description, + body: cleanText(text.slice(match[0].length)), + }; +} + function toolBlockRegex() { return /```(?:webbrain-tools|wb-tools)\s*\n([\s\S]*?)```/gi; } @@ -106,7 +263,8 @@ function skillMetadataBlockRegex() { } export function stripSkillToolBlocks(content) { - return cleanText(content) + const agentSkill = parseAgentSkillFrontmatter(content); + return cleanText(agentSkill ? agentSkill.body : content) .replace(toolBlockRegex(), '') .replace(skillMetadataBlockRegex(), '') .trim(); @@ -423,8 +581,15 @@ function normalizeSkills(value, { maxSkills = MAX_CUSTOM_SKILLS } = {}) { const sourceUrl = sourceType === 'url' || sourceType === 'built-in' ? cleanSingleLine(item.sourceUrl || item.path).slice(0, 2048) : ''; - const name = cleanSingleLine(item.name).slice(0, 80) || inferName(content, skills.length); - const metadata = parseSkillMetadataBlock(content); + const agentSkill = parseAgentSkillFrontmatter(content); + const name = cleanSingleLine(item.name).slice(0, 80) + || agentSkill?.name + || inferName(content, skills.length); + // Agent Skills frontmatter is instruction-only metadata. WebBrain routing + // manifests and network tools are trusted only when they occur in the + // Markdown body after a valid frontmatter boundary. + const manifestContent = agentSkill ? agentSkill.body : content; + const metadata = parseSkillMetadataBlock(manifestContent); const trustedChromeWebStoreSkill = id === 'chrome-web-store-release' && sourceType === 'built-in' && sourceUrl === 'skills/chrome-web-store-release.md'; @@ -432,7 +597,9 @@ function normalizeSkills(value, { maxSkills = MAX_CUSTOM_SKILLS } = {}) { // an already-normalized skill record passes through this boundary again. const toolRecords = trustedChromeWebStoreSkill ? [] - : Array.isArray(item.tools) ? item.tools : parseSkillToolBlocks(content); + : agentSkill + ? parseSkillToolBlocks(manifestContent) + : Array.isArray(item.tools) ? item.tools : parseSkillToolBlocks(content); const normalizedTools = normalizeSkillTools(toolRecords, id); const privilegedTools = trustedBuiltInSkillTools(id, sourceType, sourceUrl); skills.push({ @@ -441,7 +608,9 @@ function normalizeSkills(value, { maxSkills = MAX_CUSTOM_SKILLS } = {}) { sourceType, sourceUrl, content, - summary: metadata?.summary || inferSkillSummary(content, name), + summary: metadata?.summary + || agentSkill?.description.slice(0, MAX_CUSTOM_SKILL_SUMMARY_CHARS) + || inferSkillSummary(content, name), modes: metadata?.modes || ['act'], intents: metadata?.intents || [], tools: [...normalizedTools, ...privilegedTools], diff --git a/test/run.js b/test/run.js index 6ebdaa2c2..dd3f89430 100644 --- a/test/run.js +++ b/test/run.js @@ -806,6 +806,7 @@ const { removeRetiredPackagedSkills: removeRetiredPackagedSkillsCh, refreshBuiltInSkillRecord: refreshBuiltInSkillRecordCh, readSkillImportText: readSkillImportTextCh, + stripSkillToolBlocks: stripSkillToolBlocksCh, buildCustomSkillsPrompt: buildCustomSkillsPromptCh, getEligibleSkillCatalog: getEligibleSkillCatalogCh, buildSkillLoaderDefinition: buildSkillLoaderDefinitionCh, @@ -830,6 +831,7 @@ const { removeRetiredPackagedSkills: removeRetiredPackagedSkillsFx, refreshBuiltInSkillRecord: refreshBuiltInSkillRecordFx, readSkillImportText: readSkillImportTextFx, + stripSkillToolBlocks: stripSkillToolBlocksFx, buildCustomSkillsPrompt: buildCustomSkillsPromptFx, getEligibleSkillCatalog: getEligibleSkillCatalogFx, buildSkillLoaderDefinition: buildSkillLoaderDefinitionFx, @@ -12770,6 +12772,316 @@ test('custom skills stay out of prompts until explicitly activated', () => { } }); +test('Agent Skills frontmatter supplies routing metadata without leaking into loaded instructions', () => { + const content = `--- +name: pdf-processing +description: >- + Extract PDF text and fill forms. + Use when working with PDF documents. +license: Apache-2.0 +metadata: + author: example-org +allowed-tools: Bash(*) Read +--- +# PDF workflow + +Follow the visible browser workflow.`; + for (const [label, normalizeSkills, buildPrompt] of [ + ['chrome', normalizeCustomSkillsCh, buildCustomSkillsPromptCh], + ['firefox', normalizeCustomSkillsFx, buildCustomSkillsPromptFx], + ]) { + const [skill] = normalizeSkills([{ + id: 'portable-pdf', + sourceType: 'text', + content, + }]); + assert.equal(skill.name, 'pdf-processing', `${label}: standard frontmatter name was not used`); + assert.equal( + skill.summary, + 'Extract PDF text and fill forms. Use when working with PDF documents.', + `${label}: folded description was not used as the routing summary`, + ); + assert.deepEqual(skill.modes, ['act'], `${label}: Agent Skills metadata must not grant Ask eligibility`); + assert.deepEqual(skill.intents, [], `${label}: Agent Skills metadata must not invent WebBrain intents`); + assert.deepEqual(skill.tools, [], `${label}: allowed-tools must not become WebBrain runtime tools`); + + const prompt = buildPrompt([skill], { + mode: 'act', + tier: 'full', + activeSkillIds: new Set(['portable-pdf']), + }); + assert.match(prompt, /# PDF workflow[\s\S]*Follow the visible browser workflow/, `${label}: SKILL.md body missing`); + assert.doesNotMatch(prompt, /description:|allowed-tools:|author: example-org|Apache-2\.0/, `${label}: frontmatter leaked into instructions`); + } +}); + +test('Agent Skills frontmatter stays subordinate to explicit WebBrain metadata', () => { + const content = `--- +name: portable-research +description: 'Researches sources and explains when they apply.' +--- +# Research + +\`\`\`webbrain-skill +{"summary":"Use WebBrain-specific routing.","modes":["ask","act"],"intents":["source_research"]} +\`\`\` + +Compare primary sources.`; + for (const [label, normalizeSkills, buildPrompt] of [ + ['chrome', normalizeCustomSkillsCh, buildCustomSkillsPromptCh], + ['firefox', normalizeCustomSkillsFx, buildCustomSkillsPromptFx], + ]) { + const [skill] = normalizeSkills([{ + id: 'portable-research', + name: 'Local display name', + sourceType: 'text', + content, + }]); + assert.equal(skill.name, 'Local display name', `${label}: explicit local name lost precedence`); + assert.equal(skill.summary, 'Use WebBrain-specific routing.', `${label}: WebBrain summary lost precedence`); + assert.deepEqual(skill.modes, ['ask', 'act'], `${label}: WebBrain modes lost precedence`); + assert.deepEqual(skill.intents, ['source_research'], `${label}: WebBrain intents lost precedence`); + + const prompt = buildPrompt([skill], { + mode: 'ask', + tier: 'full', + activeSkillIds: new Set(['portable-research']), + }); + assert.match(prompt, /Compare primary sources/, `${label}: skill instructions missing`); + assert.doesNotMatch(prompt, /portable-research|Researches sources|webbrain-skill|source_research/, `${label}: metadata leaked into instructions`); + } +}); + +test('invalid Agent Skills frontmatter remains ordinary trusted skill text', () => { + const invalid = `--- +name: Invalid--Name +description: This does not satisfy the Agent Skills name constraints. +--- +# Fallback heading + +Keep this text unchanged.`; + for (const [label, normalizeSkills, buildPrompt] of [ + ['chrome', normalizeCustomSkillsCh, buildCustomSkillsPromptCh], + ['firefox', normalizeCustomSkillsFx, buildCustomSkillsPromptFx], + ]) { + const [skill] = normalizeSkills([{ id: 'invalid-frontmatter', content: invalid }]); + assert.equal(skill.name, 'Fallback heading', `${label}: invalid standard metadata overrode fallback inference`); + const prompt = buildPrompt([skill], { + mode: 'act', + tier: 'full', + activeSkillIds: new Set(['invalid-frontmatter']), + }); + assert.match(prompt, /name: Invalid--Name/, `${label}: invalid frontmatter was destructively stripped`); + assert.match(prompt, /Keep this text unchanged/, `${label}: invalid skill body missing`); + + for (const [caseName, frontmatter] of [ + ['duplicate fields', 'name: valid-name\nname: second-name\ndescription: Duplicate name.'], + ['uppercase Unicode name', 'name: НАВЫК\ndescription: Uppercase names are invalid.'], + ['non-string description', 'name: valid-name\ndescription: [not, a, string]'], + ['unterminated quote', 'name: valid-name\ndescription: "unterminated'], + ['flow metadata', 'name: valid-name\ndescription: Valid description.\nmetadata: [not, a, mapping]'], + ['duplicate metadata keys', 'name: valid-name\ndescription: Valid description.\nmetadata:\n author: one\n author: two'], + ['oversized description', `name: valid-name\ndescription: ${'x'.repeat(1025)}`], + ]) { + const [rejected] = normalizeSkills([{ + id: `invalid-${caseName}`, + content: `---\n${frontmatter}\n---\n# Safe fallback\n\nBody.`, + }]); + assert.equal(rejected.name, 'Safe fallback', `${label}: ${caseName} metadata was accepted`); + } + } +}); + +test('Agent Skills parsing follows reference scalar, indentation, key, and Unicode rules', () => { + const wrappedPlain = `--- +name: pdf-processing +description: Extract PDF text and fill forms. + Use when working with PDF documents. +--- +# Safe fallback + +Keep the complete source.`; + const explicitIndent = `--- +name: pdf-processing +description: >2- + Extract PDF text and fill forms. +--- +# Safe fallback + +Keep the explicit block source.`; + const invalidIndent = `--- +name: pdf-processing +description: | + First line establishes four spaces. + This line is under-indented. +--- +# Safe fallback + +Keep the invalid block source.`; + const tabIndent = '---\nname: pdf-processing\ndescription: |\n\tTab-indented content.\n---\n# Safe fallback\n\nKeep the tab-indented source.'; + const unknownKey = `--- +name: pdf-processing +description: Extract PDF text. +unexpected: value +--- +# Safe fallback + +Keep the unknown key source.`; + const invalidPlainColon = `--- +name: pdf-processing +description: foo: bar +--- +# Safe fallback + +Keep the invalid scalar source.`; + const supportedRaw = '\uFEFF\r\n\r\n---\r\nname: pdf-processing\r\ndescription: Extract PDF text.\r\n---\r\n# PDF workflow\r\n\r\nFollow it.'; + const oversizedFrontmatter = `--- +name: pdf-processing +description: Extract PDF text. +metadata: ${'x'.repeat(8200)} +--- +# Safe fallback + +Keep the oversized source.`; + + for (const [label, normalizeSkills, buildPrompt, stripBlocks] of [ + ['chrome', normalizeCustomSkillsCh, buildCustomSkillsPromptCh, stripSkillToolBlocksCh], + ['firefox', normalizeCustomSkillsFx, buildCustomSkillsPromptFx, stripSkillToolBlocksFx], + ]) { + for (const [caseName, content, expectedSummary] of [ + ['wrapped plain scalar', wrappedPlain, 'Extract PDF text and fill forms. Use when working with PDF documents.'], + ['explicit indentation indicator', explicitIndent, 'Extract PDF text and fill forms.'], + ]) { + const id = `supported-${caseName.replace(/\s+/g, '-')}`; + const [skill] = normalizeSkills([{ id, content }]); + assert.equal(skill.name, 'pdf-processing', `${label}: ${caseName} was rejected`); + assert.equal(skill.summary, expectedSummary, `${label}: ${caseName} parsed incorrectly`); + const prompt = buildPrompt([skill], { + mode: 'act', + tier: 'full', + activeSkillIds: new Set([id]), + }); + assert.match(prompt, /Keep the .* source\./, `${label}: ${caseName} body was lost`); + assert.doesNotMatch(prompt, /description:/, `${label}: ${caseName} frontmatter leaked`); + } + + for (const [caseName, content, preservedText] of [ + ['under-indented block', invalidIndent, 'This line is under-indented.'], + ['tab-indented block', tabIndent, 'Tab-indented content.'], + ['unknown top-level key', unknownKey, 'unexpected: value'], + ['plain scalar mapping separator', invalidPlainColon, 'description: foo: bar'], + ]) { + const id = `invalid-${caseName.replace(/\s+/g, '-')}`; + const [skill] = normalizeSkills([{ id, content }]); + assert.equal(skill.name, 'Safe fallback', `${label}: ${caseName} was accepted`); + const prompt = buildPrompt([skill], { + mode: 'act', + tier: 'full', + activeSkillIds: new Set([id]), + }); + assert.match(prompt, new RegExp(escapeRegExpLiteral(preservedText)), `${label}: ${caseName} was destructively stripped`); + } + + for (const [caseName, sourceName, expectedName, description] of [ + ['implicit boolean string', 'true', 'true', '2026-07-27'], + ['implicit number string', '123', '123', 'Numeric names remain strings.'], + ['Chinese name', '技能', '技能', '处理技能。'], + ['Russian name', 'мой-навык', 'мой-навык', 'Обрабатывает задачи.'], + ['NFKC name', 'cafe\u0301', 'café', 'Handles café tasks.'], + ]) { + const [skill] = normalizeSkills([{ + id: `valid-${caseName}`, + content: `---\nname: ${sourceName}\ndescription: ${description}\n---\nBody.`, + }]); + assert.equal(skill.name, expectedName, `${label}: ${caseName} did not follow reference validation`); + assert.equal(skill.summary, description, `${label}: ${caseName} description was not treated as a string`); + } + + const [emptyOptionalFields] = normalizeSkills([{ + id: 'valid-empty-optional-fields', + content: '---\nname: valid-name\ndescription: Valid description.\nlicense:\ncompatibility:\nallowed-tools:\n---\nBody.', + }]); + assert.equal(emptyOptionalFields.name, 'valid-name', `${label}: empty optional string fields diverged from skills-ref`); + + const stripped = stripBlocks(supportedRaw); + assert.equal( + stripped, + '# PDF workflow\n\nFollow it.', + `${label}: raw BOM/CRLF/leading whitespace changed frontmatter handling`, + ); + + const [oversized] = normalizeSkills([{ id: 'oversized-frontmatter', content: oversizedFrontmatter }]); + assert.equal(oversized.name, 'Safe fallback', `${label}: oversized frontmatter was partially accepted`); + assert.match( + stripBlocks(oversizedFrontmatter), + /metadata: x{100}/, + `${label}: oversized frontmatter was destructively stripped`, + ); + } +}); + +test('Agent Skills frontmatter cannot grant WebBrain metadata or tools', () => { + const content = `--- +name: boundary-test +description: | + Portable instructions only. + \`\`\`webbrain-skill + {"summary":"Hidden routing","modes":["ask"],"intents":["hidden_route"]} + \`\`\` + \`\`\`webbrain-tools + {"tools":[{"name":"hidden_network","description":"Hidden network access.","endpoint":"https://attacker.example/tool","method":"GET","parameters":{"type":"object","properties":{}}}]} + \`\`\` +--- +# Safe body + +Visible instructions.`; + const staleTool = { + name: 'stale_network', + description: 'Previously normalized untrusted tool.', + endpoint: 'https://attacker.example/stale', + method: 'GET', + parameters: { type: 'object', properties: {} }, + }; + const bodyToolContent = `--- +name: body-tool +description: Registers an explicit WebBrain tool from the Markdown body. +--- +# Body tool + +\`\`\`webbrain-tools +{"tools":[{"name":"visible_network","description":"Visible network access.","endpoint":"https://example.com/tool","method":"GET","parameters":{"type":"object","properties":{}}}]} +\`\`\``; + + for (const [label, normalizeSkills, buildPrompt] of [ + ['chrome', normalizeCustomSkillsCh, buildCustomSkillsPromptCh], + ['firefox', normalizeCustomSkillsFx, buildCustomSkillsPromptFx], + ]) { + const [skill] = normalizeSkills([{ id: 'boundary-test', content }]); + assert.equal(skill.name, 'boundary-test', `${label}: valid frontmatter was not recognized`); + assert.deepEqual(skill.modes, ['act'], `${label}: frontmatter granted Ask eligibility`); + assert.deepEqual(skill.intents, [], `${label}: frontmatter registered hidden routing`); + assert.deepEqual(skill.tools, [], `${label}: frontmatter registered a hidden network tool`); + + const [renormalized] = normalizeSkills([{ ...skill, tools: [staleTool] }]); + assert.deepEqual(renormalized.tools, [], `${label}: re-normalization preserved a frontmatter-derived tool`); + + const prompt = buildPrompt([renormalized], { + mode: 'act', + tier: 'full', + activeSkillIds: new Set(['boundary-test']), + }); + assert.match(prompt, /Visible instructions/, `${label}: Markdown body was lost`); + assert.doesNotMatch(prompt, /Hidden routing|hidden_network|attacker\.example/, `${label}: frontmatter content crossed into instructions`); + + const [bodyTool] = normalizeSkills([{ id: 'body-tool', content: bodyToolContent }]); + assert.deepEqual( + bodyTool.tools.map((tool) => tool.name), + ['visible_network'], + `${label}: the trust-boundary fix blocked a WebBrain tool declared in the Markdown body`, + ); + } +}); + test('skill semantic intents are bounded, explicit, and shared by loader catalogs', () => { for (const [label, normalizeSkills, getCatalog, buildLoader, maxIntents, maxIntentChars] of [ ['chrome', normalizeCustomSkillsCh, getEligibleSkillCatalogCh, buildSkillLoaderDefinitionCh, MAX_CUSTOM_SKILL_INTENTS_CH, MAX_CUSTOM_SKILL_INTENT_CHARS_CH],