# Scala CLI Adding Directives

> Add or change using directives in Scala CLI. Use when adding a new //> using directive, registering a directive handler, or editing directive preprocessing.

- Skill: `virtuslab/scala-cli-adding-directives` (Agent Skill)
- Install (CLI): `npx skillmds@latest add virtuslab/scala-cli-adding-directives`
- Raw SKILL.md: https://api.skillmd.com/api/skills/virtuslab/scala-cli-adding-directives/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: virtuslab (https://skillmd.com/u/virtuslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/virtuslab/scala-cli-adding-directives

---


# Adding a new directive (Scala CLI)

1. **Create a case class** in `modules/directives/src/main/scala/scala/build/preprocessing/directives/` extending one of:
   - `HasBuildOptions` — produces `BuildOptions` directly
   - `HasBuildOptionsWithRequirements` — produces `BuildOptions` with scoped requirements (e.g. `test.dep`)
   - `HasBuildRequirements` — produces `BuildRequirements` (for `//> require`)

2. **Annotate**: `@DirectiveLevel(SpecificationLevel.EXPERIMENTAL)`, `@DirectiveDescription("…")`, `@DirectiveUsage("…")`, `@DirectiveExamples("…")`, `@DirectiveName("key")` on fields.

3. **Companion**: `val handler: DirectiveHandler[YourDirective] = DirectiveHandler.derive`

4. **Register** in `modules/build/.../DirectivesPreprocessingUtils.scala` in the right list: `usingDirectiveHandlers`, `usingDirectiveWithReqsHandlers`, or `requireDirectiveHandlers`.

5. **Regenerate reference docs**: `./mill -i 'generate-reference-doc[]'.run`

CLI options always override directive values when both set the same thing.