### Data Migration Script Example (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/examples/backend-api-master/datasets/db_best_practices.md

Shows a Python example for a data migration script using Alembic's `op` object. This script demonstrates updating data within the database schema during a migration.

```python
# migrations/versions/002_migrate_user_data.py
def upgrade():
    # Migrate data from old schema to new schema
    op.execute("""
        UPDATE users 
        SET full_name = CONCAT(first_name, ' ', last_name)
        WHERE full_name IS NULL
    """)

def downgrade():
    # Reverse the migration if needed
    pass
```

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

### SQL Indexing Strategies

Source: https://github.com/longcipher/omni-skill/blob/master/examples/backend-api-master/datasets/db_best_practices.md

Provides examples of creating various types of SQL indexes to optimize query performance. Includes single-column, composite, and partial indexes for different querying needs.

```sql
-- Create index on foreign keys
CREATE INDEX idx_user_id ON orders(user_id);

-- Create composite index for common query patterns
CREATE INDEX idx_status_created ON orders(status, created_at);

-- Create partial index for filtered queries
CREATE INDEX idx_active_users ON users(email) WHERE status = 'active';
```

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

### Install OmniSkill using uv

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Installs the omniskill package using the uv package manager. This is the recommended installation method for its speed and efficiency.

```bash
uv add omniskill
```

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

### Generate Skill with Custom Options (CLI Example)

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Provides an example of the `omniskill generate` command with custom options for skill name and output directory, demonstrating flexibility in skill creation.

```bash
omniskill generate data/api-specs/ --name api-assistant --output skills/api-assistant/
```

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

### Install OmniSkill from Source

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Clones the omni-skill repository and installs dependencies using uv. This method is useful for development or when needing the latest unreleased features.

```bash
git clone https://github.com/longcipher/omni-skill.git
cd omni-skill
uv sync --all-groups
```

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

### FastAPI JWT Dependency Injection

Source: https://github.com/longcipher/omni-skill/blob/master/examples/backend-api-master/datasets/auth_patterns.md

Demonstrates how to integrate JWT verification into FastAPI routes using the HTTPBearer security scheme. It extracts credentials from the Authorization header and raises HTTP 401 exceptions on failure.

```python
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials

security = HTTPBearer()

async def get_current_user(
    credentials: HTTPAuthorizationCredentials = Depends(security)
) -> dict:
    """Extract and verify the current user from JWT token."""
    token = credentials.credentials
    try:
        payload = verify_jwt_token(token, SECRET_KEY)
        return payload
    except ValueError as e:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail=str(e)
        )
```

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

### Install OmniSkill using pip

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Installs the omniskill package using the pip package manager. This is a standard method for installing Python packages.

```bash
pip install omniskill
```

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

### API Key Generation and Header Validation

Source: https://github.com/longcipher/omni-skill/blob/master/examples/backend-api-master/datasets/auth_patterns.md

Provides methods for generating cryptographically secure API keys and validating them via request headers in a FastAPI application. This is intended for service-to-service communication.

```python
import secrets
from fastapi import Header, HTTPException

def generate_api_key() -> str:
    """Generate a secure API key."""
    return secrets.token_urlsafe(32)

async def verify_api_key(x_api_key: str = Header(...)) -> str:
    """Verify the API key from request headers."""
    if x_api_key not in VALID_API_KEYS:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Invalid API key"
        )
    return x_api_key
```

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

### Database Error Handling (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/examples/backend-api-master/datasets/db_best_practices.md

Provides an example of handling specific database exceptions like `IntegrityError` and `OperationalError` in Python using SQLAlchemy. Includes rollback logic and user-friendly error messages.

```python
from sqlalchemy.exc import IntegrityError, OperationalError

def create_user(session: Session, user_data: dict):
    """Create a user with proper error handling."""
    try:
        user = User(**user_data)
        session.add(user)
        session.commit()
        return user
    except IntegrityError as e:
        session.rollback()
        if "unique constraint" in str(e):
            raise ValueError("User with this email already exists")
        raise
    except OperationalError as e:
        session.rollback()
        raise RuntimeError(f"Database error: {e}")
```

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

### Create and Verify JWT Tokens in Python

