OpenCode Skills

https://github.com/ssdeanx/ai-skills
Admin
OpenCode Skills is a framework for building and managing modular AI Skills that extend AI agent...
Tokens:12,293
Snippets:192
Trust Score:7.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Basic Skill Usage Command

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Example command for executing a skill.

```bash
command --option value
```

--------------------------------

### Skill Metadata Example

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/AGENTS.md

Leverage metadata in `SKILL.md` for enhanced organization and discoverability. This example includes category, complexity, prerequisites, and tags.

```yaml
metadata:
  category: development
  complexity: intermediate
  prerequisites: git, npm
  tags: testing, quality, automation
```

--------------------------------

### Define Project Setup Skill Metadata

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/AGENTS.md

Use this YAML frontmatter structure at the beginning of a SKILL.md file to define a new skill.

```yaml
---
name: project-setup
description: Initialize new projects with proper structure, dependencies, and configuration
metadata:
  category: project-management
  audience: developers
---
```

--------------------------------

### Examples Pattern for Commit Messages

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/skill-creator/references/output-patterns.md

Provide input/output pairs to guide the AI in generating specific formats like commit messages.

```markdown
## Commit message format

Generate commit messages following these examples:

**Example 1:**
Input: Added user authentication with JWT tokens
Output:
    ```
    feat(auth): implement JWT-based authentication

    Add login endpoint and token validation middleware
    ```

**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:
    ```
    fix(reports): correct date formatting in timezone conversion

    Use UTC timestamps consistently across report generation
    ```

Follow this style: type(scope): brief description, then detailed explanation.
```

--------------------------------

### Advanced Skill Usage in Python

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Example of initializing and using a skill class in Python.

```python
# Example Python code
from skill_module import SkillClass

skill = SkillClass()
result = skill.process(data)
```

--------------------------------

### Python Logging Configuration

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Standard logging setup for tracking skill processing status and errors.

```python
import logging

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

logger = logging.getLogger(__name__)

def process_skill(skill_path: str) -> bool:
    """Process a skill with proper logging."""
    logger.info(f"Processing skill: {skill_path}")

    try:
        # Processing logic
        logger.debug("Validation step completed")
        logger.info("Skill processed successfully")
        return True

    except Exception as e:
        logger.error(f"Failed to process skill {skill_path}: {e}")
        return False
```

--------------------------------

### Initialize New Skill with CLI

Source: https://context7.com/ssdeanx/ai-skills/llms.txt

Use the init_skill.py script to create a new skill directory with a template SKILL.md file and example resource directories. Specify the skill name and the path for its creation.

```bash
python skills/skill-creator/scripts/init_skill.py data-analyzer --path skills
```

```bash
python skills/skill-creator/scripts/init_skill.py api-helper --path /custom/skills/private
```

--------------------------------

### Load Skill On-Demand

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/AGENTS.md

Agents use the `skill` tool to load skills dynamically. This example shows how to load a skill named 'code-review'.

```javascript
skill({ name: "code-review" })
```

--------------------------------

### Initialize New Skill

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/skill-creator/SKILL.md

Use this script to create a new skill directory with a template structure. It generates a SKILL.md file, and example directories for scripts, references, and assets.

```bash
scripts/init_skill.py <skill-name> --path <output-directory>
```

--------------------------------

### Skill Structure Example

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/skill-creator/SKILL.md

Illustrates the required file structure for a skill, including the SKILL.md file with its YAML frontmatter and Markdown body, and optional bundled resources like scripts, references, and assets.

```tree
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)
```

--------------------------------

### Execute Data Processing Script

Source: https://context7.com/ssdeanx/ai-skills/llms.txt

Example command for running a data processing task within a skill workflow.

```bash
python scripts/process_data.py --input data.csv --output report.json
```

--------------------------------

### Create a New Skill with Skill Creator

Source: https://github.com/ssdeanx/ai-skills/blob/main/README.md

Use the provided Python script to scaffold a new skill within the skills directory. This requires Python to be installed.

```python
python skills/skill-creator/scripts/init_skill.py my-new-skill --path skills
```

--------------------------------

