Skip to content
Skills Library
Programming · Building & coding

developing-julia-package

/developing-julia-package

Use when you implement or edit code inside an existing Julia package: module/`include` layout, multiple dispatch, type annotations and stability, formatting, and docstrings

Licence
MIT
Last repository change
26.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 26.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when you implement or edit code inside an existing Julia package: module/`include` layout, multiple dispatch, type annotations and stability, formatting, and docstrings

Original author description

Use when you implement or edit code inside an existing Julia package: module/`include` layout, multiple dispatch, type annotations and stability, formatting, and docstrings

How it works

  1. Avoid excessive exports
  2. Julia-idiomatic style
  3. Code formatting (JuliaFormatter)
  4. Performance and allocations
  5. Errors and documentation
Original SKILL.md headings · 147 lines, 651 words
SKILL.md preview
---
name: developing-julia-package
description: Use when you implement or edit code inside an existing Julia package: module/`include` layout, multiple dispatch, type annotations and stability, formatting, and docstrings
---

# Developing a Julia package

Notes on developing Julia packages.

Assume the package is named `MyPkg`. Substitute your actual package name wherever `MyPkg` appears.

Use `src/MyPkg.jl` as the package entry point. Keep the module declaration, exports, and `include` list there; put substantial implementation in focused files under `src/`.

```julia
module MyPkg

export fit_model, FitResult, GaussianModel

include("models.jl")
include("fit.jl")
include("preprocess.jl")

end
```

Split files to improve readability, not to recreate Python-style class or submodule hierarchies. Prefer one public module unless there is a real user-facing namespace boundary.

Guidelines below.

## Avoid excessive `export`s

To audit and clean up an existing package's exports (for example, helpers
exported only so `Pkg.test` can reach them), see [[fixing-julia-exports]].

- Do not `export` helpers that are only used internally just so tests can reach them. Prefer importing explicitly in tests:

```julia
# test/runtests.jl

using Test
using MyPkg: <internal-only helper>
```

Test public behavior through the public API first. Import internals only when the helper has meaningful behavior that is hard to exercise through the public path:

```julia
using Test
using MyPkg
using MyPkg: initial_guess

@testset "fit_model" begin
    result = fit_model(x, y; model = GaussianModel())
    @test result isa FitResult
end

@testset "initial_guess" begin
    @test initial_guess(x, y, GaussianModel()) isa NamedTuple
end
```

## Julia-idiomatic style

### Multiple dispatch

Prefer splitting behavior across methods instead of a large `if`/`elseif` chain on `isa`, unlike typical Python style.

```julia
# Do not write if else end
function f(x)
    if x isa Integer
        return 2x
    else
        return x
    end
end
```

Instead, use multiple dispatch:

```julia
f(x) = x # generic implementation
f(x::Integer) = 2x # specialized implementation for x::Integer
```

For package APIs, make the dispatch object explicit and keep symbol options as a thin compatibility layer if needed:

```julia
abstract type AbstractModel end

struct GaussianModel <: AbstractModel
    baseline::Bool
end

GaussianModel(; baseline = true) = GaussianModel(baseline)

fit_model(x, y; model::AbstractModel = GaussianModel()) =
    fit_model(model, x, y)

function fit_model(model::GaussianModel, x, y)
    guess = initial_guess(x, y, model)
    # gaussian-specific implementation
end
```

Use a marker or configuration struct for the model choice, and use a separate result struct for fitted values. Do not mutate a model type into a mixed "algorithm plus fitted state" object unless that is clearly the public contract.

```julia
struct FitResult{P,T}
    params::P
    residuals::Vector{T}
    converged::Bool
end
```

This keeps `GaussianModel()` as the method-selection/configuration value and `FitResult` as the returned fitted state.

### Type annotations

- On **public** APIs, narrow signatures when it prevents misuse or clarifies the contract.
- Inside the package, avoid over-constraining types everywhere; leave room for the compiler and for generic code.

### Type stability

- On hot paths, avoid return types that vary unpredictably across inputs; type instability prevents specialization and shows up as dynamic dispatch.
- Diagnose and fix it with the tools in [[profiling-julia-performance]] (Profile, JET.jl, AllocCheck.jl) instead of guessing.

## Code formatting (JuliaFormatter)

- Format package sources with **[JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl)** so layout and whitespace stay consistent across contributors and CI.
- Optionally commit a **`.JuliaFormatter.toml`** at the repository root (or rely on defaults) so everyone applies the same rules.

From the package root:

```julia
using JuliaFormatter
format(".")  # formats src/, test/, etc. under the current directory
```

Run formatting before merging substantive edits; wire the same command into CI or pre-commit hooks if the team wants enforcement.

## Performance and allocations

- Confirm bottlenecks by profiling before optimizing; see [[profiling-julia-performance]] for the full workflow (Profile, JET.jl, AllocCheck.jl).
- For micro-benchmarks, use **`@benchmark` / `@btime`** from BenchmarkTools.jl rather than a single `@time`, which is dominated by variance and one-time effects.
- Watch unnecessary array copies from slicing and broadcasting; when an in-place API is needed, expose it explicitly (separate function name or keyword argument) so callers opt in.

## Errors and documentation

- Raise **`ArgumentError`**, **`DomainError`**, or other appropriate exceptions; messages should tell the caller what to fix.
- Give **docstrings** to exported/public functions—ordinary docstrings above definitions integrate cleanly with Documenter.jl; use `@doc` when you attach documentation programmatically.

Versions

The database has no other skills named developing-julia-package.

Database snapshot: 13.11.2026 · package version 2e2f365e5531 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100julia-pro
    Master Julia 1.10+ with modern features, performance optimization, multiple dispatch, and production-ready practices. Expert in the Julia ecosystem including package management, scientific computing, and high-performance numerical code. Use for Julia development, optimization,…
  • 100julia-expert
    Expert knowledge in Julia scientific computing, multiple dispatch, performance optimization, and numerical analysis. Use when the user mentions scientific computing, multiple dispatch, performance, numerical analysis, data science, or HPC, or when the task involves Type System,…
  • 100generating-julia-package
    Use when you create a new Julia package or project environment — choosing the layout, writing `Project.toml`/`src`, generating a UUID, adding dependencies — or prepare a package for registration
  • 95testing-julia-package
    Use when you set up or run tests for a Julia package, including workspace-based test dependencies, Pkg.test(), focused local runs, and optional parallel test files
  • 100julia
    Expert Julia assistance covering numerical computing, multiple dispatch, broadcasting, and parallel computing. Use when developing scientific models, machine learning, physics simulations, or differential equations.
  • 85julia-evaluation
    Activates when user asks to run, evaluate, or test Julia code in a persistent REPL session, or mentions Julia REPL, Julia session, or hot-reloading Julia changes.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.