docs: add agent-generic SKILLS.md

AGENTS.md

@@ -4,6 +4,8 @@
 
 Heylogs is a Java 8+ multi-module Maven project for validating and releasing changelogs in [Keep a Changelog](https://keepachangelog.com) format. It parses Markdown into an AST (via [flexmark-java](https://github.com/vsch/flexmark-java)) and operates on the tree.
 
+> **This file** covers building and contributing to Heylogs itself. To *use* Heylogs (run `check`, tune rules, configure `heylogs.properties`) on a changelog, see the [`heylogs` skill](skills/heylogs/SKILL.md).
+
 ## Architecture
 
 **Core module** (`heylogs-api`): Contains the facade class (`Heylogs`), domain model, and SPI interfaces in the `spi` subpackage. Internal implementation lives under `internal.*` packages — never reference these types from public API.

README.md

@@ -33,6 +33,8 @@ Heylogs is available in multiple formats to fit your workflow:
 - **[Maven Enforcer rules](docs/usage-enforcer-rules.md)** - Enforce changelog quality in builds
 - **[CI/CD pipelines](docs/usage-pipelines.md)** - Integrate into CI/CD environments
 
+> Using an AI coding assistant? The [`heylogs` skill](skills/heylogs/SKILL.md) is an agent-generic guide to running `check`, tuning rules, and configuring `heylogs.properties`. Install it with `npx skills add nbbrd/heylogs --skill heylogs` ([details](skills/heylogs/README.md)).
+
 ## Features
 
 Heylogs provides several **commands** to interact with changelog files:

skills/heylogs/README.md

@@ -0,0 +1,58 @@
+# Install the `heylogs` skill
+
+The `heylogs` skill teaches an AI coding agent how to validate and maintain
+[Keep a Changelog](https://keepachangelog.com)–formatted `CHANGELOG.md` files
+with the **[Heylogs](https://github.com/nbbrd/heylogs)** CLI — running `check`,
+tuning rules, and configuring `heylogs.properties`. The skill definition is in
+[`SKILL.md`](SKILL.md), with details under [`references/`](references/).
+
+Skills can be installed in many ways — refer to your agent's documentation for
+the available options. Below we use [skills](https://github.com/vercel-labs/skills)
+(`npx skills`, see [skills.sh](https://skills.sh)), which installs a skill in a
+single step across multiple agents (Claude Code, OpenCode, GitHub Copilot,
+Codex, and more) in a unified way.
+
+## Prerequisites
+
+Node.js (v18+) is required only for the `npx skills` method. Install it via your
+system's package manager or from [nodejs.org](https://nodejs.org).
+
+The skill drives the Heylogs CLI; if it isn't on your `PATH`, the skill itself
+explains how to run it with no prerequisites via JBang (see
+[`references/running-cli.md`](references/running-cli.md)).
+
+## Installation
+
+```bash
+npx skills add nbbrd/heylogs --skill heylogs
+```
+
+The installer fetches the skill from the repository, asks which agents to install
+it for (several universal agents incl. Claude Code are enabled by default), then
+the scope (project vs **Global** — recommended so it's available in every
+project) and method (**Symlink** recommended — updates reflect immediately).
+Confirm to finish.
+
+Non-interactive (CI-friendly) install for Claude Code, global:
+
+```bash
+npx skills add nbbrd/heylogs --skill heylogs -g -a claude-code -y
+```
+
+## Alternative: manual installation
+
+If you prefer not to use `npx skills`, download the skill folder
+[`skills/heylogs/`](.) and register it as a local skill folder per your agent's
+documentation (no Node.js required).
+
+## Update
+
+```bash
+npx skills update heylogs
+```
+
+## Usage
+
+Once installed, invoke `/heylogs` in the selected agent, or just ask it to check,
+fix, or release a changelog — the skill's `description` triggers it automatically.
+See the [skill definition](SKILL.md) for full capabilities.

skills/heylogs/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: heylogs
+description: >
+  Validate and maintain Keep a Changelog–formatted CHANGELOG.md files with the
+  Heylogs CLI. Use this skill whenever the user asks to check, lint, validate,
+  fix, format, or release a changelog, sees Heylogs rule violations (e.g.
+  no-empty-group, latest-version-first, forge-ref), wants to get a repo to
+  "0 problems" via heylogs.properties without editing the changelog, or needs to
+  add/extract/export changelog entries. Covers the `check` command and rule
+  configuration (primary task), persistent `heylogs.properties` config, every
+  built-in rule, the authoring/releasing/inspecting commands, and how to run the
+  CLI with no prerequisites via JBang.
+metadata:
+  source: https://github.com/nbbrd/heylogs
+  agent-generic: "true"
+---
+
+# Working with Heylogs changelogs
+
+Agent-generic guide (works with any coding assistant) for using the
+[Heylogs](https://github.com/nbbrd/heylogs) CLI to validate and maintain
+[Keep a Changelog](https://keepachangelog.com)–formatted `CHANGELOG.md` files.
+
+For project architecture and contribution conventions, see [`AGENTS.md`](../../AGENTS.md).
+Full feature docs live under [`docs/`](../../docs/).
+
+## What Heylogs does
+
+Heylogs parses a Markdown changelog into an AST and validates/transforms it.
+It is available as a CLI, a Maven plugin, Maven Enforcer rules, and a Java
+library. This skill focuses on the **CLI**.
+
+```bash
+heylogs <command> [<args>]
+```
+
+Examples below write `heylogs …` for brevity. If you don't have a native binary
+on `PATH`, run the same command through JBang (no prerequisites) — see
+[`references/running-cli.md`](references/running-cli.md). Quickest one-liner:
+
+```bash
+export JBANG_USE_NATIVE=true
+curl -Ls https://sh.jbang.dev | bash -s - com.github.nbbrd.heylogs:heylogs-cli:0.19.1:bin check CHANGELOG.md
+```
+
+Most commands default to `CHANGELOG.md` and accept a positional file argument
+(use `-` for stdin). File-modifying commands print a one-line status to
+**stderr** (`+` modified, `!` needs attention, `~` dry-run, `=` no-op) and most
+support `--dry-run`. Global options (`--debug`, `--batch`, `-D<prop>=<val>`) are
+documented in [`references/running-cli.md`](references/running-cli.md).
+
+## Primary task: `check`
+
+Validate a changelog against the rule set:
+
+```bash
+heylogs check                      # checks CHANGELOG.md
+heylogs check path/to/CHANGELOG.md
+heylogs check --recursive          # find changelogs recursively
+heylogs check --format json --output result.json
+```
+
+Output formats: `stylish` (default), `json`, `github-actions`, … (run
+`heylogs list` to see what's installed).
+
+### Adjusting which rules run and their severity
+
+Each rule has a severity: `ERROR`, `WARN`, `INFO`, or `OFF` (disabled). Override
+per invocation with repeated `--rule <id>:<severity>` options:
+
+```bash
+# Enable dot-space-link-style (off by default) as a warning, and disable no-empty-group
+heylogs check --rule dot-space-link-style:WARN --rule no-empty-group:OFF
+```
+
+This is the canonical way to tune rules ad hoc. For persistent configuration,
+use `heylogs.properties` (below). Other `check` options — `--versioning`,
+`--tagging`, `--forge`, `--domain`, `--no-config` — are listed in
+[`references/commands.md`](references/commands.md#check-options).
+
+## Configuration via `heylogs.properties`
+
+Settings can be made persistent (and shared across CLI, Maven plugin, and
+Enforcer) in a `heylogs.properties` file. Files are discovered by walking **up**
+the directory tree from the changelog's directory; parent files load first and
+**child values override parents**. A template ships at the root of the Heylogs
+repository. Full discovery/override/`stopBubbling` semantics and the property
+table are in [`references/config-file.md`](references/config-file.md).
+
+```properties
+# heylogs.properties — project root
+versioning=semver
+tagging=prefix:v
+forge=github
+rules=dot-space-link-style:WARN,no-empty-group:OFF
+```
+
+### Pattern: get a repo (or several) to "0 problems" without editing the changelog
+
+Because the file is **auto-discovered** and `rules=name:SEVERITY` accepts `OFF`,
+rule-tuning can live entirely in configuration — no `CHANGELOG.md` edits needed.
+This keeps a changelog a verbatim port of its upstream source while still passing
+`heylogs check`.
+
+1. Run `heylogs check` and note every rule id that fires.
+2. Put one `heylogs.properties` at the root, listing those rules at the severity
+   you want (`OFF` to silence, `WARN` to downgrade from `ERROR`):
+
+   ```properties
+   # Uniform config: silence/downgrade the rules that fire, edit no changelogs
+   versioning=semver
+   forge=github
+   rules=dot-space-link-style:OFF,no-empty-group:OFF,release-date:WARN
+   ```
+
+3. Re-run `heylogs check` until it reports 0.
+
+For several repositories, drop the **same** `heylogs.properties` in each (or place
+one in a shared parent directory and let hierarchical discovery apply it to all,
+unless `config.stopBubbling=true` blocks it).
+
+## Available rules
+
+Rules fall into three kinds: **format** (structure/formatting), **content**
+(required sections, links, uniqueness), and **versioning** (version numbers and
+tag refs). The full table of every built-in rule with its default severity is in
+[`references/rules.md`](references/rules.md). Discover the rules installed in
+your environment (including extensions) with:
+
+```bash
+heylogs list                 # human-readable; also lists formats, forges, schemes
+heylogs list --format json
+```
+
+## Other commands
+
+All commands default to `CHANGELOG.md`, accept a positional file (or `-` for
+stdin), and most support `--dry-run`:
+
+- **Authoring/editing:** `init`, `push`, `fetch`, `note`, `format`
+- **Releasing:** `release`, `yank`
+- **Inspecting/converting:** `scan`, `extract`, `export`, `import`, `list`
+
+Full purpose + examples for each, plus composability notes, are in
+[`references/commands.md`](references/commands.md).
+
+## Typical agent workflow
+
+```bash
+# 1. Validate; tune rules for this project
+heylogs check --rule dot-space-link-style:WARN --rule no-empty-group:OFF
+
+# 2. Normalize structure before committing
+heylogs format
+
+# 3. Add changes as you work
+heylogs push -y fixed -m "Fix parser memory leak"
+
+# 4. Gate in CI (no colors/feedback, fail on formatting drift)
+heylogs --batch format --check
+heylogs --batch check
+```
+
+In CI, prefer `--batch` (clean output, no ANSI) and consider `--no-config` for
+fully explicit, reproducible configuration.
+
+---
+
+See [`docs/`](../../docs/) for per-feature documentation and
+[`docs/feature-matrix.md`](../../docs/feature-matrix.md) for support by usage mode.

skills/heylogs/references/commands.md

@@ -0,0 +1,54 @@
+# Heylogs commands reference
+
+All commands default to `CHANGELOG.md`, accept a positional file (or `-` for
+stdin), and most support `--dry-run`.
+
+## `check` options
+
+`check` is the primary task (see [`../SKILL.md`](../SKILL.md)). Beyond
+`--rule <id>:<severity>`:
+
+| Option                    | Purpose                                                |
+|---------------------------|--------------------------------------------------------|
+| `--rule <id:severity>`    | Override a rule's severity (repeatable).               |
+| `--versioning <scheme>`   | Versioning scheme: `semver`, `calver:YYYY.MM.DD`, `regex:…`. |
+| `--tagging <strategy>`    | Tag naming, e.g. `prefix:v` (for `v1.0.0`).            |
+| `--forge <platform>`      | `github`, `gitlab`, or `forgejo` (link validation).    |
+| `--domain <domain:forge>` | Map a custom domain to a forge (repeatable), e.g. `git.corp.com:gitlab`. |
+| `--no-config`             | Ignore all `heylogs.properties` files.                 |
+
+## Authoring / editing
+
+| Command   | Purpose                                                              | Example                                                        |
+|-----------|---------------------------------------------------------------------|---------------------------------------------------------------|
+| `init`    | Create a new changelog from a template (fails if it exists).        | `heylogs init --project-url https://github.com/nbbrd/heylogs` |
+| `push`    | Add an entry to the Unreleased section (creates the group as needed).| `heylogs push -y added -m "Add custom themes"`                |
+| `fetch`   | Add an entry from a forge issue/PR (full URL or short `#ref`).      | `heylogs fetch -y fixed -i "#42"`                             |
+| `note`    | Set/replace the summary text after the Unreleased header.          | `heylogs note -m "Performance improvements."`                 |
+| `format`  | Normalize ordering & markers (idempotent). `--check` for CI gate.   | `heylogs format` · `heylogs format --check`                  |
+
+`push`/`fetch` change types (`-y`): `added`, `changed`, `deprecated`,
+`removed`, `fixed`, `security`.
+
+## Releasing
+
+| Command   | Purpose                                              | Example                          |
+|-----------|------------------------------------------------------|----------------------------------|
+| `release` | Convert Unreleased changes into a new version entry. | `heylogs release --ref 1.0.0`    |
+| `yank`    | Append `[YANKED]` to a release heading.              | `heylogs yank -r 1.0.0`          |
+
+## Inspecting / converting
+
+| Command   | Purpose                                                          | Example                                          |
+|-----------|------------------------------------------------------------------|--------------------------------------------------|
+| `scan`    | Summarize content (release count, date range, forge, …).        | `heylogs scan --format json`                     |
+| `extract` | Filter/extract specific versions (e.g. latest only).            | `heylogs extract --limit 1 --output latest.md`   |
+| `export`  | Serialize the changelog to structured data (e.g. JSON).         | `heylogs export --format json`                   |
+| `import`  | Rebuild a Markdown changelog from structured data (export's inverse). | `heylogs import changelog.json`            |
+| `list`    | List installed resources: rules, formats, forges, schemes.      | `heylogs list --format json`                     |
+
+Commands are composable (Unix-style) — `extract` and `export` read from stdin:
+
+```bash
+heylogs extract --limit 1 | heylogs export - --format json
+```

skills/heylogs/references/config-file.md

@@ -0,0 +1,63 @@
+# Configuration via `heylogs.properties`
+
+Settings can be made persistent (and shared across CLI, Maven plugin, and
+Enforcer) in a `heylogs.properties` file. Files are discovered by walking **up**
+the directory tree from the changelog's directory; parent files load first and
+**child values override parents** (Lombok-style). For list properties (`rules`,
+`domains`) the child list **replaces** the parent list entirely.
+
+```properties
+# heylogs.properties — project root
+versioning=semver
+tagging=prefix:v
+forge=github
+
+# Rule severity overrides (comma-separated). Same id:severity grammar as --rule.
+rules=dot-space-link-style:WARN,no-empty-group:OFF
+
+# Map custom domains to forges (comma-separated)
+domains=git.company.com:gitlab,code.internal.org:github
+
+# Stop walking up to parent directories (e.g. monorepo module boundary)
+config.stopBubbling=true
+```
+
+| Property     | Description                  | Example                                      |
+|--------------|------------------------------|----------------------------------------------|
+| `versioning` | Version validation scheme    | `semver`, `calver:YYYY.MM.DD`, `regex:^\d+$` |
+| `tagging`    | Tag naming strategy          | `prefix:v`                                   |
+| `forge`      | Hosting platform             | `github`, `gitlab`, `forgejo`                |
+| `rules`      | Rule severity overrides      | `no-empty-group:WARN,https:OFF`              |
+| `domains`    | Custom forge domains         | `git.company.com:gitlab`                     |
+
+Precedence note: `--rule` on the command line and the `rules` list in
+`heylogs.properties` both express the same `id:severity` overrides. Use
+`--no-config` to bypass the file hierarchy entirely and rely only on CLI flags
+(useful in CI for explicit, reproducible config).
+
+A template `heylogs.properties` ships at the root of the Heylogs repository.
+
+## Pattern: get a repo (or several) to "0 problems" without editing the changelog
+
+Because the file is **auto-discovered** and `rules=name:SEVERITY` accepts `OFF`,
+rule-tuning can live entirely in configuration — no `CHANGELOG.md` edits needed.
+This keeps a changelog a verbatim port of its upstream source while still passing
+`heylogs check`.
+
+1. Run `heylogs check` and note every rule id that fires.
+2. Put one `heylogs.properties` at the root, listing those rules at the severity
+   you want (`OFF` to silence, `WARN` to downgrade from `ERROR`):
+
+   ```properties
+   # Uniform config: silence/downgrade the rules that fire, edit no changelogs
+   versioning=semver
+   forge=github
+   rules=dot-space-link-style:OFF,no-empty-group:OFF,release-date:WARN
+   ```
+
+3. Re-run `heylogs check` until it reports 0.
+
+For several repositories, drop the **same** `heylogs.properties` in each (or place
+one in a shared parent directory and let hierarchical discovery apply it to all,
+unless `config.stopBubbling=true` blocks it). One uniform config can bring every
+repo to 0 while the workflow and changelog contents stay identical to upstream.