Source: https://github.com/longcipher/omni-skill/blob/master/examples/backend-api-master/datasets/auth_patterns.md

Provides utility functions to generate signed JWT tokens with expiration claims and verify them using the PyJWT library. It handles token expiration and integrity validation through HS256 algorithm.

```python
import jwt
from datetime import datetime, timedelta

def create_jwt_token(user_id: str, secret_key: str) -> str:
    """Create a JWT token for user authentication."""
    payload = {
        "user_id": user_id,
        "exp": datetime.utcnow() + timedelta(hours=24),
        "iat": datetime.utcnow()
    }
    return jwt.encode(payload, secret_key, algorithm="HS256")

def verify_jwt_token(token: str, secret_key: str) -> dict:
    """Verify and decode a JWT token."""
    try:
        payload = jwt.decode(token, secret_key, algorithms=["HS256"])
        return payload
    except jwt.ExpiredSignatureError:
        raise ValueError("Token has expired")
    except jwt.InvalidTokenError:
        raise ValueError("Invalid token")
```

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

### Alembic Migration Commands (Bash)

Source: https://github.com/longcipher/omni-skill/blob/master/examples/backend-api-master/datasets/db_best_practices.md

Illustrates common Alembic commands for managing database schema migrations, including generating new revisions, applying upgrades, and rolling back changes.

```bash
# Generate migration
alembic revision --autogenerate -m "Add user table"

# Apply migration
alembic upgrade head

# Rollback migration
alembic downgrade -1
```

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

### Database Connection Pooling (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/examples/backend-api-master/datasets/db_best_practices.md

Demonstrates how to use SQLAlchemy's QueuePool for efficient database connection management, improving performance by reusing connections. Configurable parameters include pool size, overflow, timeout, and recycle time.

```python
from sqlalchemy import create_engine
from sqlalchemy.pool import QueuePool

engine = create_engine(
    "postgresql://user:password@localhost/dbname",
    poolclass=QueuePool,
    pool_size=5,
    max_overflow=10,
    pool_timeout=30,
    pool_recycle=1800
)
```

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

### Assembler Protocol and OutputFormat (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/specs/2026-03-26-01-omniskill-framework/design.md

Defines the 'AssemblerProtocol' for assembling search results into formatted context, and the 'OutputFormat' enum (XML, Markdown). The 'assemble' method takes search results and a desired format, returning a formatted string.

```python
from enum import Enum

class OutputFormat(Enum):
    XML = "xml"
    MARKDOWN = "markdown"

@runtime_checkable
class AssemblerProtocol(Protocol):
    """Protocol for prompt assemblers."""

    def assemble(
        self,
        results: list[SearchResult],
        format: OutputFormat = OutputFormat.XML,
    ) -> str:
        """Assemble search results into formatted prompt context."""
        ...
```

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

### Async Database Operations (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/examples/backend-api-master/datasets/db_best_practices.md

Shows how to set up asynchronous database connections and sessions using SQLAlchemy's async capabilities. This is crucial for non-blocking I/O in modern Python applications.

```python
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

async_engine = create_async_engine(
    "postgresql+asyncpg://user:password@localhost/dbname",
    pool_size=5,
    max_overflow=10
)

async_session = sessionmaker(
    async_engine,
    class_=AsyncSession,
    expire_on_commit=False
)
```

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

### Execute Project Verification Commands

Source: https://github.com/longcipher/omni-skill/blob/master/specs/2026-03-26-01-omniskill-framework/design.md

Standard CLI commands used for verifying the project integrity, including BDD acceptance testing, type checking, and linting.

```bash
uv run behave features/
uv run ty check
uv run ruff check
```

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

### Execute Knowledge Base Search via CLI

Source: https://github.com/longcipher/omni-skill/blob/master/skills/backend-api-master/SKILL.md

This command triggers the search utility to query the curated knowledge base. It requires a query string as an argument and returns relevant context from CSV and Markdown datasets.

```bash
python backend_api_master/search.py "<your query>"
```

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

### Input Data Validation with Pydantic (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/examples/backend-api-master/datasets/db_best_practices.md

Demonstrates how to use Pydantic models for robust input data validation in Python. Includes custom validators for email format and password length.

