webhubworks/ai

Shared AI assets for webhub GmbH — guidelines, Skills, and slash-commands used across our Laravel and Craft CMS projects, and uploaded to our claude.ai Team workspace.

TL;DR — install/update in one line

cd into your dev directory first (~/reps, ~/code, whatever you use), then run:

[ -d ai ] || git clone https://github.com/webhubworks/ai.git && cd ai && git pull && ./bootstrap.sh

Clones webhubworks/ai into the current directory if it isn't already there, pulls the latest, then runs bootstrap.sh to wire commands and guidelines into ~/.claude. Safe to re-run any time — it's the update path too.

Layout

ai/
├── bootstrap.sh       # One-shot installer that links this repo into ~/.claude
├── hooks/
│   └── session-start.sh      # Claude Code SessionStart hook: detects the stack,
│                             # injects the matching guideline(s), throttled auto-pull
├── guidelines/        # Plain-markdown guidelines
│   ├── README.md
│   ├── webhub.md                  # stack-agnostic webhub baseline
│   ├── webhub-laravel.md          # Laravel/PHP
│   ├── webhub-craft-cms.md        # Craft CMS (scaffold)
│   └── laravel-php-guidelines.md  # Spatie's Laravel/PHP standards, mirrored from spatie.be
├── skills/            # Skills — linked into ~/.claude/skills by bootstrap.sh,
│   │                  # and each subfolder also zips up into one claude.ai Skill
│   ├── laravel/
│   │   ├── SKILL.md             # thin wrapper - the rules live in the guideline
│   │   └── reference.md         # → ../../guidelines/webhub-laravel.md (symlink)
│   ├── craft-cms/
│   │   ├── SKILL.md             # thin wrapper - the rules live in the guideline
│   │   └── reference.md         # → ../../guidelines/webhub-craft-cms.md (symlink)
│   └── craft-upgrade/        # Craft major-version upgrade playbook
│       ├── SKILL.md          # orchestrator (only its description loads per session)
│       ├── upgrading-across-multiple-major-versions.md
│       ├── v2-to-v3/ v3-to-v4/ v4-to-v5/   # per-leg docs, read on demand
│       └── v5-to-v6/         # placeholder until the first 5→6 upgrade
└── commands/          # Slash-commands for Claude Code
    ├── laravel/                       # → /webhub:laravel:<name>
    │   ├── commit-and-simplify.md
    │   └── simplify.md
    ├── plan-issue.md                  # → /webhub:plan-issue
    └── security-review.md             # → /webhub:security-review

How distribution works (read this first)

Everything is served from your local clone of this repo, so a single git pull updates every project on your machine — no composer update, nothing committed into project repos.

There are two layers, both wired up by bootstrap.sh:

1. Stack-agnostic baseline — guidelines/webhub.md is @-imported into ~/.claude/CLAUDE.md. The import points at the live file in this clone, so it's in context for every session in every project, and updates the moment you pull.
2. Stack-specific guidelines — a Claude Code SessionStart hook (hooks/session-start.sh) runs at the start of every session. It:
   • detects the project type from the working directory (composer.json → laravel/framework = Laravel, craftcms/cms = Craft; falls back to artisan / craft marker files),
   • reads the matching guideline(s) straight from this clone (webhub-laravel.md + laravel-php-guidelines.md for Laravel; webhub-craft-cms.md for Craft) and injects them as session context, prefixed with the detected project type,
   • runs a throttled background git pull of this clone (at most once/hour, fully detached, offline-safe) so edits you push here reach every developer's next session automatically.

So Claude opens every session already knowing the stack and with the right rules loaded — in any repo, including Craft and non-PHP repos — and guideline edits propagate on their own.

One-time per developer: the hook can't install itself — bootstrap.sh is what wires it into ~/.claude/settings.json. After that single git pull && ./bootstrap.sh, it's hands-off: the hook keeps the clone fresh and serves the latest guidelines with no further action. You only need to re-run bootstrap.sh if the wiring itself changes (a new globally-imported guideline, or a change to how the hook is registered) — never for ordinary guideline or hook-script edits.

Onboarding — bootstrap.sh (recommended)

See the one-liner above. What bootstrap.sh does, idempotently:

• Symlinks commands/ into ~/.claude/commands/webhub/, so every slash-command in this repo is available as /webhub:<name> (subdirs add namespace segments — e.g. /webhub:laravel:simplify).
• Symlinks each skills/<name>/ folder into ~/.claude/skills/<name>/, so every skill is discoverable in Claude Code — available as /<name> and auto-invoked from its description. Only the description loads each session; a skill's body and any bundled reference docs are read on demand. A pre-existing non-symlink ~/.claude/skills/<name> is left untouched (your personal skills are safe).
• Appends an @<path> import for the stack-agnostic webhub.md to ~/.claude/CLAUDE.md, so the webhub baseline applies to every session regardless of stack. Existing content in ~/.claude/CLAUDE.md is left untouched.
• Registers the SessionStart hook (hooks/session-start.sh) in ~/.claude/settings.json under matcher: "*" (fires on startup, resume, clear, compact). Wiring is idempotent and relocation-safe (a moved clone replaces the old entry instead of stacking), and any unrelated SessionStart hooks you have are left intact.

