giteadmin/.dotfiles

Fork 0

Files

Jonathan Agmon c09d9151ca Add skills

2026-03-22 23:21:49 +02:00

17 KiB

Raw Blame History

Skill Templates

Copy-paste templates for common skill patterns. Use these as starting points when creating new skills.

Simple Skill (Knowledge Only)
Tool Integration Skill
Workflow Skill
Documentation Skill
Testing Your Skill

Simple Skill

For skills that provide knowledge without scripts or complex resources.

Use when: The skill provides guidance, best practices, or reference information that can be explained in text.

Directory Structure

simple-skill/
└── SKILL.md

SKILL.md Template

---
name: simple-skill
description: This skill should be used when the user asks to "TRIGGER_PHRASE_1", "TRIGGER_PHRASE_2", or needs help with SPECIFIC_TASK
license: MIT
compatibility: opencode
metadata:
  category: CATEGORY
  version: "1.0.0"
---

# Simple Skill Name

Brief description of what this skill covers.

## Overview

High-level explanation of the domain or topic.

## Common Tasks

### Task 1: Description

Step-by-step instructions:

1. First step with code example
2. Second step with code example
3. Third step

### Task 2: Description

Step-by-step instructions:

1. First step
2. Second step

## Best Practices

- Bullet point 1
- Bullet point 2
- Bullet point 3

## Important Notes

- Critical caveat 1
- Critical caveat 2

Example: Git Commit Guidelines

---
name: git-commit-guide
description: This skill should be used when the user asks to "write a commit message", "format a commit", "conventional commits", or needs help with Git commit standards
license: MIT
compatibility: opencode
---

# Git Commit Guidelines

Follow conventional commits specification for clear, structured commit messages.

## Format

():

[optional body]

[optional footer]


## Types

- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Code style (formatting, semicolons, etc)
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks

## Examples

```bash
# Feature
feat(auth): add OAuth2 login support

# Fix with scope
fix(api): resolve null pointer in user endpoint

# Breaking change
feat(db)!: migrate to PostgreSQL

Rules

Use imperative mood: "add" not "added"
Don't capitalize first letter
No period at end
Keep first line under 72 characters


---

## Tool Integration Skill

For skills that interact with command-line tools and include automation scripts.

**Use when:** The skill wraps a CLI tool, provides automation, or requires executable scripts.

### Directory Structure

tool-skill/ ├── SKILL.md ├── scripts/ │ └── helper.sh ├── references/ │ └── advanced-usage.md └── evals/ └── evals.json


### SKILL.md Template

```markdown
---
name: tool-skill
description: This skill should be used when the user asks to "TRIGGER_PHRASE_1", "run TOOL_NAME", "TOOL_NAME commands", or work with TOOL_NAME
license: MIT
compatibility: opencode
metadata:
  category: tools
  version: "1.0.0"
---

# Tool Name Integration

Interact with TOOL_NAME for SPECIFIC_PURPOSE.

## Quick Start

Basic usage:

```bash
tool-name --option value

Common Operations

Operation 1: Description

# Example command
tool-name command --flag

Explanation of what this does.

Operation 2: Description

# Example command
tool-name another-command

Scripts

Use helper scripts in scripts/:

scripts/helper.sh - What this script does

Advanced Usage

For detailed options and edge cases, see references/advanced-usage.md.

Important Notes

Requirement 1
Requirement 2
Common pitfall


### scripts/helper.sh Template

```bash
#!/bin/bash
#
# Helper script for TOOL_NAME operations
#

set -euo pipefail

# Configuration
DEFAULT_OPTION="value"

# Functions
show_help() {
    cat << EOF
Usage: $0 [OPTIONS]

Helper script for TOOL_NAME

Options:
    -h, --help      Show this help message
    -v, --verbose   Enable verbose output
    -o, --option    Specify option value

Examples:
    $0 --verbose
    $0 --option custom-value
EOF
}

# Parse arguments
VERBOSE=false
OPTION="$DEFAULT_OPTION"