```python
from pydantic import BaseModel, validator

class UserCreate(BaseModel):
    email: str
    password: str

    @validator('email')
    def validate_email(cls, v):
        if '@' not in v:
            raise ValueError('Invalid email format')
        return v

    @validator('password')
    def validate_password(cls, v):
        if len(v) < 8:
            raise ValueError('Password must be at least 8 characters')
        return v
```

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

### Define SKILL.md Template Constant

Source: https://github.com/longcipher/omni-skill/blob/master/specs/2026-03-26-01-omniskill-framework/tasks.md

Defines the Jinja2-style template structure for SKILL.md, including sections for Role, Knowledge Retrieval, and step-by-step Instructions. This constant serves as the blueprint for all generated skill documentation.

```python
SKILL_MD_TEMPLATE = """# Role
{{ skill_name }} is designed to assist with specific tasks.

# Knowledge Retrieval Action
Use the following command to retrieve context:
python -m omniskill search --query "<keywords>"

# Instructions
1. Extract keywords from the user request.
2. Execute the search command.
3. Read the context injection.
4. Generate the final output based on retrieved data.
"""
```

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

### Efficient Query Patterns (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/examples/backend-api-master/datasets/db_best_practices.md

Illustrates the difference between inefficient N+1 query problems and efficient data loading using SQLAlchemy's `joinedload` option to reduce database round trips.

```python
# Bad: N+1 query problem
users = session.query(User).all()
for user in users:
    orders = session.query(Order).filter_by(user_id=user.id).all()

# Good: Use joined loading
from sqlalchemy.orm import joinedload

users = session.query(User).options(joinedload(User.orders)).all()
```

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

### Index and Search with SearchEngine (Python API)

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Demonstrates using the `SearchEngine` from the OmniSkill Python API to index a directory of datasets and perform searches. It also shows how to use `PromptAssembler` to format the results.

```python
from omniskill.core.engine import SearchEngine
from omniskill.core.assembler import OutputFormat, PromptAssembler

engine = SearchEngine()
engine.index_directory("skills/my-skill/datasets")

results = engine.search("API design", limit=10)

assembler = PromptAssembler()
print(assembler.assemble(results, output_format=OutputFormat.XML))
```

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

### CLI Reference: create command

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Explains the `omniskill create` command used to generate an empty skill directory with template files. Includes the option to force overwrite.

```bash
omniskill create <skill-name> [--force]

Options:
  --force, -f — Overwrite existing skill directory
```

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

### Implement SKILL.md Generation Function

Source: https://github.com/longcipher/omni-skill/blob/master/specs/2026-03-26-01-omniskill-framework/tasks.md

A utility function that accepts a skill name and directory, renders the template with the provided values, and returns the formatted string. This function is intended to be integrated into the project's CLI creation command.

```python
def generate_skill_md(skill_name: str, skill_dir: str) -> str:
    """Renders the SKILL.md template with the provided skill name."""
    return SKILL_MD_TEMPLATE.replace("{{ skill_name }}", skill_name)
```

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

### CLI Reference: generate command

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Details the arguments and options for the `omniskill generate` command, including dataset directory, custom name, output directory, and verbose mode.

```bash
omniskill generate <dataset-dir> [options]

Arguments:
  dataset-dir — Path to a directory containing CSV and/or Markdown files

Options:
  --name, -n — Skill name (defaults to the dataset directory name)
  --output, -o — Output directory (defaults to `skills/<skill-name>/`)
  --verbose, -v — Show dataset analysis details
```

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

### CLI Reference: search command

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Outlines the parameters for the `omniskill search` command, including query, skill directory, output format, result limit, type filtering, tag filtering, metadata inclusion, and verbose mode.

```bash
omniskill search <query> --skill-dir <path> [options]

Options:
  --skill-dir, -d — Path to the skill directory (required)
  --format, -f — Output format: `xml`, `markdown` (default: `xml`)
  --limit, -l — Maximum number of results (default: `10`)
  --type, -t — Filter by document type: `csv`, `markdown`
  --tag — Filter by tag (AND logic, repeatable)
  --metadata — Include BM25 scores in output
  --verbose, -v — Enable verbose output
```

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

### Atomic Transaction Management (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/examples/backend-api-master/datasets/db_best_practices.md

