home / skills / lookatitude / beluga-ai / create_package

create_package skill

safe

/.agent/skills/create_package

This skill guides you to create a standardized Go package in Beluga AI, including structure, interfaces, metrics, and validation.

npx playbooks add skill lookatitude/beluga-ai --skill create_package

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.1 KB

---
name: Create New Package
description: Guide to creating a new standardized package in Beluga AI.
---

# Create New Package

This skill ensures your new package follows the strict Beluga AI architecture.

## Steps

1.  **Create Directory Structure**
    ```bash
    mkdir -p pkg/<package_name>/{iface,internal,providers}
    ```

2.  **Create Required Files**
    -   `pkg/<package_name>/<package_name>.go`: Main entry point / interfaces.
    -   `pkg/<package_name>/config.go`: Configuration structs and validation.
    -   `pkg/<package_name>/metrics.go`: OTEL metrics setup.
    -   `pkg/<package_name>/errors.go`: Custom error definitions.
    -   `pkg/<package_name>/test_utils.go`: Test helpers and mocks.

3.  **Define Interfaces**
    -   Place primary interfaces in `iface/` or the root package file.

4.  **Implement OTEL Metrics**
    -   In `metrics.go`, define `NewMetrics(meter)`.
    -   Create counters/histograms for operations.

5.  **Add Documentation**
    -   Create `pkg/<package_name>/README.md`.

## Validation
-   Run `make lint` to ensure no linting errors.
-   Run `go test ./pkg/<package_name>/...` to verify tests.

Overview

This skill guides you through creating a new standardized Go package that conforms to Beluga AI architecture. It explains the required directory layout, mandatory files, and validation steps so new packages are consistent, testable, and observable. Follow the checklist to reduce integration friction and maintain code quality.

How this skill works

The guide prescribes a directory layout under pkg/<package_name> with iface, internal, and providers subpackages and a set of required files (entry point, config, metrics, errors, test helpers). It also details implementing OTEL metrics, defining interfaces, adding documentation, and running linting and tests to validate the new package. The result is a package ready for integration with the rest of the system.

When to use it

When adding a new domain component or service module to the codebase.
When extracting functionality from an existing package to improve separation of concerns.
When onboarding a new contributor who needs a template for compliant packages.
When preparing code for production with observability and error handling requirements.

Best practices

Always create the full directory structure: pkg/<name>/{iface,internal,providers} to enforce boundaries.
Keep interfaces in iface/ or the root package file to make implementations swappable and testable.
Implement NewMetrics(meter) in metrics.go and register counters/histograms for key operations.
Put configuration structs and validation logic in config.go to centralize runtime checks.
Add focused tests and test utilities in test_utils.go and run go test ./pkg/<name>/... frequently.
Run make lint before opening PRs to catch style and static analysis issues early.

Example use cases

Create a new storage adapter package with iface for repository interfaces and providers for concrete DB drivers.
Introduce a new feature module that needs its own metrics and error types for observability.
Split a monolithic package into a cleaner bounded context using internal for implementation details.
Provide a mockable service package for integration tests by placing interfaces in iface and mocks in test_utils.go.

FAQ

Where should I place package-level interfaces?

Put primary interfaces in the iface/ subpackage or the package root file so consumers depend on abstractions, not implementations.

What metrics should I create in metrics.go?

Create counters for operation counts and histograms for latencies. Expose NewMetrics(meter) to wire them into the global OTEL meter.