### Per-Agent Skill Permissions

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/AGENTS.md

Global skill permissions can be overridden for specific agents. This example allows 'testing-*' skills for the 'build' agent.

```json
{
  "agent": {
    "build": {
      "permission": {
        "skill": {
          "testing-*": "allow"
        }
      }
    }
  }
}
```

--------------------------------

### PDF Processing with pdfplumber

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/skill-creator/SKILL.md

Use pdfplumber for extracting text from PDF files. This is a quick start example.

```markdown
# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]
```

--------------------------------

### Bun Dependency Management

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Commands for managing JavaScript/TypeScript dependencies using Bun. Includes installation, adding packages, running the development server, and building the project.

```bash
# Install dependencies
bun install
```

```bash
# Add a new dependency
bun add <package-name>
```

```bash
# Development server (if configured)
bun run dev
```

```bash
# Build project
bun run build
```

--------------------------------

### Clone OpenCode Skills Repository

Source: https://github.com/ssdeanx/ai-skills/blob/main/README.md

Clone the OpenCode Skills repository to your local configuration or project root using Git. Ensure you have Bun installed.

```bash
git clone https://github.com/ssdeanx/AI-Skills.git ~/.opencode
```

--------------------------------

### Python Dependency Management (pip)

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Commands for managing Python dependencies using pip. Installs requirements from a file or specific packages.

```bash
# Install Python requirements (if requirements.txt exists)
pip install -r requirements.txt
```

```bash
# Or install specific packages
pip install pyyaml pathlib
```

--------------------------------

### Code Review Skill Metadata

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/AGENTS.md

Example metadata for a 'code-review' skill, specifying its category, audience, and license. This helps agents understand the skill's purpose and context.

```yaml
---
name: code-review
description: Comprehensive code review following security, performance, and quality standards
license: MIT
metadata:
  category: quality-assurance
  audience: developers
---

## What I do
- Security vulnerability scanning
- Performance optimization review
- Code quality assessment
- Best practices verification
- Testing coverage evaluation

```

--------------------------------

### Define Conditional Workflow Branches

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/skill-creator/references/workflows.md

Use branching logic to guide the AI through decision points based on task requirements.

```markdown
1. Determine the modification type:
   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow: [steps]
3. Editing workflow: [steps]
```

--------------------------------

### Extract Text from PDF using pdfplumber

Source: https://context7.com/ssdeanx/ai-skills/llms.txt

Use this snippet to extract text content from PDF documents. Ensure the pdfplumber library is installed.

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        text = page.extract_text()
        print(text)
```

--------------------------------

### Load hello-world Skill

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/hello-world/SKILL.md

Use this command to load the hello-world skill and access its introductory instructions.

```javascript
skill({ name: "hello-world" })
```

--------------------------------

### Initialize New Skill (Python)

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Initialize a new skill with the proper directory structure. Specify the skill name and the path where it should be created.

```bash
python skills/skill-creator/scripts/init_skill.py <skill-name> --path skills
```

```bash
# Example: Create a new skill called "api-testing"
python skills/skill-creator/scripts/init_skill.py api-testing --path skills
```

--------------------------------

### Organizing by Domain

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/skill-creator/SKILL.md

Structure skills by domain using a reference directory for domain-specific files like finance, sales, product, and marketing.

```bash
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)
```

--------------------------------

### Organizing by Variant

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/skill-creator/SKILL.md

Organize skills by variant, such as cloud providers (AWS, GCP, Azure), using a references directory for variant-specific patterns.

```bash
cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)
```

--------------------------------

### Package a Skill

Source: https://context7.com/ssdeanx/ai-skills/llms.txt

Executes the packaging script to validate and bundle a skill directory. Packaging will abort if validation fails.

```bash
$ python skills/skill-creator/scripts/package_skill.py skills/invalid-skill
```

--------------------------------

### Package Skill for Distribution (Python)

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Package a skill into a distributable .skill file. You can specify an output directory for the packaged file.

```bash
python skills/skill-creator/scripts/package_skill.py skills/<skill-name>
```

```bash
# Package to specific output directory
python skills/skill-creator/scripts/package_skill.py skills/<skill-name> ./dist
```

```bash
# Example: Package the icon-generator skill
python skills/skill-creator/scripts/package_skill.py skills/icon-generator
```

--------------------------------

### Generate Web and Unreal Engine Icons

Source: https://context7.com/ssdeanx/ai-skills/llms.txt

Automates the creation of icon asset bundles from source images. Supports web-only targets or combined web and Unreal Engine outputs with optional customization.

```bash
python skills/icon-generator/scripts/generate_icons.py --input logo.png --out ./icons --targets web
```

```bash
python skills/icon-generator/scripts/generate_icons.py --input logo.png --out ./icons --targets web,ue
```

```bash
python skills/icon-generator/scripts/generate_icons.py \
  --input logo.png \
  --out ./icons \
  --targets web \
  --background "#4FD1C5" \
  --maskable-scale 0.75