Shows how to implement atomic database operations using SQLAlchemy sessions and transactions. Ensures that a series of database changes either all succeed or all fail, using `commit()` and `rollback()`.

```python
from sqlalchemy.orm import Session

def transfer_funds(session: Session, from_id: int, to_id: int, amount: float):
    """Transfer funds between accounts atomically."""
    try:
        from_account = session.query(Account).with_for_update().get(from_id)
        to_account = session.query(Account).with_for_update().get(to_id)

        if from_account.balance < amount:
            raise ValueError("Insufficient funds")

        from_account.balance -= amount
        to_account.balance += amount

        session.commit()
    except Exception:
        session.rollback()
        raise
```

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

### Indexer Protocol Definition (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/specs/2026-03-26-01-omniskill-framework/design.md

Defines the 'IndexerProtocol' using Python's typing.Protocol. It specifies methods for indexing single files, entire directories, and checking file support. This protocol enables interchangeable indexing implementations.

```python
from typing import Protocol, runtime_checkable
from pathlib import Path

@runtime_checkable
class IndexerProtocol(Protocol):
    """Protocol for document indexers."""

    def index_file(self, file_path: Path) -> list[Document]:
        """Index a single file and return documents."""
        ...

    def index_directory(self, dir_path: Path) -> list[Document]:
        """Index all supported files in a directory."""
        ...

    def supports_file(self, file_path: Path) -> bool:
        """Check if this indexer supports the given file."""
        ...
```

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

### Search using OmniSkill CLI

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Uses the OmniSkill CLI to search a generated skill's knowledge base. Requires specifying the skill directory.

```bash
omniskill search "API design best practices" --skill-dir skills/backend-api-master
```

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

### Searcher Protocol Definition (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/specs/2026-03-26-01-omniskill-framework/design.md

Defines the 'SearcherProtocol' for search engine implementations. It includes methods for performing searches with various filters (query, limit, document type, tags) and adding documents to the index. This protocol standardizes search functionality.

```python
@runtime_checkable
class SearcherProtocol(Protocol):
    """Protocol for search engines."""

    def search(
        self,
        query: str,
        limit: int = 10,
        doc_type: str | None = None,
        tags: list[str] | None = None,
    ) -> list[SearchResult]:
        """Search documents and return ranked results."""
        ...

    def add_documents(self, documents: list[Document]) -> None:
        """Add documents to the search index."""
        ...
```

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

### Generate a Skill from a Dataset Directory (CLI)

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Generates a complete Agentic-RAG skill from a directory containing CSV and/or Markdown files. The output includes a SKILL.md, search.py, and a datasets symlink.

```bash
omniskill generate examples/backend-api-master
```

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

### Generate Skill with Custom Name and Output Directory (CLI)

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Generates a skill with a custom name and specifies a different output directory. Useful for organizing multiple skills.

```bash
omniskill generate my-datasets/ --name my-skill --output out/my-skill/
```

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

### SQL Injection Prevention (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/examples/backend-api-master/datasets/db_best_practices.md

Contrasts a vulnerable string concatenation method for SQL queries with a secure parameterized query approach using SQLAlchemy to prevent SQL injection attacks.

```python
# Bad: String concatenation (vulnerable to SQL injection)
query = f"SELECT * FROM users WHERE email = '{email}'"

# Good: Parameterized query
query = "SELECT * FROM users WHERE email = :email"
result = session.execute(query, {"email": email})
```

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

### Define OmniSkill Configuration Model

Source: https://github.com/longcipher/omni-skill/blob/master/specs/2026-03-26-01-omniskill-framework/design.md

Defines the configuration schema for the OmniSkill framework using Python dataclasses. It manages settings for indexing, search parameters, assembly limits, and directory paths.

```python
from dataclasses import dataclass
from pathlib import Path

@dataclass(slots=True, frozen=True)
class OmniSkillConfig:
    """Configuration for OmniSkill framework."""

    # Indexing settings
    csv_extensions: tuple[str, ...] = (".csv",)
    markdown_extensions: tuple[str, ...] = (".md", ".markdown")
    max_file_size_mb: int = 10

    # Search settings
    default_search_limit: int = 10
    bm25_k1: float = 1.5
    bm25_b: float = 0.75

    # Assembly settings
    default_output_format: str = "xml"
    max_context_length: int = 4000

    # Paths
    skills_dir: Path = Path("skills")
    core_dir: Path = Path("core")
```

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

