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
├── guidelines/        # Plain-markdown guidelines
│   ├── README.md
│   ├── webhub.md             # stack-agnostic webhub baseline
│   ├── webhub-laravel.md     # Laravel/PHP
│   └── webhub-craft-cms.md   # Craft CMS (scaffold)
├── 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

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.

Stack-specific guidelines (webhub-laravel.md, webhub-craft-cms.md) are intentionally not loaded globally — they're pulled into each project repo by their starter packages (laravel-starter's webhub:post-autoload hook, future craft-starter, …) and committed there. That way Claude only sees Laravel rules in Laravel work and Craft rules in Craft work.

To update: re-run the one-liner from the directory above the clone, or cd into the clone and run git pull && ./bootstrap.sh. Symlinks pick up new commands automatically; re-running bootstrap.sh is only required when new globally-imported guidelines are added.

Onboarding — manual fallback

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

ln -sfn "$PWD/commands" ~/.claude/commands/webhub
echo "@$PWD/guidelines/webhub.md" >> ~/.claude/CLAUDE.md

Guidelines

Plain markdown files consumed by AI tooling in our projects.

• User-level (this repo, via bootstrap.sh): imports the full set into ~/.claude/CLAUDE.md.
• Project-level: Laravel apps pull webhub-laravel.md (+ spatie's laravel-php-ai-guidelines.md) into .ai/guidelines/ automatically — both php artisan webhub:install and webhub:update do this, and the webhub:post-autoload hook keeps them fresh on every composer dump-autoload.
• Raw URL pattern: https://raw.githubusercontent.com/webhubworks/ai/main/guidelines/<file> — keep main stable.

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.
• Add a curl line in laravel-starter's publishCustomAiGuidelines() if it should land in every Laravel project.

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. Consumers re-pull:
   • User-level (~/.claude/…): git -C ~/reps/ai pull — symlinks update commands automatically; new guidelines need a re-run of bootstrap.sh.
   • Laravel projects: php artisan webhub:update (or just composer dump-autoload thanks to the webhub:post-autoload hook).
   • claude.ai Skills: re-zip and re-upload via the admin UI.