feat: add agentic install instruction

README.md

@@ -67,17 +67,25 @@ For a detailed breakdown of the quality and verifiability criteria used in our e
 
 ## 🚀 Quick Start
 
-### Option 1: Install the Hosted Skill (Recommended)
+### Two Skill Versions
+
+SkillsVote currently ships two agent-facing skills:
+
+- **`skills-vote`**: recommends skills from the hosted SkillsVote service. Use this when the agent can call the cloud recommendation API and you want fresh recommendations from the public SkillsVote ecosystem.
+- **`skills-vote-local`**: recommends skills from local or private skill libraries. Use this when the agent should search skills already present on the machine, in the current workspace, or in private directories that should not be sent to the hosted service.
+
+### Option 1: Install the Hosted Skill `skills-vote` (Cloud)
 
 #### 🤖 Agent Setup Prompt
 
 Supercharge your agents (Codex, Claude Code, OpenClaw) by integrating SkillsVote directly! Just drop this prompt into your agent:
 
 ```markdown
-1. Install the skill by running `npx skills add MemTensor/skills-vote --skill skills-vote`
-2. Create or update `.env` file located in the root directory of the installed `skills-vote` skill and set `SKILLS_VOTE_API_KEY="YOUR_API_KEY"`
+Fetch and follow installation instructions from https://raw.githubusercontent.com/MemTensor/skills-vote/main/docs/INSTALL.md
 
-Do not configure this as a system or user-level environment variable unless explicitly requested.
+Use the following values: 
+`SKILLS_VOTE_API_KEY`: `YOUR_API_KEY`
+`GITHUB_TOKEN`:`YOUR_GH_TOKEN`
 ```
 
 #### 🔧 Manual Setup Alternative
@@ -102,7 +110,25 @@ npx skills add MemTensor/skills-vote --skill skills-vote
 > [!note]
 > Don't forget to replace `YOUR_API_KEY` with your actual key!
 
-### Option 2: Run the Local Demo 🏠
+### Option 2: Install the Local Skill `skills-vote-local` (Private Libraries)
+
+Use this when you want the agent to recommend from local skills instead of the hosted SkillsVote service.
+
+#### 🤖 Agent Setup Prompt
+
+```markdown
+Fetch and follow installation instructions from https://raw.githubusercontent.com/MemTensor/skills-vote/main/docs/INSTALL_LOCAL.md
+```
+
+#### 🔧 Manual Setup Alternative
+
+```bash
+npx skills add MemTensor/skills-vote --skill skills-vote-local
+```
+
+After installation, open the installed skill root and configure `config/config.yaml`. See [Install SkillsVote Local](docs/INSTALL_LOCAL.md) for the full configuration flow.
+
+### Option 3: Run the Local Demo 🏠
 
 Want to test drive the core engine locally? Just follow these 3 easy steps:
 

docs/INSTALL.md

@@ -0,0 +1,92 @@
+# Install SkillsVote
+
+Use this guide when asked to install the `skills-vote` skill for the current agent.
+
+This guide installs the hosted `skills-vote` skill. For local or private skill libraries, use [`INSTALL_LOCAL.md`](INSTALL_LOCAL.md) to install `skills-vote-local`.
+
+## Goal
+
+Install `skills-vote` into the current agent's **global** skill directory by default. If the current request explicitly asks for workspace or current-project installation, use that scope instead. Then write `SKILLS_VOTE_API_KEY` and, when available, one usable GitHub token into the installed skill root.
+
+This guide assumes the current request or conversation provides these runtime inputs:
+- the current agent
+- the API key value to write into `.env`
+- optionally, a usable GitHub token if one is already available or explicitly provided
+
+## Installation scope
+
+Support both installation scopes:
+- **Global**: default choice
+- **Workspace / current project**: use only when the current request explicitly asks for it
+
+Do not ask about scope unless the user gives conflicting or ambiguous scope instructions.
+
+## Common `<current-agent>` values
+
+Use the value in the right column for `-a <current-agent>`. These are `npx skills` agent identifiers, not generic product labels.
+
+| Agent | `<current-agent>` |
+| --- | --- |
+| Codex | `codex` |
+| Claude Code | `claude-code` |
+| OpenClaw | `openclaw` |
+| Cursor | `cursor` |
+| Gemini CLI | `gemini-cli` |
+| OpenCode | `opencode` |
+| Cline | `cline` |
+| GitHub Copilot CLI | `github-copilot` |
+| Continue | `continue` |
+| Windsurf | `windsurf` |
+| OpenHands | `openhands` |
+| Pi | `pi` |
+
+If the current agent is not listed here, do not infer a new identifier from the product name. Ask the user for the correct `npx skills` agent identifier, or use a verified value supplied by the current runtime.
+
+## Required flow
+
+1. Determine the current agent and set `<current-agent>` accordingly. If you cannot determine the current agent reliably, stop and ask instead of guessing.
+2. Determine the installation scope:
+   - **Global (default):**
+
+   ```bash
+   npx skills add MemTensor/skills-vote -g -a <current-agent> -s skills-vote -y
+   ```
+
+   - **Workspace / current project** — use only when explicitly requested:
+
+   ```bash
+   npx skills add MemTensor/skills-vote -a <current-agent> -s skills-vote -y
+   ```
+
+3. Resolve the real installed path with the matching scope. Do **not** guess it:
+
+   - **Global:**
+
+   ```bash
+   npx skills list -g -a <current-agent> --json
+   ```
+
+   - **Workspace / current project:**
+
+   ```bash
+   npx skills list -a <current-agent> --json
+   ```
+
+4. Read the returned JSON and find the `path` for `skills-vote`. Treat that path as the skill root. If no valid `path` is returned for `skills-vote`, stop and report the failure instead of guessing.
+5. Create or update `<path>/.env` and set `SKILLS_VOTE_API_KEY` to the API key value provided in the current request or prompt. Do not write the literal string `YOUR_API_KEY`.
+6. GitHub token handling is optional:
+   - If a usable `GH_TOKEN` or `GITHUB_TOKEN` is already available or explicitly provided, you may write one of them into `<path>/.env`.
+   - If the GitHub token is empty, missing, or not usable, tell the user that downloading skills may hit a GitHub rate limit and ask whether they want to provide a usable token.
+   - If no usable GitHub token is ultimately provided, do **not** set `GH_TOKEN` or `GITHUB_TOKEN` in the `.env` file.
+
+```env
+SKILLS_VOTE_API_KEY="<provided-api-key>"
+GITHUB_TOKEN="<usable-github-token>"
+```
+
+## Rules
+
+- Do **not** install into the current project or workspace unless explicitly requested.
+- Do **not** configure `SKILLS_VOTE_API_KEY` as a system-level or user-level environment variable unless explicitly requested.
+- Do **not** hardcode the install path. Always use the path returned by `npx skills list ... --json`.
+- If the current request does not provide a usable API key value, stop and ask the user to provide one or obtain one from `https://skills.vote`. Do not invent an API key.