sampler-module-authoring

name	sampler-module-authoring
description	Scaffold a PowerShell module project that follows the Sampler framework conventions (Gael Colas, github.com/gaelcolas/Sampler). Use this skill whenever the user asks for a "Sampler module", a "production module scaffold", or wants build/test/publish tasks driven by InvokeBuild.
domain	powershell-module-authoring
confidence	high
source	earned
tools	[]

Context

Sampler is an opinionated module scaffolding framework. It produces a predictable project layout, a reproducible build (InvokeBuild + the Sampler build tasks), and a publishing pipeline. Apply this skill when the user wants that exact shape — do NOT use it for ad-hoc one-off modules where a manifest and a .psm1 in a folder is enough.

Patterns

• Project root layout:
  • source/ — Public/, Private/, Classes/ (only if needed), en-US/, <ModuleName>.psd1 (source manifest)
  • tests/ — Pester 5 tests mirroring source/
  • output/ — generated; gitignored
  • build.ps1 — Sampler bootstrap (Resolve-Dependency.ps1 + Invoke-Build)
  • RequiredModules.psd1 — declarative dependency list (Pester, ModuleBuilder, PSScriptAnalyzer, ChangelogManagement, etc.)
  • GitVersion.yml — for SemVer
  • azure-pipelines.yml OR .github/workflows/ci.yml — CI matrix
• Manifest in source/, not the project root. Sampler builds the publishable manifest into output/ from the source manifest plus exported function discovery.
• Public function = one file under source/Public/<Verb-Noun>.ps1. Sampler discovers them at build time.
• build.ps1 is the entry point. It bootstraps dependencies via Resolve-Dependency.ps1, then runs Invoke-Build <Task>. Common tasks: build (default), test, pack, publish.
• RequiredModules.psd1 lists dev-time dependencies. Always include: Sampler, Pester, ModuleBuilder, PSScriptAnalyzer.
• Tests target output/, not source/. The built module is what ships, so the tests run against the built artifact.

Examples

Minimal RequiredModules.psd1:

@{
    Sampler                 = 'latest'
    ModuleBuilder           = 'latest'
    Pester                  = '5.7.1'
    PSScriptAnalyzer        = 'latest'
    ChangelogManagement     = 'latest'
}

Minimal build.ps1:

[CmdletBinding()]
param(
    [Parameter(Position = 0)]
    [string[]]$Tasks = 'build',
    [switch]$ResolveDependency
)

if ($ResolveDependency) {
    . $PSScriptRoot/Resolve-Dependency.ps1
}

Invoke-Build -Task $Tasks -File $PSScriptRoot/build.ps1

Anti-patterns

• Don't put the source manifest in the project root. Sampler builds the shipping manifest into output/.
• Don't write a custom *.psm1 that dot-sources Public/Private files at runtime. Sampler/ModuleBuilder concatenates them at build time into a single optimised file.
• Don't introduce PSDeploy or PoshBuildPipeline. Sampler uses InvokeBuild and its own tasks; mixing build systems makes the project inconsistent.
• Don't skip RequiredModules.psd1. The bootstrap won't have anything to install otherwise.