From 7eae160957824090fbe4209d0c7d07692ae58f54 Mon Sep 17 00:00:00 2001 From: Shadowtor <4159051+shadowtor@users.noreply.github.com> Date: Thu, 15 Oct 2026 13:37:14 +1100 Subject: [PATCH] Copy pass on README and agent install doc (SlopMonster) README: fewer semicolon-joined sentences, shorter stacked list items, the upstream credits rewritten in plain words. INSTALL-FOR-AGENTS.md: semicolons replaced with sentences. No facts, commands or links changed. The Pages site already scored 5/5. Co-Authored-By: Claude Sonnet 5.5 --- README.md | 27 ++++++++++++++------------- docs/INSTALL-FOR-AGENTS.md | 10 +++++----- 2 files changed, 19 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 77b189f..4d57305 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![Smoke test](https://github.com/shadowtor/BrandDesign/actions/workflows/test.yml/badge.svg)](https://github.com/shadowtor/BrandDesign/actions/workflows/test.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) **A brand identity and logo design skill for AI coding agents** (Claude Code, Codex CLI, Gemini CLI and anything that reads -Agent Skills folders: a directory with a `SKILL.md`). Give it a business brief; it researches the category, shows **three greyscale +Agent Skills folders: a directory with a `SKILL.md`). Give it a business brief. It researches the category, shows **three greyscale logo sketches** for you to choose from, has an **independent sub-agent review them**, and only then builds the full brand kit. ![Three example brands built entirely by the skill: Kiln, Rookery and Marigold Press](examples/overview.png) @@ -24,9 +24,9 @@ logo sketches** for you to choose from, has an **independent sub-agent review th | **Favicons** | favicon.svg/.ico, 16–48 px, apple-touch, 192/512, maskable, web manifest, head snippet, plus a **test sheet and report** (ICO structure, sizes, manifest, safe zone, 16 px legibility on light and dark tabs) | | **Social** | avatars (3 backgrounds × 3 sizes) and banners for LinkedIn, X, Facebook, YouTube, link previews, Instagram | | **Stationery** | A4 letterhead (sample + blank), header and footer strips, business card print file with bleed, email signature | -| **Merch mockups** | items chosen for the business type (a coffee bean bag and travel mug for a roaster; jersey, mouse mat and hoodie for a gaming community; USB stick, cables and lanyards for tech…), **photographic** via free PSD mockups (opt-in) or labelled illustrations | +| **Merch mockups** | items chosen for the business type (for example a bean bag and travel mug for a roaster, or a jersey and mouse mat for a gaming community), **photographic** via free PSD mockups (opt-in) or labelled illustrations | | **Guidelines** | a PDF built from the real files: idea, logo family, clear space, versions, colour (HEX/RGB/HSL/OKLCH, contrast), type, misuse (including ones only this mark can suffer), favicon test, social, stationery, merch | -| **Tokens** | CSS, SCSS, Tailwind, DTCG JSON, GIMP palette, swatches; font embed notes | +| **Tokens** | Colour tokens as CSS variables, SCSS, a Tailwind config and DTCG JSON, a GIMP palette, and font embed notes | **How it works:** intake → category research (bundled 1,400-logo and brand-palette libraries + live Fontsource/colour APIs) → 8–12 one-line concepts → **three different sketches** (black SVG, audited at 16 px, one colour, reversed) → independent review → @@ -77,7 +77,7 @@ Install the "brand-studio" Agent Skill for me. ### D. Upload as a skill file `python tools/package_skill.py` writes `dist/brand-studio.zip` (and a `-lite` zip without the reference SVGs) for UIs that take a skill upload. -Note: the skill runs scripts and a browser; use an environment that allows both (a code-capable agent, not plain chat). +Note: the skill runs scripts and a browser, so use an environment that allows both (a code-capable agent, not plain chat). ## Use @@ -89,7 +89,7 @@ Just ask: > Turn this symbol into a favicon set and social avatars, and test the favicon at 16 px. -It asks a few questions (or states assumptions), shows the concept sheet and **stops**. Pick a direction and say go; it builds the kit +It asks a few questions (or states assumptions), shows the concept sheet and **stops**. Pick a direction and say go, and it builds the kit into the folder you name (on Windows keep the work folder on a short path). Build a kit by hand from approved artwork: @@ -101,7 +101,7 @@ python skills/brand-studio/scripts/build_kit.py brand.json --out deliver --photo ``` Photographic merch previews are opt-in: the first run downloads free PSDs from mockups-design.com into `~/.cache/brand-studio` -(roughly 5 minutes; see [credits](#credits-and-attribution)). +(roughly 5 minutes, see the [credits](#credits-and-attribution)). ## Merch is chosen for the business @@ -121,7 +121,7 @@ Each item uses a photographic mockup when a free PSD exists, otherwise a drawn i ## Examples Fictional brands, built end to end. Each folder has the `brand.json`, the final SVG artwork, every SVG logo version, and previews of -the guidelines PDF, favicon test, social banner, letterhead and merch mockups. +the guidelines PDF and favicon test, plus a banner, the letterhead and merch. | Example | Business | Mark | Merch set | |---|---|---|---| @@ -134,8 +134,8 @@ the guidelines PDF, favicon test, social banner, letterhead and merch mockups. - **No trademark clearance.** Search before launch (IP Australia, WIPO Global Brand Database, EUIPO TMview, USPTO). The skill says so every time. - **CMYK is indicative, Pantone is blank.** Print needs the printer's profile and a proof. - **The favicon test is a simulated tab.** Open the live site in a real browser once. -- **Mockups are previews**, not publishable artwork; third-party PSDs are never redistributed. -- It cannot guarantee a mark is unique. The reference libraries are for study; never copy or trace them. +- **Mockups are previews**, not publishable artwork. Third-party PSDs are never redistributed. +- It cannot guarantee a mark is unique. The reference libraries are for study only. Never copy or trace them. ## Develop @@ -160,14 +160,15 @@ third-party material with their own terms: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_ ### Built on - **[kaankiziltug/logo-design-skill](https://github.com/kaankiziltug/logo-design-skill)** (MIT): the design process, principles, SVG construction and testing tooling, concept sheet, 1,400-logo reference library and its example boards. -- **[fatihaydost/brand-identity-skill](https://github.com/fatihaydost/brand-identity-skill)** (MIT): the one-mechanism idea, AI-defaults - reflex test, OKLCH palette build and WCAG/colour-blindness audit, honest print guidance, kit and critique structure, token export. +- **[fatihaydost/brand-identity-skill](https://github.com/fatihaydost/brand-identity-skill)** (MIT): the idea of one mechanism per brand, a + check against common AI defaults, an OKLCH palette build, a WCAG and colour-vision audit, honest print guidance, and the kit, + critique and token structure. ### Mockup sources (used for previews only) The photographic previews in `examples/` were made with free PSD mockups from **[mockups-design.com](https://mockups-design.com/)** (licence: free for any purpose including commercial use, no attribution required, but the PSD files themselves may not be -redistributed; flattened finished images may be shared: [licence](https://mockups-design.com/license/)). We credit them anyway. The PSDs +redistributed, though flattened finished images may be shared: [licence](https://mockups-design.com/license/)). We credit them anyway. The PSDs are **not** in this repository: the skill downloads them on demand into `~/.cache/brand-studio/mockups` when you run `--photo-mockups`. | Mockup | Pack | Used in | @@ -188,7 +189,7 @@ are **not** in this repository: the skill downloads them on demand into `~/.cach Merch items with no free PSD on that site (jersey, lanyard, phone case, cable, travel mug, sticker sheet…) are drawn by the skill and labelled **illustration** in every kit. **[Unblast](https://unblast.com/mockups/)** has many more (lanyards, jerseys, phone cases, USB cards, tumblers, coffee packaging): its mockups come from third-party authors with their own licences and a JavaScript -download step, so the skill does not download them automatically; download one yourself, read its licence, and pass it with +download step, so the skill does not download them automatically. Download one yourself, read its licence, and pass it with `psd_mockup.py --psd`. Thank you to both sites and to the mockup authors. ### Inspiration and reference sites diff --git a/docs/INSTALL-FOR-AGENTS.md b/docs/INSTALL-FOR-AGENTS.md index 94977cf..d06c62b 100644 --- a/docs/INSTALL-FOR-AGENTS.md +++ b/docs/INSTALL-FOR-AGENTS.md @@ -33,12 +33,12 @@ an older `brand-studio` folder in the target only: | One project only | `python tools/install.py --project` | `./.claude/skills/brand-studio` | | Other agent | `python tools/install.py --dest ` | `/brand-studio` | -Use `python3` instead of `python` on macOS/Linux when `python` is missing; on Windows use `python` or `py -3`. +Use `python3` instead of `python` on macOS/Linux when `python` is missing. On Windows use `python` or `py -3`. Add `--link` to symlink instead of copy (useful if the user will edit the repository). **Claude Code plugin alternative** (no clone needed): tell the user to run `/plugin marketplace add shadowtor/BrandDesign` and then `/plugin install brand-studio@brand-studio`. -You cannot run slash commands yourself; give them these two lines. +You cannot run slash commands yourself, so give them these two lines. ## 3. Verify @@ -46,7 +46,7 @@ You cannot run slash commands yourself; give them these two lines. python skills/brand-studio/scripts/check_setup.py ``` -Expected: `PASS` for Python and a Chromium browser; `PASS` or `WARN` for uv and network. A `FAIL` means the skill cannot work: +Expected: `PASS` for Python and a Chromium browser, and `PASS` or `WARN` for uv and network. A `FAIL` means the skill cannot work: fix it first (the line includes the fix). `INFO` lines for Pillow/pypdf/fonttools are normal: they are installed on demand. If `uv` is missing, offer to install it (command is in the `WARN` line) or run `pip install pillow pypdf fonttools uharfbuzz pymupdf` (plus `"psd-tools[composite]" numpy scipy scikit-image` for `--photo-mockups`) for the same effect. @@ -68,8 +68,8 @@ The skill will ask a few questions, research the category, show three greyscale - Never run scripts from the skill other than `check_setup.py` during installation. - Never commit, push or publish anything on the user's behalf. - Never download files other than the repository itself. (Photographic mockups are downloaded later, on demand, by the skill, and only - when the user asks for them; see the README credits.) -- If a step fails, show the exact error and stop; do not improvise a different install location without asking. + when the user asks for them. See the README credits.) +- If a step fails, show the exact error and stop. Do not improvise a different install location without asking. ## 6. Uninstall