diff --git a/skills/public/find-skills/SKILL.md b/skills/public/find-skills/SKILL.md index 0b3c85577a..2de44e6838 100644 --- a/skills/public/find-skills/SKILL.md +++ b/skills/public/find-skills/SKILL.md @@ -68,7 +68,7 @@ vercel-labs/agent-skills@vercel-react-best-practices When you find relevant skills, present them to the user with: 1. The skill name and what it does -2. The install command they can run +2. The installation action for their current environment (see Step 4) 3. A link to learn more at skills.sh Example response: @@ -77,27 +77,31 @@ Example response: I found a skill that might help! The "vercel-react-best-practices" skill provides React and Next.js performance optimization guidelines from Vercel Engineering. -To install it: -bash /path/to/skill/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices +To install it in a host DeerFlow checkout, run this command from the repository root: +bash skills/public/find-skills/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices + +In a DeerFlow sandbox or Web session, use the administrator .skill import flow described in Step 4. Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices ``` ### Step 4: Install the Skill -If the user wants to proceed, use the `install-skill.sh` script to install the skill and automatically link it to the project: +Choose the installation path for the current environment. + +**Inside a host DeerFlow checkout**, run [install-skill.sh](scripts/install-skill.sh) from the repository root. It installs the skill under `$HOME/.agents/skills/` and links it into that checkout's `skills/custom/` directory: ```bash -bash /path/to/skill/scripts/install-skill.sh +bash skills/public/find-skills/scripts/install-skill.sh ``` -For example, if the user wants to install `vercel-react-best-practices`: +For example: ```bash -bash /path/to/skill/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices +bash skills/public/find-skills/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices ``` -The script will install the skill globally to `skills/custom/` +**Inside an isolated DeerFlow sandbox or Web session**, do not run this helper. The host checkout and its writable `skills/custom/` directory are unavailable, and `/mnt/skills` is a read-only projection. Instead, provide the skill as a `.skill` archive and ask an administrator to install it through **Capability Center → Skills → My skills → Install .skill**. If the source does not provide an archive, package the downloaded skill directory first with `python /mnt/skills/public/skill-creator/scripts/package_skill.py ` or an equivalent ZIP tool. Installation uses the administrator's per-user skill storage and makes the skill available through the normal skill projection. Do not copy skill files into `/mnt/skills` or claim that writing files into the thread workspace installs a skill. ## Common Skill Categories diff --git a/skills/public/find-skills/scripts/install-skill.sh b/skills/public/find-skills/scripts/install-skill.sh index b02255994f..d17c10f267 100755 --- a/skills/public/find-skills/scripts/install-skill.sh +++ b/skills/public/find-skills/scripts/install-skill.sh @@ -1,8 +1,8 @@ #!/bin/bash # Install a skill and link it to the project's skills/custom directory -# Usage: ./skills/install-skill.sh -# Example: ./skills/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices +# Usage: bash skills/public/find-skills/scripts/install-skill.sh +# Example: bash skills/public/find-skills/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices set -e @@ -36,18 +36,26 @@ find_project_root() { return 1 } -PROJECT_ROOT=$(find_project_root) - -if [[ -z "$PROJECT_ROOT" ]]; then - echo "Error: Could not find project root (deer-flow.code-workspace not found)" +if ! PROJECT_ROOT="$(find_project_root)"; then + printf '%s\n' \ + 'Error: Could not find a DeerFlow checkout (deer-flow.code-workspace not found).' \ + "This installer only links skills into a checkout's skills/custom directory." \ + 'In a sandbox or Web session, ask an administrator to install a .skill archive through Capability Center → Skills → My skills → Install .skill.' >&2 exit 1 fi SKILL_SOURCE="$HOME/.agents/skills/$SKILL_NAME" SKILL_TARGET="$PROJECT_ROOT/skills/custom" -# Step 1: Install the skill using npx -npx skills add "$FULL_SKILL_NAME" -g -y > /dev/null 2>&1 +# Step 1: Install the skill using npx. Preserve the original quiet success path, +# but return the command's status and output when installation fails. +if NPX_OUTPUT="$(npx skills add "$FULL_SKILL_NAME" -g -y 2>&1)"; then + : +else + NPX_STATUS=$? + printf 'Error: npx skills add failed for %s (exit %d).\n%s\n' "$FULL_SKILL_NAME" "$NPX_STATUS" "$NPX_OUTPUT" >&2 + exit "$NPX_STATUS" +fi # Step 2: Verify installation if [[ ! -d "$SKILL_SOURCE" ]]; then diff --git a/tests/skills/test_find_skills_install.py b/tests/skills/test_find_skills_install.py new file mode 100644 index 0000000000..adc9f13b73 --- /dev/null +++ b/tests/skills/test_find_skills_install.py @@ -0,0 +1,116 @@ +"""Offline regressions for the find-skills host-checkout installer.""" + +import os +import subprocess +from pathlib import Path + +import pytest + +INSTALLER = ( + Path(__file__).resolve().parents[2] + / "skills/public/find-skills/scripts/install-skill.sh" +) +SKILL_REFERENCE = "example/repo@example-skill" + +pytestmark = pytest.mark.skipif( + os.name == "nt", reason="The installer and npx test doubles require Bash" +) + + +def _install_fake_npx(tmp_path: Path, body: str) -> Path: + bin_dir = tmp_path / "bin" + bin_dir.mkdir() + executable = bin_dir / "npx" + executable.write_text(f"#!/bin/bash\n{body}\n", encoding="utf-8", newline="\n") + executable.chmod(0o755) + return bin_dir + + +def _run_installer( + cwd: Path, home: Path, bin_dir: Path, log: Path +) -> subprocess.CompletedProcess[str]: + env = { + **os.environ, + "HOME": str(home), + "PATH": f"{bin_dir}{os.pathsep}{os.environ['PATH']}", + "NPX_TEST_LOG": str(log), + } + return subprocess.run( + ["bash", str(INSTALLER), SKILL_REFERENCE], + check=False, + cwd=cwd, + env=env, + capture_output=True, + encoding="utf-8", + timeout=15, + ) + + +def test_missing_checkout_reports_actionable_error_without_calling_npx( + tmp_path: Path, +) -> None: + if any( + (parent / "deer-flow.code-workspace").is_file() + for parent in (tmp_path, *tmp_path.parents) + ): + pytest.skip( + "This regression requires a temporary directory outside a DeerFlow checkout" + ) + workspace = tmp_path / "workspace" + workspace.mkdir() + bin_dir = _install_fake_npx(tmp_path, 'printf called > "$NPX_TEST_LOG"\nexit 99') + log = tmp_path / "npx-called" + + result = _run_installer(tmp_path / "workspace", tmp_path / "home", bin_dir, log) + + assert result.returncode == 1 + assert result.stdout == "" + assert "Could not find a DeerFlow checkout" in result.stderr + assert "skills/custom" in result.stderr + assert "Install .skill" in result.stderr + assert not log.exists() + + +def test_npx_failure_preserves_status_and_output(tmp_path: Path) -> None: + (tmp_path / "deer-flow.code-workspace").touch() + bin_dir = _install_fake_npx( + tmp_path, + 'printf "registry unavailable\\n"\nprintf "upstream timed out\\n" >&2\nexit 23', + ) + + result = _run_installer( + tmp_path, tmp_path / "home", bin_dir, tmp_path / "npx-called" + ) + + assert result.stdout == "" + assert result.stderr.splitlines() == [ + f"Error: npx skills add failed for {SKILL_REFERENCE} (exit 23).", + "registry unavailable", + "upstream timed out", + ] + assert not (tmp_path / "skills/custom/example-skill").exists() + + +def test_successful_install_links_skill_into_checkout(tmp_path: Path) -> None: + (tmp_path / "deer-flow.code-workspace").touch() + bin_dir = _install_fake_npx( + tmp_path, + 'printf "%s\\n" "$@" > "$NPX_TEST_LOG"\nmkdir -p "$HOME/.agents/skills/example-skill"', + ) + home = tmp_path / "home" + log = tmp_path / "npx-args" + + result = _run_installer(tmp_path, home, bin_dir, log) + + assert result.returncode == 0, result.stdout + result.stderr + assert result.stdout.strip() == "Skill 'example-skill' installed successfully" + assert log.read_text(encoding="utf-8").splitlines() == [ + "skills", + "add", + SKILL_REFERENCE, + "-g", + "-y", + ] + link = tmp_path / "skills/custom/example-skill" + assert link.is_symlink() + assert link.resolve() == (home / ".agents/skills/example-skill").resolve()