### Generate Skill with Verbose Mode (CLI)

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Generates a skill while enabling verbose mode, which displays detailed information about the dataset analysis process.

```bash
omniskill generate my-datasets/ --verbose
```

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

### Run Generated Skill Search Script

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Executes the standalone Python search script generated by OmniSkill to query the knowledge base. It takes a search query as input.

```bash
python skills/backend-api-master/search.py "API design best practices"
```

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

### Analyze Dataset Programmatically (Python API)

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Uses the `analyze_dataset` function from the OmniSkill Python API to analyze a dataset directory without generating skill files. It provides counts of CSV and Markdown files, and an estimate of total documents.

```python
from omniskill.core.generator import analyze_dataset

analysis = analyze_dataset("data/my-datasets")
print(f"CSV files: {len(analysis.csv_files)}")
print(f"Markdown files: {len(analysis.markdown_files)}")
print(f"Total documents: ~{analysis.total_documents}")
```

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

### Chunk Data Structure (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/specs/2026-03-26-01-omniskill-framework/design.md

Defines the 'Chunk' dataclass for representing segments of Markdown documents. It captures chunk ID, content, source file, header level and text, and associated metadata. This is used for more granular searching within Markdown files.

```python
from dataclasses import dataclass

@dataclass(slots=True, frozen=True)
class Chunk:
    """A chunk of a document (for Markdown)."""
    id: str
    content: str
    source: str
    header_level: int  # 2 for H2, 3 for H3
    header_text: str
    metadata: dict[str, Any]
```

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

### Document Data Structure (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/specs/2026-03-26-01-omniskill-framework/design.md

Defines the 'Document' dataclass for representing searchable documents. It includes fields for ID, content, source file path, document type (CSV or Markdown), metadata, and tags. This structure is fundamental for indexing and retrieval.

```python
from dataclasses import dataclass
from typing import Any

@dataclass(slots=True, frozen=True)
class Document:
    """A searchable document."""
    id: str
    content: str
    source: str  # File path
    doc_type: str  # "csv" | "markdown"
    metadata: dict[str, Any]
    tags: list[str]
```

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

### Define OmniSkill Exception Hierarchy

Source: https://github.com/longcipher/omni-skill/blob/master/specs/2026-03-26-01-omniskill-framework/design.md

Establishes a custom exception hierarchy for the framework, allowing for granular error handling across indexing, search, assembly, and configuration modules.

```python
class OmniSkillError(Exception):
    """Base exception for OmniSkill framework."""
    pass

class IndexingError(OmniSkillError):
    """Raised when document indexing fails."""
    pass

class SearchError(OmniSkillError):
    """Raised when search operation fails."""
    pass

class AssemblyError(OmniSkillError):
    """Raised when prompt assembly fails."""
    pass

class ConfigurationError(OmniSkillError):
    """Raised when configuration is invalid."""
    pass

class FileError(OmniSkillError):
    """Raised when file operation fails."""
    pass
```

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

### Generate Skill Programmatically (Python API)

Source: https://github.com/longcipher/omni-skill/blob/master/README.md

Uses the `generate_skill` function from the OmniSkill Python API to programmatically create a skill. It returns an analysis object with details about the generated skill.

```python
from omniskill.core.generator import generate_skill

analysis = generate_skill(
    dataset_dir="data/my-datasets",
    skill_name="my-skill",
    output_dir="skills/my-skill",
)

print(f"Generated {analysis.skill_name} with {analysis.total_documents} documents")
```

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

### SearchResult Data Structure (Python)

Source: https://github.com/longcipher/omni-skill/blob/master/specs/2026-03-26-01-omniskill-framework/design.md

Defines the 'SearchResult' dataclass for encapsulating the results of a search query. It includes the document or chunk found, its BM25 relevance score, and its rank in the search results. This structure facilitates presenting ranked and scored information.

```python
from dataclasses import dataclass

@dataclass(slots=True, frozen=True)
class SearchResult:
    """A search result with BM25 score."""
    document: Document | Chunk
    score: float
    rank: int
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.