git:20261027.1c10770 to git:20261027.5f4f523

# Natuleadan Skills: Agent Guide

Technical guide for working in this repository. The README is the product

overview.

## Requirements

- Node.js 24 or newer, which runs TypeScript entry points directly.

- pnpm 12.

- No Python: validation, hooks and CI run on Node.

## Commands

| Command | What it does |

|---|---|

| `pnpm validate` | full validation: skills, audit, notices and scripts |

| `pnpm validate:skills` | skills, audit and script freshness |

| `pnpm industry` | audit the sixteen industry skills |

| `pnpm notices` | regenerate `ThirdPartyNotices.txt` |

| `pnpm scripts:generate` | regenerate every skill script stub |

| `pnpm scripts:check` | verify stubs and run their smoke tests |

| `pnpm md:check` | reject spaced hyphens in Markdown prose |

| `pnpm skill <name>` | run `skills/<name>/scripts/main.ts` |

| `pnpm changeset` | record a change for the next release |

| `pnpm run version` | apply changesets locally; CI does this in the release PR |

| `pnpm check-plugin-version` | verify plugin manifests match `package.json` |

## Project structure

| Path | Purpose |

|---|---|

| `skills/<name>/SKILL.md` | frontmatter and instructions |

| `skills/<name>/metadata.json` | version, abstract, references |

| `skills/<name>/references/` | prose notes with mermaid diagrams |

| `skills/<name>/scripts/main.ts` | generated entry point, required |

| `tools/` | validator, industry audit, notices and skill runner |

| `.claude-plugin/` | marketplace and plugin manifests |

| `.changeset/` | changeset configuration |

## Development

Clone the repository and run `pnpm install`; the `prepare` script installs the

Husky hooks. Use `pnpm validate` as the single gate before pushing.

## Validation

`pnpm validate` enforces:

- Frontmatter and directory names match.

- Every declared reference exists and has a mermaid sequence diagram.

- No fenced code blocks in markdown except mermaid.

- No spaced hyphen ` - ` in Markdown prose; the only exception is the

copyright line `2023 - Present.`.

- No `code/`, no executables and no Python.

- `scripts/` starts at `main.ts` and holds only TypeScript or ESM.

- Every skill is registered in both plugin manifests.

- License and version match across manifests.

- `ThirdPartyNotices.txt` matches the installed dependencies.

- Every skill has a generated `scripts/main.ts` and passes the smoke test.

- Industry skills stay neutral: no platform concepts, vendor names or pricing.

The `pre-commit` hook runs `pnpm validate:skills`; the `pre-push` hook and CI run

`pnpm validate`.

## Branches

`main` is the only permanent branch. Every work item goes on a short-lived

branch (`feat/...`, `fix/...`, `docs/...`) and reaches `main` through a pull

request. The branch is deleted after merge. A branch can hold one or many

commits; there is no branch per commit.

## Commits

Format: `type(scope): description`, scope in English and lower case.

- Title has 3 to 7 words, counting `type(scope):`.

- Maximum 100 characters, no trailing period.

- Blank line after the title.

- At least 3 bullets shaped `- **Label**: body`, each body with 3 to 7 words.

- Types: feat, fix, upgrade, docs, style, refactor, perf, test, chore, ci,

revert.

- Scopes: `skills`, `tools`, `docs`, `ci`, `workflow`, `hooks`, `release`,

`license`, `deps`. CI rejects any other scope.

Release commits (`chore(release): ...`) are exempt because the release pipeline

creates them.

## Releases

Changesets drive versions. A feature pull request includes a changeset; on push

to `main`, the Version Packages workflow opens or updates a release pull request.

That release PR runs `pnpm run version`, which executes `changeset version` and

`sync-plugin-version`, so `package.json`, the changelog and both plugin manifests

are generated, never edited by hand.

Merge the release PR to cut the version. The tag job tags `main` with

`v<version>` and publishes `skills_v<version>.zip`. Version `0.0.0` means

unreleased and is skipped.

## Generated files

- `ThirdPartyNotices.txt` is generated by `pnpm notices`; never edit it by hand.

- `CHANGELOG.md` and the versions are generated by changesets.

- The plugin manifests are generated by `scripts/sync-plugin-version.mjs`.

- `skills/<name>/scripts/main.ts` is generated by `pnpm scripts:generate`; never

## Links

- [README.md](README.md): product overview.

- [SKILLS.md](SKILLS.md): complete catalog.

- [CONTRIBUTING.md](CONTRIBUTING.md): skill format and contribution rules.

- [SECURITY.md](SECURITY.md): vulnerability reporting policy.