How to Build the OpenClaw Skill Package for Ponytail

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/<name>/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 – The primary build script that orchestrates the generation process.
• 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:

npm install

Running the Build Script

Generate the complete OpenClaw skill package by executing the build script from the repository root:

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), reads the corresponding source files, and writes rewritten SKILL.md files to .openclaw/skills/<skill-name>/SKILL.md.

Verifying the Generated Output

After running the script, inspect the generated skills to confirm successful creation:

cat .openclaw/skills/ponytail/SKILL.md

The test suite provides an automatic safeguard against stale generated files:

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 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/<name>/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/<name>/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:

node scripts/publish-openclaw-skills.js

This script reads the repository version from package.json, enumerates all generated skill directories in .openclaw/skills/, and invokes clawhub skill publish for each one. Preview changes without publishing using:

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.
• 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 automatically detects stale generated files and fails if the build step is omitted.
• Use 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/<name>/SKILL.md without running the build script, the test suite will fail when executing 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}