Charon/.github/skills/README.md

Agent Skills - Charon Project

This directory contains Agent Skills following the agentskills.io specification for AI-discoverable, executable tasks.

Overview

Agent Skills are self-documenting, AI-discoverable task definitions that combine YAML frontmatter (metadata) with Markdown documentation. Each skill represents a specific task or workflow that can be executed by both humans and AI assistants.

Location: .github/skills/ is the VS Code Copilot standard location for Agent Skills Format: Skills follow the agentskills.io specification for structure and metadata

Directory Structure

.github/skills/
├── README.md                           # This file
├── scripts/                            # Shared infrastructure scripts
│   ├── skill-runner.sh                # Universal skill executor
│   ├── validate-skills.py             # Frontmatter validation tool
│   ├── _logging_helpers.sh            # Logging utilities
│   ├── _error_handling_helpers.sh     # Error handling utilities
│   └── _environment_helpers.sh        # Environment validation
├── examples/                           # Example skill templates
└── {skill-name}/                      # Individual skill directories
    ├── SKILL.md                       # Skill definition and documentation
    └── scripts/
        └── run.sh                     # Skill execution script

Available Skills

Testing Skills

Skill Name	Category	Description	Status
test-backend-coverage	test	Run Go backend tests with coverage analysis	✅ Active
test-backend-unit	test	Run fast Go unit tests without coverage	✅ Active
test-frontend-coverage	test	Run frontend tests with coverage reporting	✅ Active
test-frontend-unit	test	Run fast frontend unit tests without coverage	✅ Active
test-e2e-playwright	test	Run Playwright E2E tests with browser selection	✅ Active
test-e2e-playwright-debug	test	Run E2E tests in headed/debug mode for troubleshooting	✅ Active
test-e2e-playwright-coverage	test	Run E2E tests with coverage collection	✅ Active

Integration Testing Skills

Skill Name	Category	Description	Status
integration-test-all	integration	Run all integration tests in sequence	✅ Active
integration-test-coraza	integration	Test Coraza WAF integration	✅ Active
integration-test-crowdsec	integration	Test CrowdSec bouncer integration	✅ Active
integration-test-crowdsec-decisions	integration	Test CrowdSec decisions API	✅ Active
integration-test-crowdsec-startup	integration	Test CrowdSec startup sequence	✅ Active

Security Skills

Skill Name	Category	Description	Status
security-scan-gorm	security	Detect GORM ID leaks, exposed secrets, and misconfigurations	✅ Active
security-scan-trivy	security	Run Trivy vulnerability scanner	✅ Active
security-scan-go-vuln	security	Run Go vulnerability check	✅ Active

QA Skills

Skill Name	Category	Description	Status
qa-lefthook-all	qa	Run all lefthook pre-commit‑phase hooks on entire codebase	✅ Active

Utility Skills

Skill Name	Category	Description	Status
utility-version-check	utility	Validate version matches git tag	✅ Active
utility-clear-go-cache	utility	Clear Go build and module caches	✅ Active
utility-bump-beta	utility	Increment beta version number	✅ Active
utility-db-recovery	utility	Database integrity check and recovery	✅ Active

Docker Skills

Skill Name	Category	Description	Status
docker-start-dev	docker	Start development Docker Compose environment	✅ Active
docker-stop-dev	docker	Stop development Docker Compose environment	✅ Active
docker-rebuild-e2e	docker	Rebuild Docker image and restart E2E Playwright container	✅ Active
docker-prune	docker	Clean up unused Docker resources	✅ Active

Usage

Running Skills

Use the universal skill runner to execute any skill:

# From project root
.github/skills/scripts/skill-runner.sh <skill-name> [args...]

# Example: Run backend coverage tests
.github/skills/scripts/skill-runner.sh test-backend-coverage

From VS Code Tasks

Skills are integrated with VS Code tasks (.vscode/tasks.json):

1. Open Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
2. Select Tasks: Run Task
3. Choose the task (e.g., Test: Backend with Coverage)

In CI/CD Workflows

Reference skills in GitHub Actions:

- name: Run Backend Tests with Coverage
  run: .github/skills/scripts/skill-runner.sh test-backend-coverage

Validation

Validate a Single Skill

python3 .github/skills/scripts/validate-skills.py --single .github/skills/test-backend-coverage/SKILL.md

Validate All Skills

python3 .github/skills/scripts/validate-skills.py

Validation Checks

The validator ensures:

• ✅ Required frontmatter fields are present
• ✅ Field formats are correct (name, version, description)
• ✅ Tags meet minimum/maximum requirements
• ✅ Compatibility information is valid
• ✅ Custom metadata follows project conventions

Creating New Skills

1. Create Skill Directory Structure

mkdir -p .github/skills/{skill-name}/scripts

2. Create SKILL.md

Start with the template structure:

---
# agentskills.io specification v1.0
name: "skill-name"
version: "1.0.0"
description: "Brief description (max 120 chars)"
author: "Charon Project"
license: "MIT"
tags:
  - "tag1"
  - "tag2"
compatibility:
  os:
    - "linux"
    - "darwin"
  shells:
    - "bash"
requirements:
  - name: "tool"
    version: ">=1.0"
    optional: false
metadata:
  category: "category-name"
  execution_time: "short|medium|long"
  risk_level: "low|medium|high"
  ci_cd_safe: true|false
---