while [[ $# -gt 0 ]]; do
    case $1 in
        -h|--help)
            show_help
            exit 0
            ;;
        -v|--verbose)
            VERBOSE=true
            shift
            ;;
        -o|--option)
            OPTION="$2"
            shift 2
            ;;
        *)
            echo "Unknown option: $1"
            show_help
            exit 1
            ;;
    esac
done

# Main logic
main() {
    [[ "$VERBOSE" == true ]] && echo "Running with option: $OPTION"
    
    # Your tool integration logic here
    echo "Helper script executed successfully"
}

main "$@"

Example: Docker Helper

---
name: docker-helper
description: This skill should be used when the user asks to "manage docker containers", "build docker images", "docker compose operations", or work with Docker workflows
license: MIT
compatibility: opencode
---

# Docker Helper

Streamline Docker container and image management.

## Quick Commands

### List Running Containers

```bash
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Clean Up System

# Remove stopped containers, unused networks, dangling images
docker system prune -f

Scripts

Use helper scripts:

scripts/container-logs.sh - View and follow container logs
scripts/cleanup.sh - Safe cleanup of unused resources

Docker Compose

Start Services

docker compose up -d SERVICE_NAME

View Logs

docker compose logs -f SERVICE_NAME

References

references/compose-patterns.md - Advanced compose configurations
references/troubleshooting.md - Common issues and solutions


---

## Workflow Skill

For skills that guide multi-step processes or complex procedures.

**Use when:** The skill orchestrates a sequence of steps, decisions, or collaborative tasks.

### Directory Structure

workflow-skill/ ├── SKILL.md ├── scripts/ │ ├── step-validator.sh │ └── automation.sh ├── references/ │ ├── decision-matrix.md │ └── examples/ │ └── sample-workflow.md └── evals/ └── evals.json


### SKILL.md Template

```markdown
---
name: workflow-skill
description: This skill should be used when the user asks to "WORKFLOW_NAME", "perform WORKFLOW_TASK", "WORKFLOW_VERB process", or needs help with WORKFLOW_DOMAIN
license: MIT
compatibility: opencode
metadata:
  category: workflow
  version: "1.0.0"
---

# Workflow Name

Guide the WORKFLOW_PROCESS from start to finish with validation at each step.

## Prerequisites

Before starting, ensure:

1. Requirement 1
2. Requirement 2
3. Requirement 3

## Workflow Overview

Step 1 → Step 2 → Step 3 → Completion ↓ ↓ ↓ Validate Validate Validate


## Step-by-Step Process

### Step 1: Preparation

**Objective:** What to accomplish in this step

**Actions:**
1. Action item 1
2. Action item 2

**Validation:**
- [ ] Check item 1
- [ ] Check item 2

**Script:** `scripts/step-validator.sh --step 1`

### Step 2: Execution

**Objective:** What to accomplish in this step

**Actions:**
1. Action item 1
2. Action item 2

**Validation:**
- [ ] Check item 1
- [ ] Check item 2

**Decision Point:**

If CONDITION_A:
- Follow path A (see `references/path-a.md`)

If CONDITION_B:
- Follow path B (see `references/path-b.md`)

### Step 3: Verification

**Objective:** Final checks and completion

**Actions:**
1. Run verification command
2. Review output

**Validation:**
- [ ] All checks pass
- [ ] No errors in logs

## Automation

For automated execution:

```bash
scripts/automation.sh --full

Troubleshooting

See references/troubleshooting.md for common issues.

Examples

Complete workflow examples in references/examples/.


### Example: Release Workflow

```markdown
---
name: release-workflow
description: This skill should be used when the user asks to "create a release", "publish a new version", "tag a release", or prepare software for deployment
license: MIT
compatibility: opencode
---

# Release Workflow

Guide the complete release process from version bump to deployment.

## Prerequisites

- [ ] All tests passing
- [ ] CHANGELOG.md updated
- [ ] Version number decided

## Workflow

### Step 1: Pre-Release Checks

**Actions:**
1. Run full test suite: `npm test`
2. Verify CHANGELOG.md is current
3. Check for uncommitted changes

