From acc4b4e7eee8d5d870639e65d2192204cfaccc6a Mon Sep 17 00:00:00 2001 From: Ziyang Guo <121015044+RerankerGuo@users.noreply.github.com> Date: Mon, 13 Jul 2026 13:18:46 +0800 Subject: [PATCH] fix: align generated skill guidance --- apps/memos-local-openclaw/src/skill/generator.ts | 12 ++++++++---- .../tests/skill-prompt-policy.test.ts | 10 ++++++++++ packages/memos-core/src/skill/generator.ts | 12 ++++++++---- 3 files changed, 26 insertions(+), 8 deletions(-) diff --git a/apps/memos-local-openclaw/src/skill/generator.ts b/apps/memos-local-openclaw/src/skill/generator.ts index b1b77578e..a5e6373ea 100644 --- a/apps/memos-local-openclaw/src/skill/generator.ts +++ b/apps/memos-local-openclaw/src/skill/generator.ts @@ -28,6 +28,13 @@ This Skill is special: it comes from real execution experience — every step wa - The frontmatter description (~100 words) is ALWAYS in the agent's context — it must be self-sufficient for deciding whether to use this skill. - The SKILL.md body loads when triggered — keep it under 400 lines, focused, no fluff. - If the task involved large configs/scripts, mention them but DON'T inline everything — just reference that scripts/ or references/ may contain them. +- For multi-variant skills, keep only the shared workflow and variant-selection guidance in SKILL.md; move framework-, provider-, or domain-specific details into separate references/ files. +- Do not create README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or other standalone documentation. A skill consists of SKILL.md plus only the scripts/, references/, or assets/ companions it genuinely needs. + +### Frontmatter rules +- name: Use 2-4 words in English kebab-case so the identifier stays concise. +- description: Include both what the skill does and when to use it, with concrete scenarios, keywords, and alternative phrasings because this is the primary trigger. +- Include ONLY \`name\` and \`description\` in frontmatter; do not add metadata or other fields. ### Description as trigger mechanism The description field decides whether the agent activates this skill. Write it "proactively": @@ -45,6 +52,7 @@ The description field decides whether the agent activates this skill. Write it " - Abstract the mistake, not just the fix: capture the diagnostic method that found the problem, not only the specific error message or patch from this task - Do not make a specific project name, product version, branch, or one-off rollback decision a required part of the skill unless the future task truly depends on it - Keep real commands/code/config from the task record — these are verified to work +- Only include information the agent does not already know; omit generic explanations that add tokens without improving execution. ### Language matching (CRITICAL) You MUST write the ENTIRE skill in the SAME language as the user's messages in the task record. @@ -63,16 +71,12 @@ Output ONLY the complete SKILL.md content. No extra text before or after. --- name: "{NAME}" description: "{A natural, proactive description. 60-120 words. Cover what it does + multiple phrasings/scenarios that should trigger it. Be pushy about triggering — list keywords, alternative descriptions, edge-case phrasings.}" -metadata: {{ "openclaw": {{ "emoji": "{emoji}" }} }} --- # {Title — clear, action-oriented} {One sentence: what this skill helps you do and why it's valuable} -## When to use this skill -{2-4 bullet points describing the scenarios. Focus on the user's INTENT, not just keywords. Example: "When you need to get a Node app running reliably in a container and want to avoid common pitfalls like bloated images or missing health checks."} - ## Steps {Numbered or sectioned steps extracted from the task. EVERY step actually performed must be included — do NOT skip or generalize away concrete steps like "configure security groups", "set environment variables", etc. For each step: 1. What to do (keep inline code short — if a step involves a long script or config, write a brief summary here and say "see scripts/ for the complete script") diff --git a/apps/memos-local-openclaw/tests/skill-prompt-policy.test.ts b/apps/memos-local-openclaw/tests/skill-prompt-policy.test.ts index 3969c8933..8ba2015e7 100644 --- a/apps/memos-local-openclaw/tests/skill-prompt-policy.test.ts +++ b/apps/memos-local-openclaw/tests/skill-prompt-policy.test.ts @@ -18,4 +18,14 @@ describe("skill prompt policy", () => { expect(STEP1_SKILL_MD_PROMPT).toContain("Abstract the mistake"); expect(STEP1_SKILL_MD_PROMPT).toContain("project name, product version"); }); + + it("keeps generated skills concise and discoverable", () => { + expect(STEP1_SKILL_MD_PROMPT).toContain("2-4 words in English kebab-case"); + expect(STEP1_SKILL_MD_PROMPT).toContain("ONLY `name` and `description`"); + expect(STEP1_SKILL_MD_PROMPT).not.toContain("metadata:"); + expect(STEP1_SKILL_MD_PROMPT).not.toContain("## When to use this skill"); + expect(STEP1_SKILL_MD_PROMPT).toContain("multi-variant skills"); + expect(STEP1_SKILL_MD_PROMPT).toContain("README.md"); + expect(STEP1_SKILL_MD_PROMPT).toContain("does not already know"); + }); }); diff --git a/packages/memos-core/src/skill/generator.ts b/packages/memos-core/src/skill/generator.ts index 89cf1e2e6..17001994b 100644 --- a/packages/memos-core/src/skill/generator.ts +++ b/packages/memos-core/src/skill/generator.ts @@ -28,6 +28,13 @@ This Skill is special: it comes from real execution experience — every step wa - The frontmatter description (~100 words) is ALWAYS in the agent's context — it must be self-sufficient for deciding whether to use this skill. - The SKILL.md body loads when triggered — keep it under 400 lines, focused, no fluff. - If the task involved large configs/scripts, mention them but DON'T inline everything — just reference that scripts/ or references/ may contain them. +- For multi-variant skills, keep only the shared workflow and variant-selection guidance in SKILL.md; move framework-, provider-, or domain-specific details into separate references/ files. +- Do not create README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or other standalone documentation. A skill consists of SKILL.md plus only the scripts/, references/, or assets/ companions it genuinely needs. + +### Frontmatter rules +- name: Use 2-4 words in English kebab-case so the identifier stays concise. +- description: Include both what the skill does and when to use it, with concrete scenarios, keywords, and alternative phrasings because this is the primary trigger. +- Include ONLY \`name\` and \`description\` in frontmatter; do not add metadata or other fields. ### Description as trigger mechanism The description field decides whether the agent activates this skill. Write it "proactively": @@ -42,6 +49,7 @@ The description field decides whether the agent activates this skill. Write it " - Seeing yourself write ALWAYS or NEVER in caps is a yellow flag — rephrase with reasoning instead - Generalize from the specific task so the skill works for similar future scenarios, don't over-fit to this exact project - Keep real commands/code/config from the task record — these are verified to work +- Only include information the agent does not already know; omit generic explanations that add tokens without improving execution. ### Language matching (CRITICAL) You MUST write the ENTIRE skill in the SAME language as the user's messages in the task record. @@ -60,16 +68,12 @@ Output ONLY the complete SKILL.md content. No extra text before or after. --- name: "{NAME}" description: "{A natural, proactive description. 60-120 words. Cover what it does + multiple phrasings/scenarios that should trigger it. Be pushy about triggering — list keywords, alternative descriptions, edge-case phrasings.}" -metadata: {{ "openclaw": {{ "emoji": "{emoji}" }} }} --- # {Title — clear, action-oriented} {One sentence: what this skill helps you do and why it's valuable} -## When to use this skill -{2-4 bullet points describing the scenarios. Focus on the user's INTENT, not just keywords. Example: "When you need to get a Node app running reliably in a container and want to avoid common pitfalls like bloated images or missing health checks."} - ## Steps {Numbered or sectioned steps extracted from the task. EVERY step actually performed must be included — do NOT skip or generalize away concrete steps like "configure security groups", "set environment variables", etc. For each step: 1. What to do (keep inline code short — if a step involves a long script or config, write a brief summary here and say "see scripts/ for the complete script")