Creating Skills

your-project/
  skills/
    my-skill/
      SKILL.md

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

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

{
  "profclaw": {
    "emoji": "magnifying-glass",
    "category": "development",
    "priority": 85,
    "triggerPatterns": [
      "review my code",
      "check this PR"
    ]
  }
}

## How to Execute

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

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

## Output Format

Always respond in this format:

## Summary
[1-2 sentences]

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

## Recommendations
1. First recommendation

## 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.

---
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.

# 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"