ConardLi/garden-skills instruction manual

1. Purpose, Claude Code classification, and repository model

Garden Skills instruction manual

Garden Skills is a public MIT-licensed collection of five documented Agent Skills: `web-video-presentation`, `web-design-engineer`, `gpt-image-2`, `kb-retriever`, and `beautiful-article`. They are intended for Claude Code and other hosts that recognize the `SKILL.md` format.

**Claude Code classification:** primarily **context injection**, with **tool-surface helpers** in skills that bundle scripts. **Install mode:** `claude_extension`. **Setup effort:** low for copying or marketplace installation, but medium when a workflow needs API credentials, PDF/Excel tooling, Node/npm builds, or optional TTS/PDF utilities. The evidence shows Claude Code loading skill instructions and, where applicable, invoking local scripts; it does not show a separate model gateway or standalone agent runtime.

A skill is a folder whose required `SKILL.md` contains YAML frontmatter and operational guidance. Optional `references/`, `scripts/`, and `assets/` are loaded or used as needed. The frontmatter `description` tells the agent when to activate it. Claude Code can discover a skill at `.claude/skills/<name>/` or through the repository’s plugin marketplace.

The root documentation reports tested compatibility with Claude Code, Claude.ai Skills, Cursor, Codex CLI, Gemini CLI, and OpenCode. Their documented locations are `.claude/skills/`, `.agents/skills/`, `.codex/skills/`, an extension manifest, and `.opencode/skills/`, respectively.

2. Install with the skills CLI or Claude Code marketplace

The agent-agnostic installation path uses the documented `skills` CLI. Installing from the repository without a tag follows the latest commit on `main`. Select one skill with `-s`, install globally with `--global`, or explicitly target Claude Code with `-a claude-code`.

npx skills add ConardLi/garden-skills
npx skills add ConardLi/garden-skills -s web-design-engineer
npx skills add ConardLi/garden-skills -s gpt-image-2 --global
npx skills add ConardLi/garden-skills -s kb-retriever -a claude-code

For a tag-pinned skill, use the documented tag-scoped tree URL:

npx skills add ConardLi/garden-skills/tree/web-design-engineer-v1.0.0/skills/web-design-engineer

Manage CLI-installed skills with:

npx skills list
npx skills find web-design
npx skills update
npx skills remove kb-retriever

Claude Code users can instead subscribe to the marketplace and install the four documented plugin packs:

/plugin marketplace add ConardLi/garden-skills
/plugin install presentation-skills@garden-skills
/plugin install web-design-skills@garden-skills
/plugin install knowledge-base-skills@garden-skills
/plugin install image-generation-skills@garden-skills

These map respectively to `web-video-presentation`, `web-design-engineer`, `kb-retriever`, and `gpt-image-2`. The supplied marketplace table does not document a `beautiful-article` plugin pack, so install that skill by another supported method.

3. Reproducible releases, manual copying, and submodules

For reproducible or air-gapped use, each formal skill release is documented as an immutable ZIP with a SHA-256 checksum. Replace the sample variables with an existing release version, download both files, verify the checksum, and unzip into the directory scanned by your agent:

SKILL=web-design-engineer
VERSION=1.0.0

curl -fsSL -o "${SKILL}.zip" \
  "https://github.com/ConardLi/garden-skills/releases/download/${SKILL}-v${VERSION}/${SKILL}-${VERSION}.zip"
curl -fsSL -o "${SKILL}.zip.sha256" \
  "https://github.com/ConardLi/garden-skills/releases/download/${SKILL}-v${VERSION}/${SKILL}-${VERSION}.zip.sha256"
shasum -a 256 -c "${SKILL}.zip.sha256"
unzip -q "${SKILL}.zip" -d .claude/skills/

The root README also links current artifacts: presentation 1.2.2, web design 1.3.0, image 1.0.4, retriever 1.0.1, and article 0.1.0. Prefer those explicit links over the shown floating placeholder URL, which still contains `<skill>` and `<version>`.

For editable source, clone and copy a skill:

git clone https://github.com/ConardLi/garden-skills.git
cp -r garden-skills/skills/web-design-engineer your-project/.claude/skills/

For vendoring and upstream tracking:

git submodule add https://github.com/ConardLi/garden-skills.git vendor/garden-skills
ln -s ../../vendor/garden-skills/skills/web-design-engineer .claude/skills/web-design-engineer
cd vendor/garden-skills
git checkout web-design-engineer-v1.0.0

A clone tracks `main`; a submodule is pinned by its recorded SHA and may additionally be checked out at a release tag.

4. web-video-presentation: scripted, recordable 16:9 presentations

Use `web-video-presentation` to convert an article, lesson, talk, product demo, or existing voiceover into a click- or keyboard-driven web presentation. It scaffolds Vite, React, and TypeScript around a fixed 1920×1080 stage that scales to the viewport. A persisted `(chapter, step)` cursor advances one narration beat at a time, while progress chrome appears only on hover for clean recording.

