From 315cf468898e26c2f8d8d74e90e9d5bc10c71873 Mon Sep 17 00:00:00 2001 From: lyn Date: Fri, 17 Apr 2026 14:11:46 +0000 Subject: [PATCH] add docs/guide.md, update skill structure, add guide reference to all workflows --- claw-skills/SKILL.md | 14 ++++--------- claw-skills/docs/guide.md | 27 +++++++++++++++++++++++++ claw-skills/workflows/create-skills.md | 3 +++ claw-skills/workflows/fix-skills.md | 2 ++ claw-skills/workflows/improve-skills.md | 4 ++++ 5 files changed, 40 insertions(+), 10 deletions(-) create mode 100644 claw-skills/docs/guide.md diff --git a/claw-skills/SKILL.md b/claw-skills/SKILL.md index 3a42eef..f82c6f8 100644 --- a/claw-skills/SKILL.md +++ b/claw-skills/SKILL.md @@ -5,6 +5,8 @@ ClawSkills management and collaboration suite — scripts and workflows for usin > **All skill-related documentation must be written in English.** > When creating, improving, or correcting skills, always use English for all documentation, descriptions, and guides. +For additional guidance, see `{baseDir}/docs/guide.md`. + ## Skill Structure A skill is a directory with the following layout: @@ -13,20 +15,12 @@ A skill is a directory with the following layout: {skill-name}/SKILL.md # Required — skill description and usage {skill-name}/scripts/ # Optional — executable scripts {skill-name}/workflows/ # Optional — process guides +{skill-name}/docs/ # Optional — supplementary documentation ``` ## Writing Requirements -**SKILL.md should be concise.** It serves as a table of contents for workflows — list each workflow file path with the scenario that triggers it. - -## Script Hint - -When a script needs to behave differently based on the calling agent, use these environment variables: - -- `AGENT_ID` — the agent ID executing the script -- `AGENT_WORKSPACE` — the workspace of the agent executing the script - -For more agent info, call `ego-mgr get ` inside the script. +**SKILL.md should be concise.** It serves as a table of contents for workflows — list each workflow file path with the scenario that triggers it. For supplementary documentation, use `docs/`. ## Scripts diff --git a/claw-skills/docs/guide.md b/claw-skills/docs/guide.md new file mode 100644 index 0000000..3d5f32b --- /dev/null +++ b/claw-skills/docs/guide.md @@ -0,0 +1,27 @@ +# Skill Authoring Guide + +## Skill Structure + +A skill is a directory with the following layout: + +``` +{skill-name}/SKILL.md # Required — skill description and usage +{skill-name}/scripts/ # Optional — executable scripts +{skill-name}/workflows/ # Optional — process guides +{skill-name}/docs/ # Optional — supplementary documentation +``` + +## Writing Requirements + +**SKILL.md should be concise.** It serves as a table of contents for workflows — list each workflow file path with the scenario that triggers it. + +> **All skill-related documentation must be written in English.** + +## Script Hint + +When a script needs to behave differently based on the calling agent, use these environment variables: + +- `AGENT_ID` — the agent ID executing the script +- `AGENT_WORKSPACE` — the workspace of the agent executing the script + +For more agent info, call `ego-mgr get ` inside the script. diff --git a/claw-skills/workflows/create-skills.md b/claw-skills/workflows/create-skills.md index b732ec2..cce8820 100644 --- a/claw-skills/workflows/create-skills.md +++ b/claw-skills/workflows/create-skills.md @@ -6,6 +6,9 @@ Used when you notice patterns or workflows that could improve efficiency but hav Not every repetitive task needs to become a skill. Ask first: is this pattern general enough to warrant abstraction? +> See `{baseDir}/docs/guide.md` for skill structure and writing requirements. + + ## Process ### 1. Identify the Pattern diff --git a/claw-skills/workflows/fix-skills.md b/claw-skills/workflows/fix-skills.md index 411b097..619d707 100644 --- a/claw-skills/workflows/fix-skills.md +++ b/claw-skills/workflows/fix-skills.md @@ -6,6 +6,8 @@ Used when a skill or its scripts fail to produce expected results, or throw erro **Do not resort to workarounds lightly.** Identify the root cause first, then fix properly. +> See `{baseDir}/docs/guide.md` for skill structure and writing requirements. + ## Process ### 1. Gather Information diff --git a/claw-skills/workflows/improve-skills.md b/claw-skills/workflows/improve-skills.md index 8d1db3d..4f7db58 100644 --- a/claw-skills/workflows/improve-skills.md +++ b/claw-skills/workflows/improve-skills.md @@ -17,12 +17,16 @@ Improvement is better than workaround. Fix problems when you find them, so other - Improving or correcting existing skills - Any other documentation within skills +> See `{baseDir}/docs/guide.md` for skill structure and writing requirements. + ## Process ### 1. Identify the Problem - Record which skill and which part has the issue - Describe specifically: what's misleading, what's missing, what's not working well +- Record the scenario where you encountered it- Record which skill and which part has the issue +- Describe specifically: what's misleading, what's missing, what's not working well - Record the scenario where you encountered it ### 2. Assess Impact