The Open Framework for Building Agents
fix: accept portable skill frontmatter (#1648)
Casey Gowrie7fa4d36a94f4
diff --git a/.changeset/quiet-skills-travel.md b/.changeset/quiet-skills-travel.mdnew file mode 100644index 000000000..dc3c1b1f4--- /dev/null+++ b/.changeset/quiet-skills-travel.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Accept unmodeled `SKILL.md` frontmatter when importing a skill from another runtime. These fields are no-ops in eve.diff --git a/docs/skills.mdx b/docs/skills.mdxindex 5de3eac0b..cf468b44d 100644--- a/docs/skills.mdx+++ b/docs/skills.mdx@@ -40,6 +40,8 @@ When the task is novel or ambiguous, gather evidence first, then answer with thekey facts and the remaining uncertainty.```+eve reads `description`, optional `license`, and string `metadata`; other `SKILL.md` frontmatter is accepted as a no-op.+When markdown can't express what you need (typed values, generated content, or inline sibling files), author the skill in TypeScript with `defineSkill` from `eve/skills`:```ts title="agent/skills/research.ts"diff --git a/packages/eve/src/discover/skills.integration.test.ts b/packages/eve/src/discover/skills.integration.test.tsindex 6a1e3ebe3..5c6971282 100644--- a/packages/eve/src/discover/skills.integration.test.ts+++ b/packages/eve/src/discover/skills.integration.test.ts@@ -145,11 +145,9 @@ describe("discoverSkills (memory)", () => {]);});- it("reports frontmatter validation failures while silently ignoring authored name fields", async () => {- // Skill identity is path-derived, but the broader Agent Skills format- // commonly includes a `name` field in SKILL.md / flat skill frontmatter.- // We accept and drop the value rather than rejecting otherwise-valid- // skill markdown.+ it("reports used-frontmatter validation failures while accepting unmodeled frontmatter", async () => {+ // Frontmatter that eve does not model must not block importing a shared+ // SKILL.md from another runtime.const project = buildMemoryAgentProject({agentFiles: {"skills/bad-skill/SKILL.md": ["---", "description: 42", "---", "Broken frontmatter."].join(@@ -159,6 +157,8 @@ describe("discoverSkills (memory)", () => {"---","name: other-name","description: Use the weather tool before answering forecast questions.",+ "argument-hint: '[location]'",+ "disable-model-invocation: true","---","When the user asks about weather, call the weather tool before answering.",].join("\n"),@@ -166,6 +166,8 @@ describe("discoverSkills (memory)", () => {"---","name: other-name","description: Research complex weather questions.",+ "argument-hint: '[topic]'",+ "disable-model-invocation: true","---","Research weather patterns before replying.",].join("\n"),diff --git a/packages/eve/src/internal/helpers/markdown.test.ts b/packages/eve/src/internal/helpers/markdown.test.tsindex 7a7d866c9..e3d354151 100644--- a/packages/eve/src/internal/helpers/markdown.test.ts+++ b/packages/eve/src/internal/helpers/markdown.test.ts@@ -54,13 +54,15 @@ Research complex weather questions before replying.`;);});- it("silently ignores authored name fields in skill markdown frontmatter", () => {- // SKILL.md files in the broader Agent Skills ecosystem typically declare- // `name`; eve derives identity from the file path, so we accept and drop- // the field rather than rejecting otherwise-valid skill markdown.+ it("ignores unmodeled skill frontmatter", () => {const markdown = `---name: get-weatherdescription: Use the weather tool before answering forecast questions.+allowed-tools: Bash Read+argument-hint: "[city]"+compatibility: Requires a weather API key.+disable-model-invocation: true+user-invocable: false---When the user asks about weather, call the weather tool before answering.`;@@ -91,14 +93,19 @@ Research complex weather questions before replying.`;);});- it("rejects unsupported frontmatter fields in skills instead of silently dropping them", () => {- expect(() =>+ it("treats unknown skill frontmatter as a no-op", () => {+ expect(lowerSkillMarkdown(`---description: Use the weather tool before answering forecast questions.category: routing---When the user asks about weather, call the weather tool before answering.`),- ).toThrow("Expected authored skill markdown to match the public eve shape.");+ ).toEqual(+ defineSkill({+ description: "Use the weather tool before answering forecast questions.",+ markdown: "When the user asks about weather, call the weather tool before answering.",+ }),+ );});it("derives flat skill metadata from plain markdown when no frontmatter is present", () => {diff --git a/packages/eve/src/internal/helpers/markdown.ts b/packages/eve/src/internal/helpers/markdown.tsindex 6a01bd316..28f8fdfa7 100644--- a/packages/eve/src/internal/helpers/markdown.ts+++ b/packages/eve/src/internal/helpers/markdown.ts@@ -94,17 +94,6 @@ interface LowerSkillMarkdownInput {readonly slug?: string;}-/**- * Lowers authored skill markdown into the shared public definition shape.- *- * Supports both packaged skill files (`SKILL.md` inside a skill- * directory; description comes from frontmatter) and flat skill files- * (`<name>.md` next to other skills; description may be derived from- * the markdown body). Identity is path-derived, so an authored `name`- * frontmatter field is silently ignored — `SKILL.md` files commonly- * carry one for compatibility with the broader Agent Skills ecosystem,- * and we accept it without using it rather than rejecting the file.- *//*** Lowers an authored schedule markdown file into the shared public* definition shape. The frontmatter must contain `cron`. The body@@ -140,6 +129,14 @@ export function lowerScheduleMarkdown(source: string): ScheduleDefinition {);}+/**+ * Lowers authored skill markdown into the shared public definition shape.+ *+ * Supports both packaged skill files (`SKILL.md` inside a skill directory;+ * description comes from frontmatter) and flat skill files (`<name>.md` next+ * to other skills; description may be derived from the markdown body).+ * Identity is path-derived, and frontmatter that eve does not use is a no-op.+ */export function lowerSkillMarkdown(source: string,input: LowerSkillMarkdownInput = {},@@ -151,7 +148,7 @@ export function lowerSkillMarkdown(throw new Error("Skill markdown must start with YAML frontmatter.");}- const frontmatter = stripIgnoredSkillFrontmatterKeys(document.frontmatter);+ const frontmatter = document.frontmatter;const frontmatterDescription = toOptionalString(frontmatter.description, "description");const description =@@ -162,7 +159,6 @@ export function lowerSkillMarkdown(deriveFlatSkillDescription(document.markdown, slug));const rawDefinition: Record<string, unknown> = {- ...frontmatter,description,markdown: document.markdown,};@@ -204,24 +200,6 @@ function applyOptionalSkillFrontmatter(}}-/**- * Removes frontmatter keys that the broader Agent Skills format permits but- * eve deliberately does not consume. Skill identity is path-derived, so an- * authored `name` is meaningless to eve; we drop it silently rather than- * letting it surface as an unknown-key error during normalization.- */-const IGNORED_SKILL_FRONTMATTER_KEYS = ["name"];--function stripIgnoredSkillFrontmatterKeys(- frontmatter: Record<string, unknown>,-): Record<string, unknown> {- let stripped: Record<string, unknown> = { ...frontmatter };- for (const key of IGNORED_SKILL_FRONTMATTER_KEYS) {- delete stripped[key];- }- return stripped;-}-function toOptionalString(value: unknown, fieldName: string): string | undefined {if (value === undefined || value === null) {return undefined;