The workflow identifies the input, optionally rewrites an article as narration, then pauses at **Checkpoint A1** for script, theme, and rough assets. It creates `outline.md` and pauses at **A2** for outline and development-mode approval. After implementation, **Checkpoint B** asks whether to synthesize narration. Recording and post-production follow. This deliberate pacing prevents theme, motion, and chapter structure from drifting.

Create a project or inspect the 23 themes with:

bash skills/web-video-presentation/scripts/scaffold.sh ./presentation --theme=paper-press
bash skills/web-video-presentation/scripts/scaffold.sh --list-themes

Themes are token-based but have distinct visual signatures; examples include `midnight-press`, `blueprint`, `terminal-green`, `creative-voltage`, `newsroom`, `swiss-ikb`, and `split-canvas`. Every scene should have a moving visual anchor rather than static paragraphs.

Optional TTS uses a provider-neutral runner. Built-ins are MiniMax through `mmx-cli` and OpenAI TTS through `curl` and `OPENAI_API_KEY`. Provider snippets are documented for ElevenLabs, edge-tts, Azure, Google Cloud, and macOS `say`. The supplied README does not document a command for running the generated Vite project, so use the scaffold through the agent rather than assuming an unlisted command.

5. web-design-engineer: calibrated frontend design and verification

Use `web-design-engineer` for pages, landing sites, dashboards, prototypes, HTML presentations, UI mockups, data visualizations, design systems, and motion work. It improves design judgment through a seven-stage workflow: understand requirements; gather code or screenshot context; classify an existing project as extension, preserve, or overhaul; produce a five-dial Design Read; declare colors, typography, spacing, and motion before coding; show a v0 early; build fully; and verify.

The five dials cover visible variance, motion, density, asset dependence, and brand fidelity. Anti-cliché guidance rejects routine AI defaults such as decorative purple-pink-blue gradients, left-border cards, emoji icons, and fabricated testimonials or statistics. Color derivation uses `oklch()`. Browser acceptance is **opt-in**: executable responsive, interaction, and runtime QA runs only when the user explicitly requests acceptance, QA, or browser testing.

For a named aesthetic anchor, the agent progressively loads one of 25 recipe files instead of the entire catalog. The seven groups are editorial/minimalist, information architecture, builder SaaS, motion/experimental, brutalist/raw, warm humanist, and specialty/genre. Examples include `aesop`, `tufte-dataink`, `linear`, `active-theory`, `stripe-press`, and `y2k-retrofuturism`.

Run the documented recipe gallery locally with:

cd demo/web-design-engineer-demo
npm install && npm run dev

It serves at `http://localhost:5181/`; hash routes such as `#/linear` open recipes, `H` toggles the HUD, and `Esc` returns to the gallery. Side-by-side static demonstrations also live under `demo/web-design-demo/`.

6. gpt-image-2: generation, editing, delegation, and prompt advising

`gpt-image-2` handles only OpenAI-compatible image generation and editing: `POST /images/generations` and `POST /images/edits`. It first detects one of three modes:

node skills/gpt-image-2/scripts/check-mode.js
node skills/gpt-image-2/scripts/check-mode.js --json

**Mode A, Garden local** requires a truthy `ENABLE_GARDEN_IMAGEGEN` (`1`, `true`, `yes`, or `on`) and `OPENAI_API_KEY`; it renders a structured prompt, calls the API, and saves the image. **Mode B** renders a prompt and delegates to a host-native image tool. **Mode C** has no image tool, so it writes a reusable prompt for the user. B and C have no CLI generation entry point.

Mode A examples:

node skills/gpt-image-2/scripts/generate.js \
  --prompt "A cute baby sea otter" --size 1024x1024 --quality high
node skills/gpt-image-2/scripts/generate.js \
  --promptfile garden-gpt-image-2/prompt/poster-20260424-153045.md
node skills/gpt-image-2/scripts/edit.js \
  --image assets/source.png --prompt "Replace the background with a clean studio scene"
node skills/gpt-image-2/scripts/edit.js \
  --image assets/source.png --mask assets/mask.png \
  --prompt "Replace only the masked area with a glass vase"

Configuration precedence is CLI arguments, `process.env`, workspace `.env`, workspace `.gateway.env`, then `~/.gateway.env`. `OPENAI_BASE_URL` defaults to `https://api.openai.com/v1`; `OPENAI_IMAGE_MODEL` defaults to `gpt-image-2`. Prompts go to `garden-gpt-image-2/prompt/<slug>-<timestamp>.md`; Mode A images go to `garden-gpt-image-2/image/<slug>-<timestamp>.png`.

The skill documents 79 templates and 18 categories, while the companion static gallery README reports 17 categories and 161 cases. Treat that category count as documentation drift.

