Skip to content
OSTwin

Publishing Skills

Skills are the primary extension mechanism for OSTwin agents. This guide covers authoring, testing, versioning, and publishing to the ClawhHub marketplace.

Skill Structure

my-skill/
├── SKILL.md              # Required: frontmatter + instructions
├── references/           # Optional: templates, checklists
│   └── template.md
├── scripts/              # Optional: helper scripts
│   └── validate.py
└── .clawhub-meta.json    # Generated on publish

Authoring a Skill

  1. Create the skill directory

    Terminal window
    mkdir -p .agents/skills/global/my-skill

  2. Write SKILL.md with frontmatter

    ---
    name: my-skill
    description: "One-line description of what this skill does."
    tags: [engineer, testing, automation]
    trust_level: community
    ---
    

    # my-skill
    

    ## Overview
    When and why to use this skill.
    

    ## When to Use
    - Trigger condition 1
    - Trigger condition 2
    

    ## Workflow
    1. Step one
    2. Step two
    3. Step three
    

    ## Examples
    Concrete usage examples with realistic data.
    

    ## Error Handling
    What to do when things go wrong.

  3. Add supporting resources

    Place templates, checklists, or scripts in subdirectories. Reference them from SKILL.md using relative paths.

  4. Register in registry.json (optional for auto-discovery)

    {
      "name": "my-skill",
      "description": "One-line description",
      "path": "skills/global/my-skill/SKILL.md",
      "tags": ["engineer", "testing"],
      "trust_level": "community"
    }

Testing Skills

  1. Add the skill to a role’s skill_refs

    {
      "engineer": {
        "skill_refs": ["my-skill"]
      }
    }

  2. Run a plan that exercises the skill

    Create a plan with an epic that triggers the skill’s conditions.

  3. Verify the skill is loaded

    Check the agent logs for skill injection:

    Terminal window
    .agents/logs.sh search "my-skill"

  4. Test edge cases

    • Skill not found (misspelled name)
    • Conflicting skill_refs from multiple sources
    • Oversized SKILL.md (check prompt truncation)

Versioning

Skills use semantic versioning in their ClawhHub metadata:

VersionMeaning
1.0.0Initial stable release
1.1.0New features, backward compatible
1.0.1Bug fixes only
2.0.0Breaking changes to workflow or interface

Version is tracked in .clawhub-meta.json:

{
  "source": "clawhub",
  "version": "1.2.0",
  "installed_at": "2026-04-01T12:00:00Z",
  "checksum": "sha256:abc123def456..."
}

Publishing to ClawhHub

  1. Validate the skill structure

    Terminal window
    python .agents/bin/skills/validate.py my-skill/

    This checks for required frontmatter fields, body structure, and file size limits.

  2. Create a distribution package

    Terminal window
    python .agents/bin/skills/package.py my-skill/ --version 1.0.0

  3. Submit to ClawhHub

    Terminal window
    .agents/clawhub-install.sh publish my-skill-1.0.0.tar.gz

  4. Wait for review — ClawhHub maintainers review submissions within 72 hours

API Endpoints

The ClawhHub API provides skill discovery and installation:

EndpointMethodDescription
/api/skills/searchGETSearch skills by name or tags
/api/skills/{name}GETGet skill metadata
/api/skills/{name}/versionsGETList available versions
/api/skills/{name}/downloadGETDownload skill package
/api/skills/publishPOSTSubmit a new skill

Search Example

Terminal window
curl "https://clawhub.dev/api/skills/search?q=testing&tags=engineer"

Review Guidelines

Skills are reviewed against these criteria:

  • Valid YAML frontmatter with name, description, tags
  • Clear “When to Use” trigger conditions
  • Step-by-step workflow instructions
  • Under 4KB total SKILL.md size
  • No hardcoded secrets or API keys