add docs/guide.md, update skill structure, add guide reference to all workflows

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 <column>` 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
 

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 <column>` inside the script.

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

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

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