# Skill Name

## Overview

Brief description of what this skill does.

## Prerequisites

- List prerequisites

## Usage

```bash
.github/skills/scripts/skill-runner.sh skill-name

Examples

Example 1: Basic Usage

# Example command

---

Last Updated: YYYY-MM-DD Maintained by: Charon Project

### 3. Create Execution Script

Create `scripts/run.sh` with proper structure:

```bash
#!/usr/bin/env bash
set -euo pipefail

# Source helper scripts
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILLS_SCRIPTS_DIR="$(cd "${SCRIPT_DIR}/../../scripts" && pwd)"

source "${SKILLS_SCRIPTS_DIR}/_logging_helpers.sh"
source "${SKILLS_SCRIPTS_DIR}/_error_handling_helpers.sh"
source "${SKILLS_SCRIPTS_DIR}/_environment_helpers.sh"

PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"

# Validate environment
log_step "ENVIRONMENT" "Validating prerequisites"
# Add validation calls here

# Execute skill logic
log_step "EXECUTION" "Running skill"
cd "${PROJECT_ROOT}"

# Your skill logic here

log_success "Skill completed successfully"

4. Set Permissions

chmod +x .github/skills/{skill-name}/scripts/run.sh

5. Validate

python3 .github/skills/scripts/validate-skills.py --single .github/skills/{skill-name}/SKILL.md

6. Test

.github/skills/scripts/skill-runner.sh {skill-name}

Naming Conventions

• Skill Names: {category}-{feature}-{variant} (kebab-case)
• Categories: test, integration-test, security, qa, build, utility, docker
• Examples:
  • test-backend-coverage
  • integration-test-crowdsec
  • security-scan-trivy
  • utility-version-check

Best Practices

Documentation

• Keep SKILL.md under 500 lines
• Use progressive disclosure (link to extended docs for complex topics)
• Include practical examples
• Document all prerequisites and environment variables

Scripts

• Always source helper scripts for consistent logging and error handling
• Validate environment before execution
• Use set -euo pipefail for robust error handling
• Make scripts idempotent when possible
• Clean up resources on exit

Metadata

• Use accurate execution_time values for scheduling
• Set ci_cd_safe: false for skills requiring human oversight
• Mark idempotent: true only if truly safe to run multiple times
• Include all required dependencies in requirements

Error Handling

• Use helper functions (log_error, error_exit, check_command_exists)
• Provide clear error messages with remediation steps
• Return appropriate exit codes (0 = success, non-zero = failure)

Helper Scripts Reference

Logging Helpers (_logging_helpers.sh)

log_info "message"      # Informational message
log_success "message"   # Success message (green)
log_warning "message"   # Warning message (yellow)
log_error "message"     # Error message (red)
log_debug "message"     # Debug message (only if DEBUG=1)
log_step "STEP" "msg"   # Step header
log_command "cmd"       # Log command before executing

Error Handling Helpers (_error_handling_helpers.sh)

error_exit "message" [exit_code]              # Print error and exit
check_command_exists "cmd" ["message"]        # Verify command exists
check_file_exists "file" ["message"]          # Verify file exists
check_dir_exists "dir" ["message"]            # Verify directory exists
run_with_retry max_attempts delay cmd...      # Retry command with backoff
trap_error [script_name]                      # Set up error trapping
cleanup_on_exit cleanup_func                  # Register cleanup function

Environment Helpers (_environment_helpers.sh)

validate_go_environment ["min_version"]       # Check Go installation
validate_python_environment ["min_version"]   # Check Python installation
validate_node_environment ["min_version"]     # Check Node.js installation
validate_docker_environment                   # Check Docker installation
set_default_env "VAR" "default_value"        # Set env var with default
validate_project_structure file1 file2...     # Check required files exist
get_project_root ["marker_file"]             # Find project root directory

Troubleshooting

Skill not found

Error: Skill not found: skill-name

Solution: Verify the skill directory exists in .github/skills/ and contains a SKILL.md file

Skill script not executable

Error: Skill execution script is not executable

Solution: Run chmod +x .github/skills/{skill-name}/scripts/run.sh

Validation errors

[ERROR] skill.SKILL.md :: description: Must be 120 characters or less

Solution: Fix the frontmatter field according to the error message and re-validate

Command not found in skill

Error: go is not installed or not in PATH

Solution: Install the required dependency or ensure it's in your PATH

Integration Points

VS Code Tasks

Skills are integrated in .vscode/tasks.json:

{
    "label": "Test: Backend with Coverage",
    "type": "shell",
    "command": ".github/skills/scripts/skill-runner.sh test-backend-coverage",
    "group": "test"
}

GitHub Actions

Skills are referenced in .github/workflows/:

- name: Run Backend Tests with Coverage
  run: .github/skills/scripts/skill-runner.sh test-backend-coverage

Pre-commit Hooks

Skills can be used in .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: backend-coverage
        name: Backend Coverage Check
        entry: .github/skills/scripts/skill-runner.sh test-backend-coverage
        language: system

Resources

• agentskills.io Specification
• VS Code Copilot Agent Skills
• Project Documentation
• Contributing Guide

Support

For issues, questions, or contributions:

1. Check existing GitHub Issues
2. Review CONTRIBUTING.md
3. Create a new issue if needed

---

Last Updated: 2025-12-20 Maintained by: Charon Project Team License: MIT