```

```bash
python skills/icon-generator/scripts/generate_icons.py \
  --input wide-logo.png \
  --out ./icons \
  --targets web \
  --no-pad
```

```bash
python skills/icon-generator/scripts/generate_icons.py --input logo.svg --out ./icons --targets web
```

--------------------------------

### Configure Skill Permissions

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/AGENTS.md

Skill access is configured in `opencode.json` using permission types like 'allow', 'deny', and 'ask'. Wildcard patterns are supported for broader control.

```json
{
  "permission": {
    "skill": {
      "code-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask",
      "*": "allow"
    }
  }
}
```

--------------------------------

### PWA Manifest Configuration

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/icon-generator/references/web-ui-ux.md

Define the application name, display mode, and icon paths including maskable icon support.

```json
{
  "name": "My App",
  "short_name": "MyApp",
  "display": "standalone",
  "start_url": "/",
  "icons": [
    { "src": "/icon-192.png", "type": "image/png", "sizes": "192x192", "purpose": "any" },
    { "src": "/icon-512.png", "type": "image/png", "sizes": "512x512", "purpose": "any" },
    { "src": "/icon-maskable-512.png", "type": "image/png", "sizes": "512x512", "purpose": "maskable" }
  ]
}
```

--------------------------------

### SKILL.md YAML Frontmatter

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/AGENTS.md

Each skill file must begin with YAML frontmatter defining its name, description, and optional metadata. Ensure the description is action-oriented and within the specified character limits.

```yaml
---
name: skill-name
description: What this skill does and when to use it (1-1024 characters)
license: MIT  # optional
compatibility: opencode  # optional
metadata:  # optional key-value pairs
  audience: developers
  workflow: coding
---

## What I do
- Accomplishment 1
- Accomplishment 2
- Accomplishment 3

## When to use me
Describe when agents should use this skill.
Ask clarifying questions if needed.

## Instructions
Step-by-step guidance in Markdown format.

Reference supporting files: `scripts/helper.py` or `docs/api.md`
```

--------------------------------

### Skill Directory Structure

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Standard file layout for a skill project.

```text
skill-name/
├── SKILL.md              # Required: Main skill file
├── scripts/              # Optional: Executable automation
│   ├── helper.py
│   └── setup.sh
├── references/           # Optional: Documentation loaded on-demand
│   ├── api-specs.md
│   └── examples.md
└── assets/               # Optional: Files used in outputs
    ├── template.json
    └── logo.png
```

--------------------------------

### Optional YAML Frontmatter

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Extended metadata fields for a skill file.

```yaml
---
name: skill-name
description: Description of what the skill does and when to use it
license: MIT
metadata:
  category: development
  complexity: intermediate
  audience: developers
  prerequisites: git, python3
  tags: automation, tooling, productivity
---
```

--------------------------------

### Skill Supporting Files Structure

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/AGENTS.md

Organize supporting files within the skill directory using subfolders like `scripts`, `templates`, `docs`, and `assets` for maintainability.

```plaintext
skill-name/
├── SKILL.md              # Required
├── scripts/              # Executable helpers
│   └── automation.sh
├── templates/            # Reusable templates
│   └── config-template.md
├── docs/                 # Documentation
│   └── usage-examples.md
└── assets/               # Static resources
    └── diagrams/

