diff --git a/README.md b/README.md index c312369..e3fba25 100644 --- a/README.md +++ b/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: diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000..3c18cec --- /dev/null +++ b/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 `` values + +Use the value in the right column for `-a `. These are `npx skills` agent identifiers, not generic product labels. + +| 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 `` 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 -s skills-vote -y + ``` + + - **Workspace / current project** — use only when explicitly requested: + + ```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 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="" +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. 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.