Skip to content
Skills Library
Programming · Building & coding

project-setup

/project-setup

Standards for OCaml project metadata files. Use when initializing a new OCaml library/module, preparing for opam release, setting up CI, discussing project structure, or ensuring proper .mli/.ocamlformat files exist.

Author
avsm ↗
Licence
ISC
Last repository change
02.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
11
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

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

Licence

ISC, otwarta.

What it does and when to use it

Standards for OCaml project metadata files. Use when initializing a new OCaml library/module, preparing for opam release, setting up CI, discussing project structure, or ensuring proper .mli/.ocamlformat files exist.

Original author description

Standards for OCaml project metadata files. Use when initializing a new OCaml library/module, preparing for opam release, setting up CI, discussing project structure, or ensuring proper .mli/.ocamlformat files exist.

How it works

  1. Required Files
  2. Interface Files (.mli)
  3. Standard Module Interface
  4. OCamlFormat Configuration
  5. Logging Setup
  6. User Configuration
  7. License Headers
  8. Project Structure
  9. dune-project
  10. Tangled CI Configuration
Original SKILL.md headings · 278 lines, 849 words
SKILL.md preview
---
name: project-setup
description: "Standards for OCaml project metadata files. Use when initializing a new OCaml library/module, preparing for opam release, setting up CI, discussing project structure, or ensuring proper .mli/.ocamlformat files exist."
---

# OCaml Project Setup

## Required Files

Every OCaml project needs:

| File | Purpose |
|------|---------|
| `dune-project` | Build configuration, opam generation |
| `dune` (root) | Top-level build rules |
| `.ocamlformat` | Code formatting (required) |
| `.gitignore` | VCS ignores |
| `LICENSE.md` | License file |
| `README.md` | Project documentation |
| CI config | GitHub Actions / GitLab CI / Tangled |

## Interface Files (.mli)

**Every library module must have an `.mli` file** for:
- Clear API boundaries
- Proper encapsulation
- Documentation surface

```ocaml
(* lib/user.mli *)

(** User accounts.

    A user is identified by an email address, which is unique within a
    workspace. *)

type t
(** The type for users. *)

val create : name:string -> email:string -> t
(** [create ~name ~email] is a new user called [name] with address [email]. *)

val name : t -> string
(** [name u] is the display name of [u]. *)

val pp : t Fmt.t
(** [pp ppf u] formats [u] on [ppf]. *)
```

**Documentation style**: written in the voice of a POSIX manual page. Load the
`doc-style` skill before writing any of it. In short, a function's doc opens
`[f x y] is ...`, every doc comment is full sentences ending in a full stop, no
colon or em dash joins clauses, and nothing describes the implementation.

## Standard Module Interface

For modules with a central type `t`:

```ocaml
type t
val v : ... -> t                           (* pure constructor *)
val create : ... -> (t, Error.t) result    (* constructor with I/O *)
val pp : t Fmt.t                           (* pretty-printer - required *)
val equal : t -> t -> bool                 (* equality *)
val compare : t -> t -> int                (* comparison *)
val of_json : Yojson.Safe.t -> (t, string) result
val to_json : t -> Yojson.Safe.t
```

## OCamlFormat Configuration

**Required**: `.ocamlformat` in project root.

```
version = 0.28.1
```

Run `dune fmt` before every commit.

## Logging Setup

Each module using logging should declare a source:

```ocaml
let log_src = Logs.Src.create "project.module"
module Log = (val Logs.src_log log_src : Logs.LOG)
```

Log levels:
- `Log.app` - Always shown (startup)
- `Log.err` - Critical errors
- `Log.warn` - Potential issues
- `Log.info` - Informational
- `Log.debug` - Verbose debugging

## User Configuration

Read from `~/.claude/ocaml-config.json`:

```json
{
  "author": { "name": "Name", "email": "email@example.com" },
  "license": "ISC",
  "ci_platform": "github",
  "git_hosting": { "type": "github", "org": "username" },
  "ocaml_version": "5.2.0"
}
```

## License Headers

Every source file starts with license header:

```ocaml
(*---------------------------------------------------------------------------
  Copyright (c) {{YEAR}} {{AUTHOR}}. All rights reserved.
  SPDX-License-Identifier: ISC
 ---------------------------------------------------------------------------*)
```

## Project Structure

```
project/
├── dune-project
├── dune
├── .ocamlformat
├── .gitignore
├── LICENSE.md
├── README.md
├── lib/
│   ├── dune
│   ├── foo.ml
│   └── foo.mli         # Required for every .ml
├── bin/
│   ├── dune
│   └── main.ml
├── test/
│   ├── dune
│   ├── test.ml
│   └── test_foo.ml
├── .github/workflows/  # GitHub Actions
├── .gitlab-ci.yml      # GitLab CI
└── .tangled/workflows/ # Tangled CI
```

## dune-project

```lisp
(lang dune 3.21)
(name project_name)
(source (tangled handle/project_name))   ; or (github user/repo)
(license ISC)
(authors "Name <email>")
(generate_opam_files true)

(license ISC)
(authors "Name <email@example.com>")
(maintainers "Name <email@example.com>")
(source (tangled user.domain/project_name))

(package
 (name project_name)
 (synopsis "Short description")
 (description "Longer description")
 (depends
  (ocaml (>= 5.2))
  (alcotest (and :with-test (>= 1.7.0)))))
```