```

--------------------------------

### Flexible Template Pattern

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/skill-creator/references/output-patterns.md

Use this template when providing a default format that allows for adaptation based on context.

```markdown
## Report structure

Here is a sensible default format, but use your best judgment:

# [Analysis Title]

## Executive summary
[Overview]

## Key findings
[Adapt sections based on what you discover]

## Recommendations
[Tailor to the specific context]

Adjust sections as needed for the specific analysis type.
```

--------------------------------

### Generate Icons (Python)

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Generate icons for web and Unreal Engine from an input SVG file. Specify the input SVG path and the output directory.

```bash
python skills/icon-generator/scripts/generate_icons.py <input-svg> <output-dir>
```

```bash
# Example: Generate icons from logo.svg
python skills/icon-generator/scripts/generate_icons.py assets/logo.svg ./output-icons
```

--------------------------------

### Required YAML Frontmatter

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Minimal required fields for a skill file.

```yaml
---
name: skill-name
description: Clear, action-oriented description under 1024 characters
---
```

--------------------------------

### Root Directory Structure

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Project-level directory organization.

```text
opencode-skills/
├── skills/               # All skill directories
├── assets/               # Project branding
├── .github/              # CI/CD and instructions
├── package.json          # Bun dependencies
├── bun.lock             # Lockfile
├── README.md            # Project documentation
└── AGENTS.md            # This file
```

--------------------------------

### Package AI Skill

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/skill-creator/SKILL.md

Use this script to package your developed AI skill into a distributable .skill file. It automatically validates the skill before packaging.

```bash
scripts/package_skill.py <path/to/skill-folder>
```

```bash
scripts/package_skill.py <path/to/skill-folder> ./dist
```

--------------------------------

### Define Sequential Workflow Steps

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/skill-creator/references/workflows.md

Use a numbered list to outline a linear process for complex tasks. This provides the AI with a clear roadmap of operations.

```markdown
Filling a PDF form involves these steps:

1. Analyze the form (run analyze_form.py)
2. Create field mapping (edit fields.json)
3. Validate mapping (run validate_fields.py)
4. Fill the form (run fill_form.py)
5. Verify output (run verify_output.py)
```

--------------------------------

### DOCX Processing with docx-js

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/skill-creator/SKILL.md

Use docx-js for creating new documents. Link to a separate file for detailed guidance.

```markdown
# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
```

--------------------------------

### Package Skill for Distribution with CLI

Source: https://context7.com/ssdeanx/ai-skills/llms.txt

The package_skill.py script packages a validated skill folder into a distributable .skill file (ZIP format). It automatically runs validation before packaging and includes all files while maintaining the directory structure.

```bash
# Package a skill to current directory
python skills/skill-creator/scripts/package_skill.py skills/icon-generator
```

```bash
# Package to specific output directory
python skills/skill-creator/scripts/package_skill.py skills/web-ui-ux ./dist
```

--------------------------------

### Validate Skill Structure with CLI and Python

Source: https://context7.com/ssdeanx/ai-skills/llms.txt

The quick_validate.py script validates skill directory structure and SKILL.md frontmatter. Programmatic usage in Python involves checking for SKILL.md, YAML frontmatter, and required fields like 'name' and 'description'.

```bash
# Using quick_validate.py from command line
# python skills/skill-creator/scripts/quick_validate.py skills/my-skill
```

```python
# Programmatic usage in Python
from pathlib import Path
import re
import yaml

def validate_skill(skill_path):
    skill_path = Path(skill_path)
    skill_md = skill_path / 'SKILL.md'

    if not skill_md.exists():
        return False, "SKILL.md not found"

    content = skill_md.read_text(encoding='utf-8')
    if not content.startswith('---'):
        return False, "No YAML frontmatter found"

    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
    if not match:
        return False, "Invalid frontmatter format"

    frontmatter = yaml.safe_load(match.group(1))

    if 'name' not in frontmatter:
        return False, "Missing 'name' in frontmatter"
    if 'description' not in frontmatter:
        return False, "Missing 'description' in frontmatter"

    return True, "Skill is valid!"