7. kb-retriever: bounded retrieval over a local knowledge base

`kb-retriever` answers natural-language questions from a user-supplied local corpus of Markdown, text, PDF, and Excel files. Put the default corpus at workspace-root `knowledge/`, or name another path in the question, such as “answer from `./docs`.” If neither exists nor is specified, the workflow asks rather than guessing.

Each indexed directory should contain `data_structure.md` describing its purpose, files or subdirectories, schema or contents, and coverage such as date, version, or source. Retrieval always starts at this index, follows only relevant branches, searches with `grep`, and reads small matching windows—approximately 200–500 lines—with offset and limit. It stops when evidence is sufficient or after five rounds.

PDF and Excel have a mandatory learn-before-process gate. Before a PDF, the agent reads `references/pdf_reading.md`; before Excel reading or analysis, it reads `excel_reading.md` or `excel_analysis.md`. PDFs are extracted to a file and then searched:

pdftotext input.pdf output.txt

For large PDFs, the documented pattern is page-ranged extraction such as:

pdftotext -f 1 -l 10 input.pdf output.txt

Do not send PDF extraction to stdout or grep raw binary files. Excel work uses pandas, first with `nrows` to learn the schema, then filtered reads after identifying key ID, time, or category columns. Required host capabilities are `grep`, windowed `read_file`, `pdftotext` or `pdfplumber`, and pandas. `scripts/convert_pdf_to_images.py` is the fallback for scanned PDFs whose text extraction is unusable. Answers should cite the source material found.

8. beautiful-article: editorial planning, building, review, and delivery

Use `beautiful-article` when the desired result is an article—not an app, form, dashboard, or generic landing page. It accepts URLs, PDF, DOCX, Markdown, text, screenshots, and pasted notes, then edits them into a self-contained HTML article, optionally accompanied by PDF. It targets the ReActicle component protocol: semantic components such as `Hero`, `Lead`, `Section`, `Quote`, `Callout`, `Image`, `Formula`, `CodeBlock`, and `Table`, plus a constrained `Raw` layer using only `--ra-*` theme tokens.

The flow is intake; source-to-Markdown; editorial planning; **Checkpoint 1**; first-spread proof; **Checkpoint 2**; full build; editorial, visual, and technical review; minimal-slice repair; **Checkpoint 3**; delivery. At Checkpoint 1, confirm article type/retention, theme, width, image mode, and cover independently. Types range from `longform` at about 100% retention through `briefing` at about 50% and `interactive-explainer` at about 25% excerpt plus 75% rebuild. Eleven themes include `tufte`, `press`, `bayer`, `vignelli`, `fuller`, `knuth`, and `shannon`. A 3:4 cover and table of contents are defaults, but decisions are not silently assumed.

Scaffold with:

bash <path-to-skill>/scripts/scaffold.sh ./my-article --theme=tufte
bash <path-to-skill>/scripts/scaffold.sh ./my-article --theme=press --no-cover
bash <path-to-skill>/scripts/scaffold.sh --list-themes

Each section belongs in `article/sections/NN-*.tsx`; `Article.tsx` only assembles them. Build the single inlined output with:

npm run build

This produces `article/article.html`. Only after selecting HTML plus PDF at the delivery checkpoint, run:

bash <path-to-skill>/scripts/html-to-pdf.sh

Subagents may review the first spread, sections, and final output; without subagent support, the main agent performs the documented fallback.

9. Maintenance, evidence limits, and safe operating notes

Repository contributors can clone, list skills and manifest status, and run the same validation documented for pull requests:

git clone https://github.com/ConardLi/garden-skills.git
cd garden-skills
npm run list
npm run validate

The root README directs maintainers to `CONTRIBUTING.md` or its Chinese translation for repository layout, release rules, CI, and troubleshooting. No other maintenance commands should be inferred from the supplied files.

Operational requirements vary by skill. Image generation needs an API credential only in Garden Mode A and may send prompts or images to the configured OpenAI-compatible endpoint. Local retrieval needs the listed PDF/Excel tools and does not provide a knowledge base. Article and presentation workflows need shell/file access and generated Vite projects; article PDF export additionally requires the documented headless-browser script path. TTS is optional and provider-dependent.

Known evidence cautions: the root CLI comments still say “four skills” although five are documented; only four Claude Code marketplace packs are listed; image-category counts differ between the skill and companion website; and the supplied files do not establish minimum Claude Code, Node, Python, browser, API-model, or third-party tool versions for the collection as a whole. The companion image website alone documents Node 18 or newer, preferably Node 20+, but that should not be generalized to every skill.

All capability and compatibility claims in this manual are repository-authored rather than independently tested here. Review generated code, image output, source citations, editorial retention, credentials, and external-service terms before production use. The repository metadata identifies the project as public, unarchived, and MIT-licensed.