Skip to main content

​
Skill File Format

A skill is a single SKILL.md file with YAML frontmatter and Markdown instructions: 
your-project/
  skills/
    my-skill/
      SKILL.md

​
Complete SKILL.md Example

---
name: api-reviewer
description: Review REST API designs for consistency and best practices
version: 1.0.0
user-invocable: true
metadata: >
  {"profclaw": {
    "emoji": "api",
    "category": "development",
    "priority": 75,
    "triggerPatterns": [
      "review this API",
      "is this REST API good",
      "check my endpoint design"
    ]
  }}
---

# API Reviewer

You are an API design expert. When asked to review a REST API, analyze it for
consistency, adherence to REST conventions, and potential usability issues.

## What This Skill Does

- Reviews REST endpoint designs for naming consistency
- Checks HTTP method usage (GET/POST/PUT/PATCH/DELETE)
- Validates status code choices
- Identifies missing error responses
- Suggests versioning improvements

## How to Review

### Step 1: Read the API Definition

If given an OpenAPI spec file, read it:
read_file(path: “openapi.yml”) 

If pasted inline, work with the provided content.

### Step 2: Evaluate Across These Dimensions

**Naming Conventions**
- Resources should be nouns, not verbs: `/users` not `/getUsers`
- Use plural for collections: `/tickets` not `/ticket`
- Consistent casing: kebab-case for multi-word paths

**HTTP Methods**
- GET: Read only, idempotent, no body
- POST: Create, non-idempotent
- PUT: Replace entire resource
- PATCH: Partial update
- DELETE: Remove resource

**Status Codes**
- 200 OK, 201 Created, 204 No Content
- 400 Bad Request (client error), 401 Unauthorized, 403 Forbidden, 404 Not Found
- 500 Internal Server Error (never expose stack traces)

### Step 3: Output Format

​
API Review: [endpoint or spec name]

Overall: [Looks good / Needs minor fixes / Needs redesign]

​
Issues

  • [METHOD /path] [category]: Issue description. Suggestion: …

​
Positives

  • What is well-designed

​
Frontmatter Reference

​
name
string
required
Unique skill identifier in kebab-case. Must be unique across all loaded skills.
​
description
string
required
One-sentence description shown in skill lists and the UI.
​
version
string
required
Semver version string (e.g., "1.0.0").
​
user-invocable
boolean
default:"true"
Whether this skill appears as a slash command. Set to false for background/system skills.
​
disable-model-invocation
boolean
default:"false"
Prevent the AI from auto-activating this skill based on trigger patterns.
​
command-dispatch
string
Set to "tool" to route slash command invocation directly to a tool instead of injecting as instructions.
​
command-tool
string
Tool name to dispatch to when command-dispatch: tool.
​
command-arg-mode
string
How to pass slash command args to the tool: "raw" (as a string) or "parsed" (as structured params).

​
Metadata JSON Schema

The metadata field is a JSON string (or YAML block scalar) with this structure: 
{
  "profclaw": {
    "emoji": "magnifying-glass",
    "category": "development",
    "priority": 85,
    "triggerPatterns": [
      "review my code",
      "check this PR"
    ]
  }
}
FieldDescription
emojiLucide icon name for UI display
categoryGroup in skill browser: development, productivity, media, integrations, system
prioritySort order in lists (0-100, higher = first)
triggerPatternsPhrases that cause auto-activation

​
Writing Good Instructions

​
Be Specific About Tool Usage

Instead of “look at the code”, tell the AI exactly which tools to use: 
## How to Execute

1. Read the file:
   read_file(path: provided_path)

2. Search for patterns:
   grep(pattern: "TODO:", glob: "**/*.ts")

​
Provide Output Format Templates

Give the AI a concrete output structure to follow: 
## Output Format

Always respond in this format:

## Summary
[1-2 sentences]

## Issues Found
- [severity] [file:line]: description

## Recommendations
1. First recommendation

​
Include Example Interactions

## Examples

**User**: Review this function: `[pastes code]`
**You**: *(reads code, analyzes it)* Structured feedback with file:line references.

**User**: Is this secure?
**You**: Focuses analysis on security: injection, auth, input validation.

​
Command Dispatch Skill

For simple slash commands that just run a tool, use command dispatch instead of instructions: 
---
name: run-tests
description: Run the test suite
user-invocable: true
command-dispatch: tool
command-tool: test_run
command-arg-mode: raw
---

Runs all tests using the configured test framework.
Now /run-tests src/auth.test.ts calls test_run with the file argument.

​
Testing Your Skill

# Load and test your skill
profclaw skills load ./skills/my-skill/SKILL.md

# Verify it appears in the list
profclaw skills list

# Test invocation
profclaw chat --skill my-skill "test message"

Using Skills

How to invoke and manage skills.

ClawHub

Publish your skills to the community marketplace.