```

--------------------------------

### Unit Testing Pattern with Mocks

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Standard unit testing structure using unittest and patch for dependency isolation.

```python
import unittest
from unittest.mock import patch, MagicMock

class TestSkillValidator(unittest.TestCase):
    """Test cases for skill validation."""

    def setUp(self):
        """Set up test fixtures."""
        self.validator = SkillValidator("test-skill")

    def test_valid_skill_passes(self):
        """Test that valid skills pass validation."""
        with patch('pathlib.Path.exists', return_value=True):
            is_valid, message = self.validator.validate()
            self.assertTrue(is_valid)
            self.assertEqual(message, "Skill structure is valid")

    def test_missing_skill_md_fails(self):
        """Test that missing SKILL.md causes failure."""
        with patch('pathlib.Path.exists', return_value=False):
            is_valid, message = self.validator.validate()
            self.assertFalse(is_valid)
            self.assertIn("SKILL.md", message)

    def tearDown(self):
        """Clean up test fixtures."""
        pass

if __name__ == '__main__':
    unittest.main()
```

--------------------------------

### Task List Markdown Format

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/task-generator/SKILL.md

The standard template for task files, including relevant files, notes, and the task checklist structure.

```markdown
## Relevant Files

- `path/to/file.ts` - Brief description of why this file is relevant
- `path/to/file.test.ts` - Unit tests for file.ts
- `path/to/component.tsx` - Component description
- `path/to/component.test.tsx` - Unit tests for component.tsx

### Notes

- Unit tests should be placed alongside the code files they test
- Use `npx jest [optional/path/to/test/file]` to run tests

## Instructions for Completing Tasks

**IMPORTANT:** As you complete each task, check it off by changing `- [ ]` to `- [x]`. Update after completing each sub-task.

## Tasks

- [ ] 0.0 Create feature branch
  - [ ] 0.1 Create and checkout new branch (`git checkout -b feature/[feature-name]`)
- [ ] 1.0 [Parent Task Title]
  - [ ] 1.1 [Sub-task description]
  - [ ] 1.2 [Sub-task description]
- [ ] 2.0 [Parent Task Title]
  - [ ] 2.1 [Sub-task description]
```

--------------------------------

### Validate Skill Structure (Python)

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Use this script to validate the structure and frontmatter of a single skill. Ensure the skill path is correctly specified.

```bash
python skills/skill-creator/scripts/quick_validate.py skills/<skill-name>
```

```bash
# Example: Validate the web-ui-ux skill
python skills/skill-creator/scripts/quick_validate.py skills/web-ui-ux
```

--------------------------------

### Validate and Package a Skill

Source: https://github.com/ssdeanx/ai-skills/blob/main/README.md

Validate the structure of a newly created skill and then package it for distribution or use. These scripts are written in Python.

```python
python skills/skill-creator/scripts/quick_validate.py skills/my-new-skill
```

```python
python skills/skill-creator/scripts/package_skill.py skills/my-new-skill
```

--------------------------------

### Python Relative Imports

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Standard syntax for importing modules from local and parent directories.

```python
# Local imports (relative)
from .validators import validate_name
from ..utils.helpers import safe_read
```

--------------------------------

### HTML Head Icon Links

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/icon-generator/references/web-ui-ux.md

Include these tags in the document head to link the favicon, apple-touch-icon, and PWA manifest.

```html
<link rel="icon" href="/favicon.ico">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="192x192" href="/icon-192.png">
<link rel="icon" type="image/png" sizes="512x512" href="/icon-512.png">
<link rel="manifest" href="/manifest.webmanifest">
```

--------------------------------

### Skill Directory Structure

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/AGENTS.md

Skills are organized in specific directories for automatic discovery by OpenCode. Project-local directories have the highest priority.

```plaintext
.opencode/skill/<skill-name>/SKILL.md          # Project-local (highest priority)
~/.config/opencode/skill/<skill-name>/SKILL.md # Global config
.claude/skills/<skill-name>/SKILL.md           # Claude-compatible project
~/.claude/skills/<skill-name>/SKILL.md         # Claude-compatible global
```

--------------------------------

### Python Import Management

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Standard and third-party import structure.

```python
# Standard library imports
import sys
import re
from pathlib import Path
from typing import Dict, List, Optional

