fix(skills): make find-skills installer failures actionable (#8393)

* fix(skills): make find-skills installer failures actionable

* fix(skills): clarify installer guidance and harden tests

* docs(skills): correct installer usage header
This commit is contained in:
Zeren Wang 2026-11-19 23:27:56 +01:00 committed by GitHub
parent 50d04ddf71
commit a96c9c0318
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 144 additions and 16 deletions

View File

@ -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 <owner/repo@skill-name>
bash skills/public/find-skills/scripts/install-skill.sh <owner/repo@skill-name>
```
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 <skill-directory> <output-directory>` 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

View File

@ -1,8 +1,8 @@
#!/bin/bash
# Install a skill and link it to the project's skills/custom directory
# Usage: ./skills/install-skill.sh <owner/repo@skill-name>
# Example: ./skills/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices
# Usage: bash skills/public/find-skills/scripts/install-skill.sh <owner/repo@skill-name>
# 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

View File

@ -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()