docs: cross-agent install and usage guidance

- README.md: Gemini CLI install block
- install-guidance.md: refresh Gemini section — `gemini skills link` now shipped (#18294), slash commands, tier precedence, npm-based upgrade
- CONTRIBUTING.md: Gemini CLI link+reload hints alongside the Claude validate step
- GEMINI.md: project-specific agent guidance auto-loaded by Gemini CLI

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: aklofas

CONTRIBUTING.md

@@ -134,8 +134,11 @@ description: One paragraph describing what this skill does and when to use it. I
 
 2. Add any scripts to `skills/<name>/scripts/`
 3. Add a symlink in `.agents/skills/`: `ln -s ../../skills/<name> .agents/skills/<name>`
+    *   **Gemini CLI:** Use `gemini skills link . --scope workspace` to link the whole repo.
 4. Update the manual install lists in `README.md` (both Claude Code and Codex sections)
-5. Validate: `claude plugin validate .`
+5. Validate:
+    *   **Claude Code:** `claude plugin validate .`
+    *   **Gemini CLI:** Run `/skills reload` in an active session to verify discovery.
 
 Keep SKILL.md language agent-neutral — use "the agent" instead of "Claude", "use web search" instead of "WebSearch", etc.
 

GEMINI.md

@@ -1,10 +1,17 @@
 # kicad-happy
 
-AI-powered electronics design review skills for KiCad 5-10. This repo provides structured Python analysis scripts and skill definitions for AI coding agents.
+AI-powered electronics design review skills for KiCad 5-10. This document is auto-loaded into the Gemini CLI context and carries project-specific guidance for agents working in this repo.
 
-## Skills
+## Agent guidelines
+
+1. **Skill activation**: invoke `activate_skill` before running the Python scripts in this repo. Each skill's `SKILL.md` carries procedural guidance, triggers, and constraints that aren't in the main system prompt.
+2. **Context efficiency**:
+    - **Search first**: use `grep_search` to find points of interest in `.kicad_sch` and `.kicad_pcb` files — they routinely exceed 10,000 lines.
+    - **Targeted reads**: avoid reading whole schematic/PCB files. Use line numbers from `grep_search` for surgical `read_file` calls.
+    - **Trust analyzer output**: the Python analysis scripts are the source of truth for design data. Don't guess circuit behavior from raw S-expressions when a detector already covers it.
+3. **Validation**: a change isn't done until the relevant `analyze_*.py` script has been re-run and produces no new warnings or regressions.
 
-Each skill is defined in `skills/<name>/SKILL.md` with usage instructions and triggers. Read the relevant SKILL.md before using a skill.
+## Skills
 
 | Skill | Purpose |
 |-------|---------|
@@ -39,7 +46,7 @@ python3 skills/emc/scripts/analyze_emc.py --schematic sch.json --pcb pcb.json
 python3 skills/kicad/scripts/analyze_gerbers.py <gerber_dir>/
 ```
 
-All scripts are zero-dependency (Python 3.8+ stdlib only). No pip install needed.
+All scripts are zero-dependency (Python 3.10+ stdlib only). No `pip install` needed.
 
 ## Code structure
 
@@ -55,7 +62,7 @@ All scripts are zero-dependency (Python 3.8+ stdlib only). No pip install needed
 - `skills/kicad/references/` — 19 deep methodology guides
 - `skills/datasheets/` — Extraction pipeline with 4 reference guides (schema, field-extraction, scoring, consumer API)
 
-## Key docs
+## Documentation reference
 
 - `CONTRIBUTING.md` — How detectors work, how to add skills, test harness usage
 - `VALIDATION.md` — Test methodology and corpus statistics

README.md

@@ -117,13 +117,19 @@ Use Codex's built-in skill installer first:
 
 If you prefer a manual install, install the skills into `~/.codex/skills/`.
 
-Clone the repo:
+**Google Gemini CLI:**
+
+Install the skills globally for your user:
 
 ```bash
-git clone https://github.com/aklofas/kicad-happy.git
+gemini skills install https://github.com/aklofas/kicad-happy.git
 ```
 
-After installing new skills, restart Codex if they do not appear immediately.
+Or install them to your current workspace only:
+
+```bash
+gemini skills install https://github.com/aklofas/kicad-happy.git --scope workspace
+```
 
 <details>
 <summary><strong>Manual install & other platforms</strong></summary>

install-guidance.md

@@ -273,37 +273,43 @@ Or `git pull` for symlink installs.
 
 ### Install
 
+Install the skills globally to `~/.gemini/skills/`:
+
 ```bash
 gemini skills install https://github.com/aklofas/kicad-happy.git
 ```
 
-This installs to `~/.gemini/skills/` (user scope) by default. For repo-local:
+For repo-local (workspace) installation:
 
 ```bash
 gemini skills install https://github.com/aklofas/kicad-happy.git --scope workspace
 ```
 
 ### Install (manual symlinks)
 
-Gemini CLI discovers skills from `~/.gemini/skills/` or `~/.agents/skills/`:
+Gemini CLI discovers skills from `~/.gemini/skills/` or `~/.agents/skills/`. The `gemini skills link` command is the standard way to set up a development environment:
 
 ```bash
 git clone https://github.com/aklofas/kicad-happy.git
 cd kicad-happy
-mkdir -p ~/.gemini/skills
-for skill in kicad spice emc datasheets bom digikey mouser lcsc element14 jlcpcb pcbway kidoc; do
-  ln -sf "$(pwd)/skills/$skill" ~/.gemini/skills/$skill
-done
+gemini skills link .
 ```
 
-### Management
+### Management & Interactive Mode
 
-```bash
-gemini skills list
-gemini skills enable <name>
-gemini skills disable <name>
-gemini skills uninstall <name>
-```
+You can manage skills from the terminal or interactively using slash commands:
+
+*   **`gemini skills list`** / **`/skills list`**: List all discovered skills.
+*   **`gemini skills enable/disable <name>`** / **`/skills enable/disable <name>`**: Toggle a skill.
+*   **`/skills reload`**: Refresh the skill registry (use after editing `SKILL.md` or scripts).
+*   **`/skills link <path>`**: Link local skills during an active session.
+
+### Skill Tier Precedence
+
+Gemini CLI discovers skills in three tiers with the following precedence:
+1.  **Workspace Tier**: `.gemini/skills/` or `.agents/skills/` in the project root.
+2.  **User Tier**: `~/.gemini/skills/` or `~/.agents/skills/`.
+3.  **Extension Tier**: Bundled within installed extensions.
 
 ### Upgrade
 
@@ -312,15 +318,13 @@ gemini skills uninstall kicad-happy
 gemini skills install https://github.com/aklofas/kicad-happy.git
 ```
 
-Or `git pull` for symlink installs.
+For linked installs, simply `git pull` in the cloned repository and run `/skills reload`.
 
 ### Known issues
 
-- Skills support is relatively new (v0.23.0+). The `gemini skills` commands are
-  still evolving.
-- `gemini skills link` (symlink-based install, like `gemini extensions link`) is
-  an open feature request
-  ([google-gemini/gemini-cli#18294](https://github.com/google-gemini/gemini-cli/issues/18294)).
+- Skill discovery is most stable in v0.25.0+. Ensure your CLI is up to date by running:
+  `npm install -g @google/gemini-cli@latest`
+- Large skill directories may take a moment to index during initial startup.
 
 ### Gemini-specific notes