name: common-skills
description: Best practices for the Common utilities package in LlamaFarm. Covers HuggingFace Hub integration, GGUF model management, and shared utilities.
allowed-tools: Read, Grep, Glob
user-invocable: false

Common Skills for LlamaFarm

Best practices and code review checklists for the common/ package - shared Python utilities used across all LlamaFarm services.

Component Overview

Purpose

The common/ package provides shared functionality that needs to be consistent across multiple Python services:
- Model file utilities (GGUF selection, quantization parsing)
- HuggingFace Hub integration (listing, downloading)
- Process management (PID files)

Shared Python Skills

This skill inherits all patterns from the shared Python skills:

Framework-Specific Checklists

Module Structure

common/
├── pyproject.toml           # UV-managed dependencies
├── llamafarm_common/
│   ├── __init__.py          # Public API exports
│   ├── model_utils.py       # GGUF file utilities
│   └── pidfile.py           # PID file management
└── tests/
    └── test_model_utils.py  # Unit tests with mocking

Public API

Model Utilities

from llamafarm_common import (
    # Parse model:quantization syntax
    parse_model_with_quantization,
    # Extract quantization from filename
    parse_quantization_from_filename,
    # Select best GGUF file from list
    select_gguf_file,
    select_gguf_file_with_logging,
    # List GGUF files in HF repo
    list_gguf_files,
    # Download and get path to GGUF file
    get_gguf_file_path,
    # Default quantization preference order
    GGUF_QUANTIZATION_PREFERENCE_ORDER,
)

PID File Management

from llamafarm_common.pidfile import write_pid, get_pid_file

Review Checklist Summary

When reviewing code in common/:

1. HuggingFace Integration (High priority)
2. Proper error handling for network failures
3. Authentication token passed correctly

4. High-speed transfer enabled appropriately

5. Model Selection (Medium priority)

6. Quantization preference order maintained
7. Case-insensitive matching

8. Graceful fallback when preferred not available

9. Testing (High priority)

10. HuggingFace API calls mocked
11. Network isolation in tests

12. Edge cases covered (empty lists, missing files)

13. Security (Medium priority)

14. No token exposure in logs
15. Safe file path handling
16. Environment variable protection

See huggingface.md for detailed HuggingFace-specific checklists.