From 9d494a5ed4b1fa6efd4d4801587ace1b1817424e Mon Sep 17 00:00:00 2001 From: shiuing Date: Thu, 9 Apr 2026 16:52:34 +0800 Subject: [PATCH 1/3] feat: add agentic install instruction --- docs/INSTALL.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/INSTALL.md diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000..6788831 --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,62 @@ +# Install SkillsVote + +Use this guide when asked to install the `skills-vote` skill for the current agent. + +## Goal + +Install `skills-vote` into the current agent's **global** skill directory, not the current project or workspace. Then write `SKILLS_VOTE_API_KEY` only into the installed skill root. + +This guide assumes the current request provides two runtime inputs: +- the current agent +- the API key value to write into `.env` + +## Common `` values + +Use the value in the right column for `-a `. + +| Agent | `` | +| --- | --- | +| Codex | `codex` | +| Claude Code | `claude-code` | +| OpenClaw | `openclaw` | +| Cursor | `cursor` | +| Gemini CLI | `gemini-cli` | +| OpenCode | `opencode` | +| Cline | `cline` | +| GitHub Copilot | `github-copilot` | +| Continue | `continue` | +| Windsurf | `windsurf` | +| OpenHands | `openhands` | +| Pi | `pi` | + +If the current agent is not listed here, use the exact agent value accepted by `npx skills add -a ...`. + +## Required flow + +1. Determine the current agent and set `` accordingly. If you cannot determine the current agent reliably, stop and ask instead of guessing. +2. Install the skill globally: + +```bash +npx skills add MemTensor/skills-vote -g -a -s skills-vote -y +``` + +3. Resolve the real installed path. Do **not** guess it: + +```bash +npx skills list -g -a --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 `/.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`. + +```env +SKILLS_VOTE_API_KEY="" +``` + +## 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 your owner to provide one or obtain one from `https://skills.vote`. Do not invent an API key. + From 1c3a9f932b8f22c703addd0e880c9593bc12cf4f Mon Sep 17 00:00:00 2001 From: shiuing Date: Thu, 9 Apr 2026 17:38:08 +0800 Subject: [PATCH 2/3] fix: update install instruction --- README.md | 7 +++--- docs/INSTALL.md | 58 ++++++++++++++++++++++++++++++++++++------------- 2 files changed, 47 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index c312369..d76663a 100644 --- a/README.md +++ b/README.md @@ -74,10 +74,11 @@ For a detailed breakdown of the quality and verifiability criteria used in our e 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 diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 6788831..b721ac8 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -4,15 +4,24 @@ Use this guide when asked to install the `skills-vote` skill for the current age ## Goal -Install `skills-vote` into the current agent's **global** skill directory, not the current project or workspace. Then write `SKILLS_VOTE_API_KEY` only into the installed skill root. +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 optionally a usable GH_TOKEN or GITHUB_TOKEN only into the installed skill root. -This guide assumes the current request provides two runtime inputs: +This guide assumes the current request 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 + +If the intended scope is unclear, stop and ask instead of guessing. ## Common `` values -Use the value in the right column for `-a `. +Use the value in the right column for `-a `. These are `npx skills` agent identifiers, not generic product labels. | Agent | `` | | --- | --- | @@ -23,34 +32,54 @@ Use the value in the right column for `-a `. | Gemini CLI | `gemini-cli` | | OpenCode | `opencode` | | Cline | `cline` | -| GitHub Copilot | `github-copilot` | +| GitHub Copilot CLI | `github-copilot` | | Continue | `continue` | | Windsurf | `windsurf` | | OpenHands | `openhands` | | Pi | `pi` | -If the current agent is not listed here, use the exact agent value accepted by `npx skills add -a ...`. +If the current agent is not listed here, use the exact agent value accepted by `npx skills add -a ...`. If you are unsure, check `npx skills add --help` instead of guessing. ## Required flow 1. Determine the current agent and set `` accordingly. If you cannot determine the current agent reliably, stop and ask instead of guessing. -2. Install the skill globally: +2. Determine the installation scope: + - **Global (default):** -```bash -npx skills add MemTensor/skills-vote -g -a -s skills-vote -y -``` + ```bash + npx skills add MemTensor/skills-vote -g -a -s skills-vote -y + ``` -3. Resolve the real installed path. Do **not** guess it: + - **Workspace / current project** — use only when explicitly requested: -```bash -npx skills list -g -a --json -``` + ```bash + npx skills add MemTensor/skills-vote -a -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 --json + ``` + + - **Workspace / current project:** + + ```bash + npx skills list -a --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 `/.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 `/.env`. + - If the GitHub token is empty, missing, or unable to use, warn your owner that downloading skills may hit a GitHub rate limit and ask for 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="" +GITHUB_TOKEN="" ``` ## Rules @@ -58,5 +87,4 @@ SKILLS_VOTE_API_KEY="" - 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 your owner to provide one or obtain one from `https://skills.vote`. Do not invent an API key. - +- If the current request does not provide a usable API key value, stop and ask your owner to provide one or obtain one from `https://skills.vote`. Do not invent an API key. \ No newline at end of file From 1723f880de679f0a740f03e6abe07e07ebb52096 Mon Sep 17 00:00:00 2001 From: shiuing Date: Mon, 18 May 2026 16:20:06 +0800 Subject: [PATCH 3/3] feat:add skills-vote-local install insctruction --- README.md | 29 +++- docs/INSTALL.md | 14 +- docs/INSTALL_LOCAL.md | 308 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 343 insertions(+), 8 deletions(-) create mode 100644 docs/INSTALL_LOCAL.md diff --git a/README.md b/README.md index d76663a..e3fba25 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,14 @@ 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 @@ -103,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: diff --git a/docs/INSTALL.md b/docs/INSTALL.md index b721ac8..3c18cec 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -2,11 +2,13 @@ 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 optionally a usable GH_TOKEN or GITHUB_TOKEN only into the installed skill root. +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 provides these runtime inputs: +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 @@ -17,7 +19,7 @@ Support both installation scopes: - **Global**: default choice - **Workspace / current project**: use only when the current request explicitly asks for it -If the intended scope is unclear, stop and ask instead of guessing. +Do not ask about scope unless the user gives conflicting or ambiguous scope instructions. ## Common `` values @@ -38,7 +40,7 @@ Use the value in the right column for `-a `. These are `npx skill | OpenHands | `openhands` | | Pi | `pi` | -If the current agent is not listed here, use the exact agent value accepted by `npx skills add -a ...`. If you are unsure, check `npx skills add --help` instead of guessing. +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 @@ -74,7 +76,7 @@ If the current agent is not listed here, use the exact agent value accepted by ` 5. Create or update `/.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 `/.env`. - - If the GitHub token is empty, missing, or unable to use, warn your owner that downloading skills may hit a GitHub rate limit and ask for a usable token. + - 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 @@ -87,4 +89,4 @@ GITHUB_TOKEN="" - 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 your owner to provide one or obtain one from `https://skills.vote`. Do not invent an API key. \ No newline at end of file +- 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. diff --git a/docs/INSTALL_LOCAL.md b/docs/INSTALL_LOCAL.md new file mode 100644 index 0000000..2b83c65 --- /dev/null +++ b/docs/INSTALL_LOCAL.md @@ -0,0 +1,308 @@ +# Install SkillsVote Local + +Use this guide when asked to install the `skills-vote-local` skill for the current agent. + +## Goal + +Install `skills-vote-local` into the current agent's skill directory, then help the user configure which local skill libraries it should search. + +`skills-vote-local` is different from `skills-vote`: + +- `skills-vote` calls the hosted SkillsVote service. +- `skills-vote-local` searches local or private skill directories on the user's machine. + +Do not stop after installation. The important part of this guide is the post-install configuration step. + +## Installation Scope + +Install globally by default. If the current request explicitly asks for workspace or current-project installation, use that scope instead. + +Do not ask about scope unless the user gives conflicting or ambiguous scope instructions. + +## Common `` Values + +Use the value in the right column for `-a `. These are `npx skills` agent identifiers. + +| 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 ``. If you cannot determine the current agent reliably, ask the user instead of guessing. +2. Record the original working directory before changing directories: + + ```bash + ORIGINAL_WORKDIR="$PWD" + ``` + +3. Determine the installation scope. +4. Install the skill: + + - Global: + + ```bash + npx skills add MemTensor/skills-vote -g -a -s skills-vote-local -y + ``` + + - Workspace / current project: + + ```bash + npx skills add MemTensor/skills-vote -a -s skills-vote-local -y + ``` + +5. Resolve the real installed path with the matching scope. Do not guess it: + + - Global: + + ```bash + npx skills list -g -a --json + ``` + + - Workspace / current project: + + ```bash + npx skills list -a --json + ``` + +6. Read the returned JSON and find the `path` for `skills-vote-local`. Treat that path as the skill root. If no valid `path` is returned, report the failure instead of guessing. +7. `cd` to the installed skill root. +8. Create `config/config.yaml` from `config/config.yaml.example` if it does not already exist. +9. Discover likely local skill libraries from `ORIGINAL_WORKDIR` and common user-level paths, then ask the user which ones to include. +10. Ask the user which retrieval method to use: `agentic_search` or `vector_search`. +11. Update `config/config.yaml`. +12. Run the skill's own environment check: + +```bash +uv run -qq scripts/check_env.py +``` + +## Configure Local Skill Libraries + +After installation, inspect likely local skill locations and ask the user which ones should be included. + +Search only directories that commonly contain agent skills. Do not crawl the whole filesystem. + +Recommended candidate locations: + +- the original working directory and its common subdirectories: + - `.codex/skills` + - `.claude/skills` + - `.agents/skills` + - `.skills` + - `skills` + - `integration/skills` + - `runtime_test/skills` + - `runtime_test/skills-main/skills` +- common user-level skill directories: + - `~/.codex/skills` + - `~/.claude/skills` + - `~/.config/skills` + - `~/.local/share/skills` + - `~/.agents/skills` + +Use a bounded scan such as: + +```bash +python3 - <<'PY' +import os +from pathlib import Path + +original = Path(os.environ.get("ORIGINAL_WORKDIR", Path.cwd())).expanduser().resolve() +roots = [ + original if (original / "SKILL.md").is_file() else None, + original / ".codex" / "skills", + original / ".claude" / "skills", + original / ".agents" / "skills", + original / ".skills", + original / "skills", + original / "integration" / "skills", + original / "runtime_test" / "skills", + original / "runtime_test" / "skills-main" / "skills", + Path.home() / ".codex" / "skills", + Path.home() / ".claude" / "skills", + Path.home() / ".agents" / "skills", + Path.home() / ".config" / "skills", + Path.home() / ".local" / "share" / "skills", +] +prune_names = { + ".git", + ".hg", + ".svn", + ".skills", + ".skills_vote", + ".venv", + "__pycache__", + "node_modules", +} +max_depth = 6 +seen_roots = set() + +for root in roots: + if root is None: + continue + root = root.expanduser().resolve() + if root in seen_roots or not root.exists() or not root.is_dir(): + continue + seen_roots.add(root) + count = 0 + stack = [(root, 0)] + while stack: + current, depth = stack.pop() + if current.name in prune_names: + continue + skill_md = current / "SKILL.md" + if skill_md.is_file(): + count += 1 + if depth >= max_depth: + continue + try: + children = list(current.iterdir()) + except OSError: + continue + stack.extend((child, depth + 1) for child in children if child.is_dir()) + if count: + print(f"{root}\t{count}") +PY +``` + +Then summarize the likely skill library roots and ask which should be included. A skill library root is usually the directory that contains many skill subdirectories, not each individual skill directory. + +Ask a concrete question before writing the config: + +```text +I found these likely local skill-library roots: +1. ( SKILL.md files) +2. ( SKILL.md files) + +Which of these should `skills-vote-local` search? You can choose one, several, or none, and you can add another path. +``` + +The user may choose one path, many paths, or none. Do not include a directory without user confirmation. + +Write the confirmed roots as `SKILL.md` glob patterns: + +```yaml +skill_library: + include: + - "/absolute/path/to/confirmed-skill-library/**/SKILL.md" + exclude: [] +``` + +Prefer absolute paths in `config/config.yaml` so the skill works from any current working directory. + +## Choose Retrieval Method + +Ask the user which retrieval method they want before writing `retrieval.method`: + +```text +Which retrieval method should `skills-vote-local` use? + +1. `agentic_search` (recommended): no embedding API key; searches the synced local skill namespace with filesystem search. +2. `vector_search`: semantic search with Chroma; requires an embedding provider, model, dimensions, base URL, and API key or API-key environment variable. +``` + +### Option A: `agentic_search` + +Recommended default for first setup. + +This method searches the confirmed local skills with filesystem tools and does not require an embedding API key. + +```yaml +retrieval: + method: agentic_search +``` + +Use this when: + +- the user wants the simplest local setup; +- the skill library is small or medium-sized; +- no embedding provider is available yet; +- local inspection is more important than vector recall. + +### Option B: `vector_search` + +Use this when the user wants semantic vector retrieval over a larger local library. + +`vector_search` requires embedding configuration. Ask the user for: + +- embedding provider or OpenAI-compatible base URL; +- embedding model; +- embedding dimensions; +- API key or API-key environment variable; +- whether the vector index should be built now. + +Example OpenAI-compatible configuration: + +```yaml +retrieval: + method: vector_search + +embedding: + provider: openai-compatible + model: bge-m3 + dimensions: 1024 + api_key_env: OPENAI_API_KEY + api_key: "" + base_url: "https://api.openai.com/v1" + extra_headers: {} +``` + +Do not write fake API keys such as `sk-xx`. If the user wants to use an environment variable, leave `api_key` empty and set `api_key_env`. + +If the user chooses `vector_search` but has no embedding key or endpoint ready, ask whether to configure the embedding settings now or use `agentic_search` for the first setup. + +## Minimal Example Config + +This is a good first configuration after the user confirms the local skill directories: + +```yaml +skill_library: + include: + - "/absolute/path/to/skills/**/SKILL.md" + exclude: + - "**/.git/**" + - "**/.hg/**" + - "**/.svn/**" + - "**/.skills/**" + - "**/.venv/**" + - "**/venv/**" + - "**/node_modules/**" + - "**/__pycache__/**" + - "**/.pytest_cache/**" + - "**/.mypy_cache/**" + - "**/.ruff_cache/**" + - "**/dist/**" + - "**/build/**" + +retrieval: + method: agentic_search + +routing: + mode: subagent_multi_pass + max_passes: 3 +``` + +## Rules + +- Do not install `skills-vote-local` when the user asked for the hosted `skills-vote` service. +- Do not configure cloud API keys for `skills-vote-local` unless the user chooses `vector_search`. +- Do not invent local skill paths. +- Do not include directories before the user confirms them. +- Do not write placeholder values such as `/path/to/your-skill-library/` into the final config. +- Do not write fake API keys. +- Do not write legacy retrieval method names such as `agentic_grep` or `vector`. +- Prefer `agentic_search` as the safe default when the user is unsure.