# Third-party imports
import yaml
```

--------------------------------

### Define SKILL.md Frontmatter

Source: https://context7.com/ssdeanx/ai-skills/llms.txt

Required YAML frontmatter for skill identification and AI triggering.

```yaml
---
name: my-custom-skill
description: |
  Process and analyze data files for reporting. Use when the user needs to:
  (1) Parse CSV/JSON data files, (2) Generate summary statistics,
  (3) Create formatted reports, or (4) Validate data integrity.
---
```

--------------------------------

### TypeScript ES6 and Relative Imports

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Standard module imports for TypeScript projects using ES6 syntax.

```typescript
// ES6 imports
import { readFile, writeFile } from 'fs/promises';
import { z } from 'zod';

// Relative imports
import { validateSkill } from './validators.js';
import { SkillConfig } from '../types.js';
```

--------------------------------

### Strict Template Pattern

Source: https://github.com/ssdeanx/ai-skills/blob/main/skills/skill-creator/references/output-patterns.md

Use this template for strict requirements such as API responses or rigid data formats.

```markdown
## Report structure

ALWAYS use this exact template structure:

# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```

--------------------------------

### Python File Operation Error Handling

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Pattern for safely reading files with exception handling.

```python
def safe_file_operation(file_path: str) -> Optional[str]:
    """Safely read a file with proper error handling."""
    try:
        path = Path(file_path)
        if not path.exists():
            logger.error(f"File not found: {file_path}")
            return None

        content = path.read_text(encoding='utf-8')
        return content

    except PermissionError:
        logger.error(f"Permission denied reading: {file_path}")
        return None
    except UnicodeDecodeError:
        logger.error(f"Invalid UTF-8 encoding in: {file_path}")
        return None
    except Exception as e:
        logger.error(f"Unexpected error reading {file_path}: {e}")
        return None
```

--------------------------------

### Python Skill Validator Class

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

A Python class for validating skill structures and content. It checks for the existence of the skill path and the required SKILL.md file. Includes type hints and docstrings.

```python
#!/usr/bin/env python3
"""
Module docstring describing purpose and usage.
"""

import sys
from pathlib import Path
from typing import Optional, Dict, List

# Constants in UPPER_CASE
DEFAULT_TIMEOUT = 30
MAX_RETRIES = 3

class SkillValidator:
    """Class for validating skill structures."""

    def __init__(self, skill_path: str):
        """Initialize validator with skill path.

        Args:
            skill_path: Path to the skill directory
        """
        self.skill_path = Path(skill_path)

    def validate(self) -> tuple[bool, str]:
        """Validate the skill structure and content.

        Returns:
            Tuple of (is_valid, error_message)
        """
        try:
            return self._validate_structure()
        except Exception as e:
            return False, f"Validation failed: {e}"

    def _validate_structure(self) -> tuple[bool, str]:
        """Validate basic skill directory structure."""
        if not self.skill_path.exists():
            return False, f"Skill path does not exist: {self.skill_path}"

        skill_md = self.skill_path / "SKILL.md"
        if not skill_md.exists():
            return False, "SKILL.md file is required"

        return True, "Skill structure is valid"

```

--------------------------------

### Python Skill Name Validation

Source: https://github.com/ssdeanx/ai-skills/blob/main/AGENTS.md

Function to validate skill naming conventions.

```python
def validate_skill_name(name: str) -> tuple[bool, str]:
    """Validate skill name format."""
    if not name:
        return False, "Skill name cannot be empty"

    if not re.match(r'^[a-z0-9-]+$', name):
        return False, f"Invalid name '{name}': use lowercase letters, digits, and hyphens only"

    if name.startswith('-') or name.endswith('-'):
        return False, f"Invalid name '{name}': cannot start or end with hyphen"

    if '--' in name:
        return False, f"Invalid name '{name}': cannot contain consecutive hyphens"

    if len(name) > 64:
        return False, f"Name too long ({len(name)} chars): maximum 64 characters"

    return True, "Name is valid"
```
Tokens:
Raw