To update: re-run the one-liner from the directory above the clone, or cd into the clone and run git pull && ./bootstrap.sh. In practice the hook's auto-pull keeps the clone fresh on its own; re-running bootstrap.sh is only required when the wiring changes (see the note above).

Onboarding — manual fallback

From inside your clone of this repo, the same effect by hand:

ln -sfn "$PWD/commands" ~/.claude/commands/webhub
echo "@$PWD/guidelines/webhub.md" >> ~/.claude/CLAUDE.md
chmod +x "$PWD/hooks/session-start.sh"
# Then register the SessionStart hook in ~/.claude/settings.json (jq):
jq --arg cmd "$PWD/hooks/session-start.sh" \
  '.hooks.SessionStart = ((.hooks.SessionStart // []) + [{"matcher":"*","hooks":[{"type":"command","command":$cmd,"timeout":30}]}])' \
  ~/.claude/settings.json > /tmp/s.json && mv /tmp/s.json ~/.claude/settings.json

(bootstrap.sh does all of this idempotently and is the recommended path.)

Guidelines

Plain markdown files served to Claude from this clone (never copied into project repos):

• Stack-agnostic baseline — webhub.md is @-imported into ~/.claude/CLAUDE.md by bootstrap.sh, so it's in context for every session everywhere.
• Stack-specific — webhub-laravel.md (+ the mirrored laravel-php-guidelines.md) and webhub-craft-cms.md are injected by the SessionStart hook only when it detects that project type. Claude sees Laravel rules in Laravel work, Craft rules in Craft work, nothing extra elsewhere.
• Because everything resolves to the live files in this clone, a git pull (the hook auto-pulls hourly) updates every project at once. Nothing is committed into consuming repos anymore.

laravel-php-guidelines.md is mirrored from Spatie (https://spatie.be/laravel-php-ai-guidelines.md). It's vendored here so the hook can serve it locally with no network dependency. Refresh it occasionally with:

curl -fsSL -o guidelines/laravel-php-guidelines.md https://spatie.be/laravel-php-ai-guidelines.md

To add a new guideline file, drop it into guidelines/ and:

• Add it to the GUIDELINES=( … ) array in bootstrap.sh if it should apply user-level to every session (stack-agnostic).
• Wire it into hooks/session-start.sh's case "$stack" mapping if it should load for a specific stack (and add detection there if it's a new stack).

Skills

Each subfolder under skills/ is one Skill, consumed in two places:

• Claude Code (local): bootstrap.sh symlinks every skill into ~/.claude/skills/, so they're discoverable automatically — available as /<name> and auto-invoked from their description. Nothing else to do.
• claude.ai org-wide: upload each as a .zip with SKILL.md (and any bundled files) at the root of the zip — no wrapper directory.

cd skills/laravel        && zip ../laravel.zip       SKILL.md reference.md && cd -   # zip follows the symlink, so the guideline content lands as reference.md
cd skills/craft-cms      && zip ../craft-cms.zip     SKILL.md reference.md && cd -   # same — keeps the upload self-contained
cd skills/craft-upgrade  && zip -r ../craft-upgrade.zip . && cd -   # bundles SKILL.md + reference docs

The laravel and craft-cms skills are thin wrappers: their SKILL.md just points to a bundled reference.md, which is a symlink to the corresponding guidelines/webhub-*.md (the single source of truth). Editing the guideline updates the skill everywhere - locally the symlink resolves live; for claude.ai the zip above dereferences it into the archive. Never duplicate guideline content into SKILL.md.

Then in claude.ai: Settings → Skills → Organization skills → + Add → pick the .zip. Only the org owner can publish org-wide skills.

When a skill grows extra files (examples, scripts, reference docs — like craft-upgrade's per-leg docs), zip the contents of its folder so siblings of SKILL.md sit at the zip root.

craft-upgrade — keeping it lean

craft-upgrade bundles large per-leg reference docs (Craft's official upgrade docs, plus webhub's pitfalls/protocols). These are not loaded every session: only SKILL.md's description loads at session start. Claude reads the body when an upgrade task begins, and then reads only the version-specific docs matching the from→to versions. That's why a Craft upgrade playbook can live here without bloating every unrelated session.

Editing

1. Edit the file here.
2. Commit + push.
3. It propagates automatically:
   • Guidelines, the hook script, commands, skills: nothing to do. Each developer's SessionStart hook auto-pulls this clone (≤ 1h), and everything resolves to live files/symlinks — so the next session already has the change. A developer who wants it now can git -C ~/reps/ai pull.
   • Wiring changes only (a new globally-imported guideline added to bootstrap.sh, or a change to how the hook is registered): developers re-run git pull && ./bootstrap.sh once.
   • claude.ai Skills: re-zip and re-upload via the admin UI.

Note: webhubworks/laravel-starter no longer publishes guidelines into project repos. The SessionStart hook is the single source for Claude Code; its webhub:post-autoload now removes any stale .ai/guidelines/ copies it finds (and re-runs boost:update) so Boost stops composing outdated rules.