lyn/ClawSkills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: enforce layer responsibilities across all skills

Browse Source 
Rewrote docs/standard.md as the single source of truth for skill
structure (menu/tools/recipes/manual analogy). Trimmed all SKILL.md
files to pure routers, moved recruitment workflow out of SKILL.md
into workflows/recruitment.md, removed duplicated standards from
workflow files.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
zhi
2026-04-17 20:40:16 +00:00
parent fd0f84d6b8
commit 795a710376
9 changed files with 238 additions and 301 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
claw-skills/SKILL.md
View File

@@ -1,71 +1,34 @@
---
name: claw-skills
description: ClawSkills management and collaboration suite — scripts and workflows for using and improving skills.
description: ClawSkills management — update, improve, create, and fix skills.
---
# claw-skills
ClawSkills management and collaboration suite — scripts and workflows for using and improving skills.
> **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/standard.md`.
## 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. For supplementary documentation, use `docs/`.
> All skill documentation must be written in English.
## Scripts
### update-skills
Pull latest ClawSkills from git-hangman-lab, then run learn.sh to install/update skills to `{AGENT_WORKSPACE}/skills`.
Pull latest ClawSkills and install/update skills to the agent workspace.
```bash
claw-skills/scripts/update-skills
{baseDir}/scripts/update-skills
```
### promote-improvements
Create and force-push a branch named after the agent (via `ego-mgr get name`) from `{AGENT_WORKSPACE}`.
Create a branch named after the agent and force-push local changes for review.
```bash
claw-skills/scripts/promote-improvements
{baseDir}/scripts/promote-improvements
```
## Workflows
### fix-skills
- `{baseDir}/workflows/create-skills.md` — When you notice a reusable pattern with no existing skill covering it.
- `{baseDir}/workflows/fix-skills.md` — When a skill or its scripts fail or produce unexpected results.
- `{baseDir}/workflows/improve-skills.md` — When a skill has misleading descriptions, missing coverage, or suboptimal behavior.
When a skill or its scripts fail to produce expected results, or throw errors:
## Reference
> **Do not resort to workarounds lightly.**
> Follow `{baseDir}/workflows/fix-skills.md` — identify the root cause first, then fix properly.
### improve-skills
When using a skill and you find:
- Misleading or ambiguous descriptions
- Missing coverage for your use case
- Suboptimal or confusing behavior
> Follow `{baseDir}/workflows/improve-skills.md` to improve it.
### create-skills
When you notice patterns or workflows that could improve efficiency but have no skill covering them:
> Follow `{baseDir}/workflows/create-skills.md` to create a new skill.
- `{baseDir}/docs/standard.md` — Skill structure, layer responsibilities, and writing requirements.

105
claw-skills/docs/standard.md
View File

@@ -1,43 +1,104 @@
# Skill Authoring Guide
# Skill Authoring Standard
## Skill Structure
## Anatomy of a Skill
A skill is a directory with the following layout:
A skill is a directory with up to four layers:
```
{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
{skill-name}/
SKILL.md # Required — the menu
scripts/ # Optional — the kitchen tools
workflows/ # Optional — the recipes
docs/ # Optional — the reference manual
```
## Writing Requirements
Each layer has a single responsibility:
**SKILL.md must start with a YAML frontmatter block:**
| Layer | Role | Analogy | Contains | Does NOT contain |
|-------|------|---------|----------|------------------|
| **SKILL.md** | Router | Menu | What's available + when to use it | Process details, standards, how-tos |
| **scripts/** | Automation | Kitchen tools | Fixed-logic executables | Judgment calls, contextual decisions |
| **workflows/** | Process guide | Recipes | Step-by-step procedures requiring judgment | Standards, naming rules, structure specs |
| **docs/** | Reference | Reference manual | Facts, standards, specifications | Procedures, step-by-step instructions |
```yaml
### How they relate
```
Agent reads SKILL.md
→ finds the right script or workflow
→ workflow references docs/ for standards when needed
```
## SKILL.md — The Menu
SKILL.md is the first thing an agent reads. It answers two questions: **what's available** and **when to use it**.
### Format
```markdown
---
name: {skill-name}
description: {when-to-use}
description: {one-line description of when to use this skill}
---
> Execution notes (e.g., "All scripts must be executed via pcexec")
## Scripts
List each script with invocation syntax and a one-line description.
Group related scripts under a subheading if needed.
## Workflows
List each workflow file path with the trigger condition (when to use it).
## Reference
Point to docs/ if the skill has reference material.
```
**SKILL.md body 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/`.
### Rules
> **All skill-related documentation must be written in English.**
- **Concise.** One-line descriptions per script/workflow. No multi-paragraph explanations.
- **No process details.** Don't describe how to do something — that belongs in workflows/.
- **No standards or rules.** Don't define naming conventions or structure — that belongs in docs/.
- **Warnings and prerequisites** are allowed as short callouts (e.g., "do not run unless explicitly requested").
## When to Use Scripts vs Workflows
## scripts/ — The Kitchen Tools
Both scripts and workflows are parts of a skill — scripts live in `{skill-name}/scripts/`, workflows in `{skill-name}/workflows/`.
Scripts handle operations that are **completely fixed** — the steps are predictable, the logic doesn't change based on context.
- **Scripts** — handle logic that is completely fixed. When the steps are predictable and always the same, encode them in a script.
- **Workflows** — handle flexible situations. When context matters, decisions are needed, or the process is nuanced, describe it in a workflow document.
### Rules
## Script Hint
- Each script has a single responsibility
- Must be executable (`chmod +x`)
- Must be called via `pcexec` unless documented otherwise
- Use `AGENT_ID`, `AGENT_WORKSPACE` environment variables when behavior varies by agent
- Use `ego-mgr get <field>` for agent identity info inside scripts
When a script needs to behave differently based on the calling agent, use these environment variables:
## workflows/ — The Recipes
- `AGENT_ID` — the agent ID executing the script
- `AGENT_WORKSPACE` — the workspace of the agent executing the script
Workflows guide operations that **require judgment** — the steps vary depending on context, or decisions need to be made along the way.
For more agent info, call `ego-mgr get <column>` inside the script.
### Rules
- Each workflow is a standalone markdown file
- Must be self-contained enough to follow independently
- Reference docs/ for standards (e.g., `> See docs/standard.md for naming conventions`) — don't repeat them inline
- Focus on **steps and decision points**, not rules
## docs/ — The Reference Manual
Docs hold **facts and standards** that don't change based on who's reading or what task they're doing.
### Rules
- Reference material only — no step-by-step procedures
- Standards, specifications, naming conventions, structure definitions
- Referenced by workflows and SKILL.md, never duplicated into them
## General Requirements
- **Language:** All skill documentation must be written in English
- **Naming:** Skill directories use kebab-case (e.g., `git-hangman-lab`)
- **Frontmatter:** SKILL.md must start with a YAML frontmatter block containing `name` and `description`

58
claw-skills/workflows/create-skills.md
View File

@@ -1,30 +1,12 @@
# create-skills
# Create Skills
Used when you notice patterns or workflows that could improve efficiency but have no skill covering them.
When you notice a reusable pattern with no existing skill covering it.
> See `{baseDir}/docs/standard.md` for skill structure and layer responsibilities.
## Principle
Not every repetitive task needs to become a skill. Ask first: is this pattern general enough to warrant abstraction?
> See `{baseDir}/docs/standard.md` for skill structure and writing requirements.
## When to Add a Script vs a Workflow to a Skill
A skill can contain scripts, workflows, or both. When extending a skill, decide which type to add:
**Add a script when:**
- The steps are fixed, results are predictable
- The operation recurs across different agents/workspaces
- Involves external system calls (git, keycloak, file ops, etc.)
**Add a workflow when:**
- Steps vary depending on context — the process needs human judgment or situational decisions
- The scenario is too nuanced for rigid logic
**Not worth abstracting:**
- One-off task
> Conversational/analytical work *can* be worth a workflow — e.g., an interview flow (`recruitment/intviewer`) that guides through questions contextually is a valid workflow.
Not every repetitive task needs a skill. Ask first: is this pattern general enough to warrant abstraction?
## Process
@@ -32,23 +14,29 @@ A skill can contain scripts, workflows, or both. When extending a skill, decide
- Record the repeating sequence of operations
- Analyze: what are you doing repeatedly across tasks?
- Evaluate: is this operation general-purpose or a one-off special case?
- Evaluate: is this general-purpose or a one-off?
### 2. Decide the Approach
Based on the criteria above, determine whether this should be a new skill, or a script/workflow added to an existing skill.
Should this be a new skill, or a script/workflow added to an existing skill?
### 3. Design the Skill
**Add a script when:**
- The steps are fixed and results are predictable
- The operation recurs across different agents/workspaces
- Involves external system calls (git, keycloak, file ops, etc.)
- **Name:** kebab-case (e.g., `git-clone-repo`, `keycloak-create-user`)
- **SKILL.md contents:**
- Description: what this skill does
- Use cases: when to use it
- Scripts: all related scripts and how to call them
- **Scripts:**
- Place under `scripts/`
- Each script has a single responsibility
- Provide `--help` or `-h` support
**Add a workflow when:**
- Steps vary depending on context or require judgment
- The scenario is too nuanced for rigid logic
**Not worth abstracting:**
- One-off tasks
### 3. Design
- **Name:** kebab-case (e.g., `git-clone-repo`)
- **SKILL.md:** Router only — list scripts with invocation syntax, workflows with trigger conditions
- **Scripts:** Single responsibility each, placed under `scripts/`
### 4. Implement

21
claw-skills/workflows/fix-skills.md
View File

@@ -1,13 +1,13 @@
# fix-skills
# Fix Skills
Used when a skill or its scripts fail to produce expected results, or throw errors.
When a skill or its scripts fail to produce expected results, or throw errors.
> See `{baseDir}/docs/standard.md` for skill structure and layer responsibilities.
## Principle
**Do not resort to workarounds lightly.** Identify the root cause first, then fix properly.
> See `{baseDir}/docs/standard.md` for skill structure and writing requirements.
## Process
### 1. Gather Information
@@ -20,24 +20,23 @@ Used when a skill or its scripts fail to produce expected results, or throw erro
Investigate in this order:
1. **Are inputs/parameters correct?** — Do they match what the script or tool expects?
2. **Are dependencies satisfied?** — Are required secrets, tokens, config files present?
1. **Are inputs/parameters correct?** — Do they match what the script expects?
2. **Are dependencies satisfied?** — Required secrets, tokens, config files present?
3. **Is there a bug in the script logic?** — Read the source, add `set -x` if needed
4. **Is there a design flaw in the skill?** — Does the logic actually cover this scenario?
4. **Is there a design flaw?** — Does the logic actually cover this scenario?
### 3. Pinpoint the File
- Identify which file and which line the problem is in
- If it's a skill issue → follow the [improve-skills](./improve-skills.md) workflow
- If it's an execution environment issue → document in memory/
- If it's a skill issue → follow the improve-skills workflow
- If it's an environment issue → document in memory/
### 4. Fix
- Test the fix locally
- If skill files need to be modified → follow improve-skills process to PR or push to a branch
- If skill files need modification → follow improve-skills process
- Avoid introducing new side effects
### 5. Verify
- Reproduce the original scenario; confirm the issue is resolved
- Log the fix in memory/YYYY-MM-DD.md

30
claw-skills/workflows/improve-skills.md
View File

@@ -1,24 +1,13 @@
# improve-skills
# Improve Skills
Used when a skill or workflow has one of these problems:
When a skill has misleading descriptions, missing coverage, or suboptimal behavior.
- Misleading or ambiguous
- Missing coverage for your use case
- Suboptimal or confusing behavior
> See `{baseDir}/docs/standard.md` for skill structure and layer responsibilities.
## Principle
Improvement is better than workaround. Fix problems when you find them, so others don't hit the same pitfall.
## Requirement
**All skill-related documentation must be written in English.** This applies to:
- Creating new skills or workflows
- Improving or correcting existing skills
- Any other documentation within skills
> See `{baseDir}/docs/standard.md` for skill structure and writing requirements.
## Process
### 1. Identify the Problem
@@ -29,24 +18,25 @@ Improvement is better than workaround. Fix problems when you find them, so other
### 2. Assess Impact
- How many people will this affect?
- How many agents will this affect?
- Is it a design issue or a documentation issue?
- What's the complexity of the fix?
### 3. Design the Fix
- **Documentation issue** → update SKILL.md or related descriptions
- **Logic flaw** → modify the script or skill logic
- **Documentation issue** → update SKILL.md or docs/
- **Logic flaw** → modify the script
- **Missing coverage** → add a new workflow or script
- **Process issue** → redesign the workflow
### 4. Implement
- Make changes locally or on a branch
- Make changes locally
- Update SKILL.md if behavior changed
- Test if the change is significant
### 5. Submit
- Call `{baseDir}/scripts/promote-improvements` to push to your branch.
- Commit message should describe what was changed and why
Call `{baseDir}/scripts/promote-improvements` to push to your branch.
Commit message should describe what was changed and why.