create-atlasclaw-skill

name	create-atlasclaw-skill
description	Create new AtlasClaw skills with proper structure, metadata, and documentation. Use when building executable skills, markdown skills, or provider skills for the AtlasClaw AI Agent.

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:

Question	Options
Skill type	executable (Python code), markdown (documentation), hybrid (both)
Category	provider:<name>, system, utility, workflow
Associated provider	Provider type (for provider skills)
Storage location	~/.qoder/skills/ (personal) or .qoder/skills/ (project)
Target keywords	Words users naturally say to trigger this skill

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: "[e-mail]"

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

Error	Cause	Resolution
INVALID_PARAM	Invalid input	Check parameter format
AUTH_FAILED	Authentication error	Check credentials

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 issues (use jira-search skill)"
• "User wants bulk operations (use jira-bulk skill)"

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

Category	Use Case	Example
provider:<name>	External system integration	provider:jira, provider:servicenow
system	OS-level operations	File operations, process management
utility	General-purpose tools	Data transformation, calculations
workflow	Multi-step processes	Approval workflows, onboarding

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