**Source options**:
- `(source (tangled handle/repo))` - Tangled hosting (default for monopam)
- `(source (github user/repo))` - GitHub hosting
- `(source (gitlab user/repo))` - GitLab hosting

**Note**: Don't add `(version ...)` - added at release time.

### Tangled Source Syntax

For projects hosted on tangled.org, use the succinct source stanza:

```lisp
(source (tangled user.domain/project-name))
```

Examples:
- `(source (tangled anil.recoil.org/ocaml-brotli))`
- `(source (tangled user.example.org/my-library))`

## Tangled CI Configuration

For projects hosted on tangled.org, create `.tangled/workflows/build.yml`:

```yaml
when:
  - event: ["push", "pull_request"]
    branch: ["main"]

engine: nixery

dependencies:
  nixpkgs:
    - shell
    - stdenv
    - findutils
    - binutils
    - libunwind
    - ncurses
    - opam
    - git
    - gawk
    - gnupatch
    - gnum4
    - gnumake
    - gnutar
    - gnused
    - gnugrep
    - diffutils
    - gzip
    - bzip2
    - gcc
    - ocaml
    - pkg-config

steps:
  - name: opam
    command: |
      opam init --disable-sandboxing -a -y

  - name: repo
    command: |
      opam repo add aoah https://tangled.org/anil.recoil.org/aoah-opam-repo.git

  - name: deps
    command: |
      opam install . --confirm-level=unsafe-yes --deps-only

  - name: build
    command: |
      opam exec -- dune build

  - name: test
    command: |
      opam install . --confirm-level=unsafe-yes --deps-only --with-test
      opam exec -- dune runtest --verbose
```

### Tangled Workflow Syntax

| Field | Description |
|-------|-------------|
| `when` | Trigger conditions: `event` (push/pull_request) and `branch` |
| `engine` | Build engine, use `nixery` for Nix-based builds |
| `dependencies.nixpkgs` | List of Nix packages to include |
| `environment` | Global or per-step environment variables |
| `steps` | Build steps with `name` and `command` |

Per-step environment variables:

```yaml
steps:
  - name: test
    environment:
      MY_VAR: value
    command: |
      echo $MY_VAR
```

## Templates

See `templates/` directory for:
- `dune-project.template`
- `dune-root.template`
- `ci-github.yml`
- `ci-gitlab.yml`
- `ci-tangled.yml`
- `gitignore`
- `ocamlformat`
- `LICENSE-ISC.md`
- `LICENSE-MIT.md`
- `README.template.md`
Files in this package (11)
  • SKILL.md 6 KB
  • templates/LICENSE-ISC.md 1 KB
  • templates/LICENSE-MIT.md 1 KB
  • templates/README.template.md 1 KB
  • templates/ci-github.yml 1 KB
  • templates/ci-gitlab.yml 1 KB
  • templates/ci-tangled.yml 1 KB
  • templates/dune-project.template 1 KB
  • templates/dune-root.template 1 KB
  • templates/gitignore 1 KB
  • templates/ocamlformat 1 KB

Versions

RepositoryScoreLicence
This page · avsm/ocaml-claude-marketplace100ISC
vaayne/agent-kit100MIT
linxule/interpretive-orchestration100MIT
Pagepro/nexity100MIT
bringfire/rook100MIT
ahtserhsuddav/create-agent-ready-app100MIT
SckyzO/claude-project-setup100MIT
markshust/hcf100MIT
dwmkerr/claude-toolkit100MIT

Database snapshot: 13.11.2026 · package version af97369aed99 (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

  • 100review-ocaml
    Two-phase review of an OCaml project. Use when the user asks to review an OCaml codebase, audit its module interfaces, restructure or redocument .mli files, or hunt for redundancy, dead code and optimisation opportunities across implementations. Phase one reads only dune and…
  • 90yuka
    Write or change a web app built with Yuka, the OCaml web framework with server-rendered pages and islands. Use when a project depends on the `yuka` opam package, or the task names Yuka, `Routes.ml`, `let[@client]`, `Yuka.Client` or `Yuka.State`. Not for general OCaml, Melange or…
  • 100ocaml
    OCaml development guidance for building robust, type-safe applications. Use when Claude needs to: (1) Write OCaml code following modern best practices, (2) Design module interfaces (.mli files), (3) Handle errors with result types, (4) Work with dune build system, (5) Use common…
  • 87project-setup-info-local
    Comprehensive setup steps to help the user create complete project structures in a VS Code workspace; this tool is designed for full project initialization and scaffolding, not for creating individual files. When to use this tool: user wants to create a new complete project from…
  • 100ocaml
    Expert OCaml functional programming assistance covering algebraic data types, pattern matching, modules, and Dune. Use when developing static analysis tools, compilers, theorem provers, or high-assurance software.
  • 85{setup-skill-name}
    Sets up {module-name} module in a project. Use when the user requests to 'install {module-code} module', 'configure {module-name}', or 'setup {module-name}'.

Feedback and reports

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