I wanted to add a feature to OpenClaw that didn’t exist: a Hacker News digest that summarizes the top stories every morning and posts them to my Slack. Nothing like this existed as a skill. So I built one.
It took four hours the first time, including two hours of reading the skill specification wrong. The second skill I built took 45 minutes. By the fifth, I could knock one out in 30 minutes. Here’s the process, stripped of all the mistakes I made along the way.
What a Skill Actually Is
A skill is a folder with instructions and optional scripts. At minimum, it contains a SKILL.md file — a markdown document that tells OpenClaw what the skill does, when to activate it, and how to use it.
That’s really it. No compilation. No package registry. No build system. A skill is a document that OpenClaw reads when it needs to perform a specific task.
The simplest possible skill:
A folder called daily-hn-digest containing a single file, SKILL.md, with instructions like: “When the user asks for a Hacker News digest, use the web_search tool to find the current top stories on Hacker News, summarize each one in 2-3 sentences, and format the result as a bulleted list.”
That works. The agent reads the instructions, follows them, and produces a Hacker News digest. No code required.
Adding Complexity When You Need It
The basic skill handles simple cases. For more complex workflows, you add:
Reference files. My Hacker News skill includes a refs/ folder with example outputs — showing the agent what a good digest looks like. This improves consistency dramatically. Instead of “summarize stories,” the agent sees “here’s what a good summary looks like — match this format.”
Scripts. Some skills include shell scripts or Python scripts for tasks the AI can’t do directly. My digest skill includes a script that fetches the Hacker News API (faster and more reliable than web scraping). The skill instructions tell the agent to run the script and process its output.
Configuration. Skills can read from config files. My digest skill has a config.yaml that specifies how many stories to include (default: 10), which categories to prioritize, and the output format (Slack, email, or plain text).
The Structure That Works
After building about a dozen skills, here’s the folder structure I’ve settled on:
my-skill/
├── SKILL.md — Main instructions (required)
├── refs/ — Example inputs and outputs (optional)
├── scripts/ — Helper scripts (optional)
└── config.yaml — Configuration (optional)
SKILL.md is the most important file. It should include:
1. A clear description of what the skill does
2. When the skill should activate (trigger conditions)
3. Step-by-step instructions for the workflow
4. Error handling guidance
5. Examples of good output
The quality of your SKILL.md directly determines the quality of the skill. A vague SKILL.md produces inconsistent results. A precise SKILL.md produces reliable results.
Writing Good Instructions
The biggest lesson I learned: write SKILL.md like you’re training a new employee, not like you’re writing documentation.
Bad: “Fetch Hacker News stories and summarize them.”
Good: “Fetch the top 10 stories from the Hacker News API using the script at scripts/fetch-hn.sh. For each story, write a 2-3 sentence summary that covers: what happened, why it matters, and the community reaction (if notable). Format as a numbered list with the story title as a link.”
The good version eliminates ambiguity. The agent knows exactly what to do, what format to use, and what information to include. No room for creative interpretation where you don’t want it.
Include failure modes. “If the Hacker News API is unreachable, use web_search as a fallback. If fewer than 5 stories are available, note this in the output and proceed with whatever is available. Do not fabricate stories.”
Include boundaries. “Do not editorialize. Do not add opinions about the stories. Do not skip stories because they seem unimportant. Present all top stories neutrally.”
Testing Your Skill
The testing process is simple: install the skill, trigger it, and check the output.
For my Hacker News skill:
1. Copy the folder to the skills directory
2. Restart OpenClaw (or wait for it to detect the new skill)
3. Type “Give me a Hacker News digest”
4. Check the output against expectations
5. Adjust SKILL.md based on what went wrong
I typically go through 3-4 revision cycles before I’m satisfied. Common issues: the agent skipping steps (add more explicit instructions), inconsistent formatting (add an example output), or including information you didn’t want (add explicit boundaries).
Publishing and Sharing
Once your skill works, you can share it through ClawHub — the community skill marketplace. Upload your skill folder, add a description, and other users can install it with a single command.
Before publishing, clean up your skill: remove any personal configurations, add a README with setup instructions, and test it on a fresh OpenClaw installation to make sure it doesn’t depend on your local environment.
The best community skills are focused (they do one thing well), well-documented (clear SKILL.md), and solid (they handle failures gracefully). The worst are vague (“use AI to do stuff”), poorly documented, or fragile.
My Favorite Custom Skills
Beyond the Hacker News digest, here are the custom skills I use daily:
Meeting prep. Before a meeting, I say “prep for my 2pm with [client].” The skill pulls recent emails, project updates, and open issues related to that client and compiles a one-page briefing.
Code review assistant. When I push code, the skill reviews it against our team’s coding standards (documented in a reference file) and posts comments in our team channel.
Weekly retro generator. Every Friday, the skill compiles what I accomplished that week (from GitHub commits, Slack messages, and task completions) and drafts a weekly summary.
Each of these took about an hour to build. Each saves 15-30 minutes per use. The ROI is obvious.
🕒 Last updated: · Originally published: January 7, 2026