Create AtlasClaw Skill

Guide for creating new skills that extend the AtlasClaw AI Agent's capabilities.

Quick Start Checklist

Skill Creation Progress:
- [ ] 1. Gather requirements (skill type, purpose, triggers)
- [ ] 2. Choose storage location (personal or project)
- [ ] 3. Create skill directory structure
- [ ] 4. Write SKILL.md with LLM context fields
- [ ] 5. Implement handler (for executable skills)
- [ ] 6. Test skill loading and execution

Phase 1: Gather Requirements

Before creating a skill, determine:

Phase 2: Directory Structure

Create skill at: {location}/skills/{skill-name}/

Minimal Structure (Markdown Skill)

skills/{skill-name}/
└── SKILL.md              # Required - skill metadata and documentation

Complete Structure (Executable Skill)

skills/{skill-name}/
├── SKILL.md              # Required - skill metadata
├── README.md             # Optional - extended documentation
├── scripts/              # Required for executable skills
│   ├── __init__.py
│   └── handler.py        # Main implementation
├── tests/                # Optional - test files
│   └── test_handler.py
└── references/           # Optional - reference docs
    └── api_reference.md

Phase 3: SKILL.md Template

---
name: "{skill-name}"
description: "Brief description. Trigger when user wants to {action}."
category: "{category}"
provider_type: "{provider}"           # For provider skills only
instance_required: "{true|false}"     # For provider skills only
version: "1.0.0"
author: "your@email.com"

# === LLM Context Fields (for Skill Discovery) ===
triggers:
  - action phrase 1
  - action phrase 2

use_when:
  - User intent scenario 1
  - User intent scenario 2

avoid_when:
  - Scenario when other skill is better

examples:
  - "Example user input 1"
  - "Example user input 2"

related:
  - related-skill-1
  - related-skill-2

# === Tool Registration (for executable skills) ===
tool_name: "{skill_name}"
tool_entrypoint: "scripts/handler.py:handler"
---

# {skill-name}

## Purpose

What this skill does and when to use it.

## Parameters

### Input

| Name | Type | Required | Description |
|------|------|----------|-------------|
| param1 | string | Yes | Description |
| param2 | integer | No | Description (default: 10) |

### Output

| Name | Type | Description |
|------|------|-------------|
| success | boolean | Whether operation succeeded |
| message | string | Human-readable result |
| data | object | Structured result data |

## Usage Examples

### Example 1: Basic Usage

Input:
```json
{
  "param1": "value1"
}

Output:

{
  "success": true,
  "message": "Operation completed",
  "data": { "result": "value" }
}

Error Handling

Common Errors

Related Skills

• related-skill - Description

Notes

Additional information, limitations, or considerations.

## Phase 4: Handler Template (Executable Skills)

Create `scripts/handler.py`:

```python
# -*- coding: utf-8 -*-
"""
{Skill Name} Handler

Implements the {action} functionality.
"""
from __future__ import annotations

import argparse
import json
import os
import sys
from typing import Any


def handler(params: dict[str, Any]) -> dict[str, Any]:
    """
    Main handler function.
    
    Args:
        params: Input parameters
        
    Returns:
        Result dictionary with success, message, and data
    """
    try:
        # Implement skill logic here
        result = process_request(params)
        
        return {
            "success": True,
            "message": "Operation completed successfully",
            "data": result
        }
    except ValueError as e:
        return {
            "success": False,
            "message": f"Invalid input: {str(e)}",
            "error": {"code": "INVALID_PARAM", "details": str(e)}
        }
    except Exception as e:
        return {
            "success": False,
            "message": f"Error: {str(e)}",
            "error": {"code": "EXECUTION_ERROR", "details": str(e)}
        }


def process_request(params: dict[str, Any]) -> dict[str, Any]:
    """Process the request and return result."""
    # Implement business logic here
    return {"result": "success"}


def main():
    """CLI entry point."""
    parser = argparse.ArgumentParser(description="{Skill description}")
    parser.add_argument("--param1", required=True, help="Parameter 1")
    parser.add_argument("--param2", type=int, default=10, help="Parameter 2")
    
    args = parser.parse_args()
    
    result = handler({
        "param1": args.param1,
        "param2": args.param2
    })
    
    print(json.dumps(result, indent=2))
    sys.exit(0 if result["success"] else 1)


if __name__ == "__main__":
    main()

Phase 5: Skill Types Reference

1. Markdown Skills (Documentation)

For providing knowledge without executable code:

---
name: "coding-standards"
description: "Apply team coding standards and best practices. Use when reviewing code or discussing implementation approaches."
category: "utility"
---

# Coding Standards

## Python Style

- Use type hints on all functions
- Follow PEP 8 naming conventions
- Maximum line length: 100 characters

## Error Handling

- Use specific exception types
- Include context in error messages
- Return structured error responses

2. Executable Skills (Python)

For performing actions:

---
name: "file-reader"
description: "Read and parse file contents. Trigger when user wants to read files."
category: "system"

triggers:
  - read file
  - parse file

use_when:
  - User wants to read file contents
  - User needs to parse a file

tool_name: "file_reader"
tool_entrypoint: "scripts/handler.py:handler"
---

3. Provider Skills

For integrating with external systems:

---
name: "jira-issue"
description: "Jira issue skill for CRUD operations. Trigger when user wants to manage Jira issues."
category: "provider:jira"
provider_type: "jira"
instance_required: "true"

triggers:
  - create issue
  - update issue

use_when:
  - User wants to create or update Jira issues

tool_create_name: "jira_issue_create"
tool_create_entrypoint: "scripts/create_issue.py:handler"
---

Phase 6: Verification

1. Check file location:

   ls -la {workspace}/skills/{skill-name}/

2. Restart service (or wait for hot reload)
3. Check logs for skill loading:

   [AtlasClaw] Skills loaded: X executable, Y markdown

4. Test via API:

   curl http://localhost:8000/api/skills | grep {skill-name}

LLM Context Best Practices

Triggers

• Use action-oriented phrases
• Include synonyms and variations
• Focus on user intent, not technical terms

Good triggers:

• create issue, report bug, log incident
• read file, parse document
• analyze data, generate report

use_when

• Describe user scenarios, not technical capabilities
• Focus on business value
• Include common phrasings

Good use_when:

• "User wants to create a bug report"
• "User needs to read file contents"
• "User asks about incident details"

avoid_when

• Critical for disambiguation
• Always suggest the correct alternative
• Include commonly confused scenarios

Good avoid_when:

• "User wants to search multiple records; use a provider search skill if one is available"
• "User wants bulk operations; use a provider bulk-operation skill if one is available"

Examples

• Provide concrete, realistic examples
• Include variations in phrasing
• Show both simple and complex cases

Good examples:

• "Create a Jira issue for the login bug"
• "Get details for PROJ-123"
• "Update the priority of INC0012345 to High"

Skill Categories

Common Skill Patterns

File Operations

triggers:
  - read file
  - parse file
  - analyze document

use_when:
  - User wants to read or parse file contents
  - User needs to extract data from files

Data Analysis

triggers:
  - analyze data
  - generate report
  - calculate metrics

use_when:
  - User wants to analyze data
  - User needs reports or metrics

API Integration

triggers:
  - create issue
  - update record
  - query data

use_when:
  - User wants to interact with external system
  - User needs to create or update records

Additional Resources

• SKILL_GUIDE.md - Full skill development guide
• Jira Skill - Reference implementation
• create-atlasclaw-provider skill - For creating providers