diff --git a/AGENTS.md b/AGENTS.md index 49440543..18657dba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,9 @@ 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). +> **This file** covers building and contributing to Heylogs itself. To *use* Heylogs (run `check`, tune rules, configure `heylogs.properties`) on a changelog, see the [`changelog` skill](skills/usage/changelog/SKILL.md). +> +> **Contributing skills** (step-by-step guides for extending the codebase): [`create-rule`](skills/contributing/create-rule/SKILL.md) to add a validation rule, [`create-versioning`](skills/contributing/create-versioning/SKILL.md) to add a versioning scheme. ## Architecture diff --git a/README.md b/README.md index 7b658b04..c9d3e0cc 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ 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)). +> Using an AI coding assistant? The [`changelog` skill](skills/usage/changelog/SKILL.md) is an agent-generic guide to running `check`, tuning rules, and configuring `heylogs.properties`. Install it with `npx skills add nbbrd/heylogs` ([details](skills/usage/changelog/README.md)). ## Features diff --git a/.agents/skills/create-rule/SKILL.md b/skills/contributing/create-rule/SKILL.md similarity index 95% rename from .agents/skills/create-rule/SKILL.md rename to skills/contributing/create-rule/SKILL.md index 3b426411..bc504785 100644 --- a/.agents/skills/create-rule/SKILL.md +++ b/skills/contributing/create-rule/SKILL.md @@ -1,10 +1,13 @@ --- name: create-rule description: > - Use this skill when asked to add, create, or implement a new validation rule - in the Heylogs project. It covers picking the right enum, adding the constant, - the validate method, the test, the resource file (if needed), and the - documentation row. + Contributing to Heylogs — use this skill when asked to add, create, or + implement a new validation rule in the Heylogs project. It covers picking the + right enum, adding the constant, the validate method, the test, the resource + file (if needed), and the documentation row. +metadata: + source: https://github.com/nbbrd/heylogs + category: contributing --- Add a new validation rule to `heylogs-ext-rules` by following these steps in order. Execute all steps without asking for confirmation. diff --git a/.agents/skills/create-versioning/SKILL.md b/skills/contributing/create-versioning/SKILL.md similarity index 98% rename from .agents/skills/create-versioning/SKILL.md rename to skills/contributing/create-versioning/SKILL.md index 76b6de0b..fd66b0b7 100644 --- a/.agents/skills/create-versioning/SKILL.md +++ b/skills/contributing/create-versioning/SKILL.md @@ -1,10 +1,13 @@ --- name: create-versioning description: > - Use this skill when asked to add, create, or implement a new versioning scheme - in the Heylogs project. It covers creating the extension module, the public - SPI class, the internal parser/comparator, the tests, registering the module - in all POMs, and updating the documentation. + Contributing to Heylogs — use this skill when asked to add, create, or + implement a new versioning scheme in the Heylogs project. It covers creating + the extension module, the public SPI class, the internal parser/comparator, + the tests, registering the module in all POMs, and updating the documentation. +metadata: + source: https://github.com/nbbrd/heylogs + category: contributing --- Add a new versioning scheme to Heylogs by creating a `heylogs-ext-` module. Execute all steps without asking for confirmation. diff --git a/skills/heylogs/README.md b/skills/usage/changelog/README.md similarity index 81% rename from skills/heylogs/README.md rename to skills/usage/changelog/README.md index 584f2b4b..1180d1fc 100644 --- a/skills/heylogs/README.md +++ b/skills/usage/changelog/README.md @@ -1,6 +1,6 @@ -# Install the `heylogs` skill +# Install the `changelog` skill -The `heylogs` skill teaches an AI coding agent how to validate and maintain +The `changelog` 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 @@ -24,7 +24,7 @@ explains how to run it with no prerequisites via JBang (see ## Installation ```bash -npx skills add nbbrd/heylogs --skill heylogs +npx skills add nbbrd/heylogs ``` The installer fetches the skill from the repository, asks which agents to install @@ -36,23 +36,23 @@ 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 +npx skills add nbbrd/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 +[`skills/usage/changelog/`](.) and register it as a local skill folder per your agent's documentation (no Node.js required). ## Update ```bash -npx skills update heylogs +npx skills update changelog ``` ## Usage -Once installed, invoke `/heylogs` in the selected agent, or just ask it to check, +Once installed, invoke `/changelog` 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. diff --git a/skills/heylogs/SKILL.md b/skills/usage/changelog/SKILL.md similarity index 92% rename from skills/heylogs/SKILL.md rename to skills/usage/changelog/SKILL.md index 1501797a..a8faf85b 100644 --- a/skills/heylogs/SKILL.md +++ b/skills/usage/changelog/SKILL.md @@ -1,9 +1,9 @@ --- -name: heylogs +name: changelog 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. + Check, lint, fix, format, or release Keep a Changelog CHANGELOG.md files with + the Heylogs CLI. Use this skill whenever the user asks to validate or maintain + 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 @@ -13,6 +13,7 @@ description: > metadata: source: https://github.com/nbbrd/heylogs agent-generic: "true" + category: usage --- # Working with Heylogs changelogs @@ -21,8 +22,8 @@ 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/). +For project architecture and contribution conventions, see [`AGENTS.md`](../../../AGENTS.md). +Full feature docs live under [`docs/`](../../../docs/). ## What Heylogs does @@ -166,5 +167,5 @@ 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. +See [`docs/`](../../../docs/) for per-feature documentation and +[`docs/feature-matrix.md`](../../../docs/feature-matrix.md) for support by usage mode. diff --git a/skills/heylogs/references/commands.md b/skills/usage/changelog/references/commands.md similarity index 100% rename from skills/heylogs/references/commands.md rename to skills/usage/changelog/references/commands.md diff --git a/skills/heylogs/references/config-file.md b/skills/usage/changelog/references/config-file.md similarity index 100% rename from skills/heylogs/references/config-file.md rename to skills/usage/changelog/references/config-file.md diff --git a/skills/heylogs/references/rules.md b/skills/usage/changelog/references/rules.md similarity index 100% rename from skills/heylogs/references/rules.md rename to skills/usage/changelog/references/rules.md diff --git a/skills/heylogs/references/running-cli.md b/skills/usage/changelog/references/running-cli.md similarity index 100% rename from skills/heylogs/references/running-cli.md rename to skills/usage/changelog/references/running-cli.md