# How to Build the OpenClaw Skill Package for Ponytail > Build the OpenClaw skill package for Ponytail by running a simple script. Learn how to generate compliant SKILL.md files from canonical sources for your project. - Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) - Tags: how-to-guide - Published: 2026-08-28 --- **Build the OpenClaw skill package for Ponytail by running `node scripts/build-openclaw-skills.js`, which generates compliant SKILL.md files in the `.openclaw/skills/` directory from canonical sources in `skills/`.** The Ponytail repository maintains its OpenClaw skills in a specialized format required by ClawHub. To ensure the skill definitions remain synchronized with the canonical documentation while meeting strict front-matter requirements, the project automates the build process through a dedicated Node.js script. Understanding how to build the OpenClaw skill package for Ponytail ensures your local skill definitions stay valid and publishable. ## Understanding the OpenClaw Skill Architecture Ponytail separates skill development from distribution by maintaining two distinct locations for skill definitions. ### The Source-to-Generated Workflow The canonical skill sources live under the **`skills/`** directory, containing raw documentation and usage examples. However, OpenClaw expects skills in a specific format within the hidden directory **`.openclaw/skills/`**. The build script bridges this gap by reading the source files, injecting standardized front-matter, and writing compliant versions to the destination directory. ### Key Files and Directories - **`skills//SKILL.md`** – The canonical source files containing skill documentation without OpenClaw-specific metadata. - **`.openclaw/skills/`** – The destination directory where generated OpenClaw-compliant skills are written (created automatically by the build script). - **[`scripts/build-openclaw-skills.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/build-openclaw-skills.js)** – The primary build script that orchestrates the generation process. - **[`tests/openclaw-skills.test.js`](https://github.com/DietrichGebert/ponytail/blob/main/tests/openclaw-skills.test.js)** – Automated tests that fail if generated skills are out of sync with sources. ## Building the OpenClaw Skill Package Step by Step ### Prerequisites and Installation Before building, ensure dependencies are installed. Run this once after cloning the repository: ```bash npm install ``` ### Running the Build Script Generate the complete OpenClaw skill package by executing the build script from the repository root: ```bash node scripts/build-openclaw-skills.js ``` This command processes every skill defined in the **`DESCRIPTIONS`** constant (lines 19–26 of [`scripts/build-openclaw-skills.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/build-openclaw-skills.js)), reads the corresponding source files, and writes rewritten SKILL.md files to `.openclaw/skills//SKILL.md`. ### Verifying the Generated Output After running the script, inspect the generated skills to confirm successful creation: ```bash cat .openclaw/skills/ponytail/SKILL.md ``` The test suite provides an automatic safeguard against stale generated files: ```bash npm test -- tests/openclaw-skills.test.js ``` If this test fails, it indicates the generated package is out of sync with the canonical sources and requires rebuilding. ## How the Build Script Works The generation process in [`scripts/build-openclaw-skills.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/build-openclaw-skills.js) follows a precise four-step pipeline: 1. **Load Skill Descriptions** – The **`DESCRIPTIONS`** map (lines 19–26) defines short, ≤160-character descriptions for each skill (`ponytail`, `ponytail-review`, etc.). 2. **Extract Source Content** – The **`sourceBody(name)`** helper (lines 30–35) reads `skills//SKILL.md`, strips any existing front-matter, and returns only the documentation body. 3. **Rewrite Front-Matter** – The **`render(name)`** function (lines 37–45) constructs a fresh front-matter block containing the short description, repository homepage, and MIT license, then concatenates this with the original body. 4. **Write Generated Files** – **`outPath(name)`** (lines 47–49) determines the destination path at `.openclaw/skills//SKILL.md`. The script creates missing directories and writes the rendered content (lines 54–58), ensuring the package never drifts from source documentation. ## Publishing to ClawHub Once skills are generated, publish them to ClawHub using the companion script: ```bash node scripts/publish-openclaw-skills.js ``` This script reads the repository version from [`package.json`](https://github.com/DietrichGebert/ponytail/blob/main/package.json), enumerates all generated skill directories in `.openclaw/skills/`, and invokes `clawhub skill publish` for each one. Preview changes without publishing using: ```bash node scripts/publish-openclaw-skills.js --dry-run ``` Note that publishing requires the `clawhub` CLI and prior authentication. ## Summary - The OpenClaw skill package is generated from canonical sources in `skills/` to `.openclaw/skills/` using [`scripts/build-openclaw-skills.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/build-openclaw-skills.js). - The build process injects standardized front-matter (description, repository URL, license) while preserving the original documentation body. - Run `node scripts/build-openclaw-skills.js` after modifying source files to keep the package synchronized. - The test suite [`tests/openclaw-skills.test.js`](https://github.com/DietrichGebert/ponytail/blob/main/tests/openclaw-skills.test.js) automatically detects stale generated files and fails if the build step is omitted. - Use [`scripts/publish-openclaw-skills.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/publish-openclaw-skills.js) to distribute skills to ClawHub, with support for dry-run verification. ## Frequently Asked Questions ### Where does Ponytail store the generated OpenClaw skills? Ponytail writes generated OpenClaw skills to the hidden directory **`.openclaw/skills/`**, with each skill occupying a subdirectory containing a rewritten SKILL.md file. This location is automatically created by the build script if it does not exist. ### What happens if I modify a source SKILL.md file but forget to rebuild? If you modify `skills//SKILL.md` without running the build script, the test suite will fail when executing [`tests/openclaw-skills.test.js`](https://github.com/DietrichGebert/ponytail/blob/main/tests/openclaw-skills.test.js). These tests verify that generated files match their source documentation, preventing stale skill packages from passing CI. ### How does the build script handle front-matter in source files? The **`sourceBody(name)`** function explicitly strips existing front-matter from source files (lines 30–35), while the **`render(name)`** function generates fresh front-matter containing the skill description, repository homepage, and license. This ensures OpenClaw compliance regardless of the source file's original formatting. ### Can I customize the skill descriptions used in the OpenClaw package? Yes, skill descriptions are defined in the **`DESCRIPTIONS`** constant at lines 19–26 of [`scripts/build-openclaw-skills.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/build-openclaw-skills.js). These one-line summaries must be ≤160 characters to comply with OpenClaw/ClawHub format requirements. Edit this constant and rebuild to update published skill descriptions.