**Validation:**
```bash
scripts/pre-release-check.sh

Step 2: Version Bump

Actions:

Update version in package.json
Update CHANGELOG.md with release date
Commit with message: chore(release): bump version to X.Y.Z

Validation:

Version updated in all files
CHANGELOG.md has date
Commit created

Step 3: Create Tag

Actions:

Create annotated tag: git tag -a vX.Y.Z -m "Release X.Y.Z"
Push tag: git push origin vX.Y.Z

Validation:

scripts/verify-tag.sh vX.Y.Z

Step 4: GitHub Release

Actions:

Draft release notes from CHANGELOG
Create GitHub release
Attach artifacts if needed

Command:

gh release create vX.Y.Z --notes-from-tag

Decision Matrix

See references/decision-matrix.md for:

Version numbering (semver vs calver)
Pre-release vs stable
Hotfix procedures


---

## Documentation Skill

For skills focused on writing, reviewing, or managing documentation.

**Use when:** The skill helps create documentation, enforces standards, or provides writing guidelines.

### Directory Structure

docs-skill/ ├── SKILL.md ├── references/ │ ├── style-guide.md │ ├── templates/ │ │ ├── README-template.md │ │ └── API-doc-template.md │ └── examples/ │ └── sample-docs/ ├── assets/ │ └── diagram-template.png └── evals/ └── evals.json


### SKILL.md Template

```markdown
---
name: docs-skill
description: This skill should be used when the user asks to "write documentation", "create a README", "document this code", "review docs", or needs help with technical writing
license: MIT
compatibility: opencode
metadata:
  category: documentation
  version: "1.0.0"
---

# Documentation Helper

Create clear, consistent, and effective technical documentation.

## Quick Start

### Create README

Start with the template:

```bash
cp references/templates/README-template.md ./README.md

Then fill in:

Project name and description
Installation steps
Usage examples
API reference (if applicable)

Documentation Types

README.md

Essential sections:

Title and description
Installation
Quick start
Usage examples
API reference (if applicable)
Contributing
License

Use template: references/templates/README-template.md

API Documentation

Structure:

Endpoint description
Request format
Response format
Error codes
Examples

Use template: references/templates/API-doc-template.md

Code Comments

Follow style guide in references/style-guide.md:

JSDoc for JavaScript
Docstrings for Python
Rustdoc for Rust

Style Guide

See references/style-guide.md for:

Tone and voice
Formatting rules
Terminology
Code example standards

Review Checklist

Before finalizing documentation:

Clear and concise
No typos or grammar errors
Code examples work
All links functional
Proper heading hierarchy
Consistent formatting

Examples

Review well-documented projects in references/examples/.

Assets

assets/diagram-template.png - Template for architecture diagrams


### Example: API Documentation Helper

```markdown
---
name: api-docs-helper
description: This skill should be used when the user asks to "document an API", "create API documentation", "write endpoint docs", or needs help with REST API documentation
license: MIT
compatibility: opencode
---

# API Documentation Helper

Create comprehensive REST API documentation following OpenAPI standards.

## Endpoint Documentation Template

For each endpoint, document:

### 1. Overview

```markdown
## POST /api/v1/resource

Brief description of what this endpoint does.

**Authorization:** Required (Bearer token)
**Rate Limit:** 100 requests/minute

2. Request

### Headers

| Header | Value | Required |
|--------|-------|----------|
| Content-Type | application/json | Yes |
| Authorization | Bearer {token} | Yes |

### Body

```json
{
  "field1": "string (required) - Description",
  "field2": "number (optional) - Description"
}


### 3. Response

```markdown
### Success (200 OK)

```json
{
  "id": "string",
  "created_at": "ISO 8601 datetime",
  "status": "active"
}

Error Responses

400 Bad Request - Invalid input
401 Unauthorized - Missing/invalid token
404 Not Found - Resource doesn't exist


### 4. Examples

Provide curl and client library examples.

## Standards

Follow conventions in `references/api-standards.md`:
- Use JSON for request/response bodies
- ISO 8601 for dates
- snake_case for field names
- Include pagination metadata for lists

## Tools

Validate documentation:
- `scripts/validate-openapi.sh` - Check OpenAPI spec
- `scripts/check-examples.sh` - Verify code examples work

Testing Your Skill

After creating a skill from these templates, follow this testing workflow:

Step 1: Create Test Cases

Generate test cases for your skill:

~/.config/opencode/skills/skill-builder/scripts/create-tests.sh ~/.config/opencode/skills/your-skill

This creates evals/evals.json with 3 template test cases:

Common Case - Typical usage scenario
Edge Case - Tricky or unusual situation
Varied Phrasing - Same intent, different words

Step 2: Customize Test Prompts

Edit evals/evals.json and replace placeholder text with realistic test prompts:

Good test prompt:

Convert the CSV file at ./data/sales.csv to JSON and save it as ./output/sales.json. 
The CSV has headers: date, product, quantity, price. Make sure dates are in ISO 8601 format.

Bad test prompt:

Convert CSV to JSON

See eval-templates.md for copy-paste templates for different skill types.

Step 3: Run Tests

Execute the test workflow:

~/.config/opencode/skills/skill-builder/scripts/run-tests.sh ~/.config/opencode/skills/your-skill

This will:

Display each test prompt
Guide you through manual testing in opencode
Record your evaluations (pass/fail/skip)
Save results to evals/test-results.json

Step 4: Grade Results

Use the grading checklist for systematic evaluation:

~/.config/opencode/skills/skill-builder/scripts/grade-output.sh ~/.config/opencode/skills/your-skill

This evaluates:

Correctness
Completeness
Format
Triggering
Efficiency

And generates evals/grading-report.json with structured feedback.

Step 5: Iterate

Based on test results, improve your skill:

Review issues in grading report
Update SKILL.md with fixes
Re-run tests
Repeat until satisfied

See grading-guide.md for detailed evaluation criteria and decision frameworks.

Testing by Skill Type

Simple Skills:

May not need formal test cases
Test manually with 2-3 realistic prompts
Verify outputs are helpful and accurate

Tool Integration Skills:

Must test all commands work when copied
Verify edge cases (errors, conflicts)
Test with different tool versions if possible

Workflow Skills:

Test complete end-to-end flow
Verify each step produces correct result
Test decision points and branches
Check error recovery paths

Code Generation Skills:

Verify generated code is syntactically valid
Test that code actually runs
Check edge cases (empty input, large data)
Validate error handling

When to Stop Testing

Stop iterating when:

All critical test cases pass
User is satisfied with quality
Common scenarios work reliably
No longer making meaningful improvements

Remember: A skill that works well for 90% of cases is sufficient. Perfection is the enemy of good.

Tips for All Templates

Replace placeholders immediately - Search for TRIGGER_PHRASE, TOOL_NAME, etc.
Write description first - Include 3-5 specific trigger phrases in quotes
Keep examples working - Test all code examples before finalizing
Validate early and often - Run validation after every significant change
Progressive disclosure - Move details to references/ as the skill grows
Be specific - Generic skills don't trigger well. Make descriptions concrete.
Test triggers - After creating, try phrases from your description to verify activation

Validation Checklist for New Skills

Before considering a skill complete:

SKILL.md created with proper frontmatter
name matches directory name
description is 20-1024 characters with trigger phrases
No second-person writing in body
All scripts are executable
Referenced files exist and are mentioned in SKILL.md
Validation passes: validate-skill.sh /path/to/skill
Test cases created in evals/evals.json
Tests pass or issues documented
Tested with actual trigger phrases

17 KiB Raw Blame History

Skill Templates

Table of Contents

Simple Skill

Directory Structure

SKILL.md Template

Example: Git Commit Guidelines

Rules

Common Operations

Operation 1: Description

Operation 2: Description

Scripts

Advanced Usage

Important Notes

Example: Docker Helper

Clean Up System

Scripts

Docker Compose

Start Services

View Logs

References

Troubleshooting

Examples

Step 2: Version Bump

Step 3: Create Tag

Step 4: GitHub Release

Decision Matrix

Documentation Types

README.md

API Documentation

Code Comments

Style Guide

Review Checklist

Examples

Assets

2. Request

Error Responses

Testing Your Skill

Step 1: Create Test Cases

Step 2: Customize Test Prompts

Step 3: Run Tests

Step 4: Grade Results

Step 5: Iterate

Testing by Skill Type

When to Stop Testing

Tips for All Templates

Validation Checklist for New Skills

17 KiB

Raw Blame History