#Writing a skill.md by hand

1 messages · Page 1 of 1 (latest)

rancid notch
#

Wondering what is the best way to do this. I notice when my agent writes their own skill it frequently says "we will" for itself, and "the user" for the person it is interacting with. Any tips on writing skills an agent can easily follow without confusions?

sour socketBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

digital obsidianBOT
#

Yep — write skills like direct operating instructions, not documentation/narrative.

I’d use this pattern:

## Roles

- “You” means the agent/assistant reading this skill.
- “The requester” means the human who asked for help.
- “The recipient/contact/third party” means any other person being discussed.
- Avoid “we/us” unless it literally means both you and the requester.

## Instructions

When the requester asks for X:
# 
1. Check Y.
2. Do Z.
3. Reply with the result.

Best tips:

  • Prefer imperative voice: “Check the file”, “Ask one clarifying question”, “Summarize the result”.
  • Avoid future-tense prose like “we will
” — it makes the model role-play the skill author.
  • Use “you” for the agent, not “the agent”.
  • Use “requester” instead of “user” if there may be multiple humans involved.
  • Add tiny examples when pronouns matter:
Bad: “Tell the user their account is ready.”
# 
Good: “Tell the requester: ‘Your account is ready.’”

Also keep the skill short and procedural. OpenClaw’s docs say skills should teach the agent how and when to use tools, so concise trigger/action/checklist style tends to work best: https://docs.openclaw.ai/tools/creating-skills

rancid notch
#

Would it be a good idea to have the agent read through the skill and outline the process? I noticed across new sessions the outline changes, so I assume it's my fault for writing an ambiguous skill?

digital obsidianBOT
#

Yes — that’s a good debugging technique, but I wouldn’t make it part of the normal workflow.

Ask the agent something like:

“Read this SKILL.md and produce the exact checklist you would follow. Do not perform the task.”

Then compare a few fresh sessions. If the outlines differ only in wording, that’s normal model variance. If they differ in order, required checks, definitions, or when to ask the requester questions, the skill is probably ambiguous.

My preferred fix: put the outline inside the skill as the canonical procedure.

## Procedure

Follow these steps in order:

1. Identify the requester’s goal.
# 
2. Check whether required input A and B are present.
3. If either is missing, ask one concise clarifying question.
4. Otherwise, run the workflow.
5. Return the result plus any caveats.

Then add a small “Do / Don’t” section:

## Language rules

- “You” means the assistant using this skill.
- “Requester” means the human asking for help.
- Do not say “we will” unless you mean both you and the requester.
- Do not refer to the requester as “the user” in outward-facing replies.
#

And if the workflow is delicate, add 1–2 examples:

Requester asks: “Can you clean this up?”
You should: ask what “clean up” means unless the target format is already specified.

So yeah: outline-generation is a great skill lint test. If you want stable behavior, don’t rely on the agent deriving the process each time — write the process explicitly. Docs reference: https://docs.openclaw.ai/tools/creating-skills

rancid notch
#

I wrote in TOOLS.md the following, but my agent still cannot find the skill reliably: [ The "chef" or "chef-advisor" skill can be found at /home/juani/.openclaw/workspace/skills/chef-advisor/SKILL.md, read it carefully to understand how to invoke the skill. ]

digital obsidianBOT
#

TOOLS.md is the wrong lever for this. It can remind the agent about a path, but it doesn’t make the skill reliably load into the skill snapshot.

First thing I’d check: what OpenClaw version are you on?

openclaw --version

Then debug it as a skill-loading issue:

openclaw skills list --eligible
openclaw skills info chef-advisor
openclaw skills check

A few common gotchas:

#
  • The path must be under the agent’s actual <workspace>/skills/, not just the path you expect. If that agent’s workspace is different, /home/juani/.openclaw/workspace/skills/... may be invisible.
  • Start a new session after adding/editing it: /new is usually enough.
  • Make sure SKILL.md has valid frontmatter, e.g.
---
name: chef-advisor
description: Helps with cooking/recipe/meal-planning advice.
---
  • Check agents.defaults.skills / agents.list[].skills. If you have an allowlist, the skill must be included there.
  • If the skill has metadata.openclaw.requires..., it may be gated out because a required bin/env/config/OS check fails.

Better than saying “read this path” in TOOLS.md: put the skill in the right skills/ directory, verify it appears in openclaw skills list --eligible, then reference it by its actual skill name.

Docs: https://docs.openclaw.ai/tools/skills and https://docs.openclaw.ai/cli/skills

rancid notch
#

I see, the skill generatede by the agend did not include the frontmatter, I will add it. Once added, how do I register the skill for use? I understand install is only for downlaoding from clawhub?

digital obsidianBOT
#

Yep — openclaw skills install is for downloading from ClawHub. For a hand-written local skill, there usually isn’t a separate “register” step.

Do this:

# Folder shape
~/.openclaw/workspace/skills/chef-advisor/SKILL.md

SKILL.md needs frontmatter like:

---
name: chef-advisor
description: Helps with cooking, recipes, substitutions, and meal planning.
---
# 

# Chef Advisor

When the requester asks for cooking help, follow this procedure...

Then reload/verify:

/new
openclaw skills list --eligible
openclaw skills info chef-advisor
openclaw skills check

If you want the skill shared across all agents on the machine, put it here instead:

# 
~/.openclaw/skills/chef-advisor/SKILL.md

If you have an agent skill allowlist configured, also make sure chef-advisor is included in agents.defaults.skills or that agent’s agents.list[].skills; otherwise it can exist on disk but not be exposed.

If it still doesn’t appear, check:

openclaw --version

and paste the output of:

openclaw skills info chef-advisor
rancid notch
#

thank you, consider this solved 🙂

digital obsidianBOT
#

Glad that helped! 🎉

If this fixed it, please right-click the solution message → Apps → ✅ Mark Solution. That helps Answer Overflow index it for future folks. 🩐