@synthryn/sypi-skills
v0.6.0-beta.20260816.6a00fcae
Published
Install, list, and gate Agent Skills across SyPi's user and project roots. Use it when you want reusable instructions or skill-backed commands without mixing project state into the repository. Primary capability: /skills and the host skills loader.
Maintainers
Readme
sypi-skills
Pins host-native skills machinery to two SyPi roots instead of running a parallel loader. /skills manages enabled skills: its interactive picker toggles profile entries and applies them on reload; headless mode prints the same state. enable|disable <name> is the scriptable fast path and persists to the active profile's skills block. The global switch reads global settings only, so a project override cannot re-enable skills the user disabled. Enabled paths are filtered before discovery, while disable-model-invocation stays explicitly invokable through /skill:<name>.
Install / search / update from the board (no hand-dropped files). The bare board carries two always-present action rows beneath the skills, so it is never blank even on first run: install a skill (enter) asks for a GitHub source (owner/repo, a full URL, or an owner/repo/tree/<ref>/<subpath>) or a local path, and search skills (enter) searches the public skills.sh registry first, showing each skill's install count, then falls back to GitHub when the registry is unavailable or has no results. Pick a result to install its GitHub source. u over a skill re-installs (updates) it from the origin remembered at install time, asking again only when none is known. Importing honours the agent-skills standard — a SKILL.md with YAML frontmatter — via SyPi's own loadSkillsFromDir, so it discovers a lone skill dir or a whole .claude/skills/ tree in one go, then copies the skill dirs into the user root ~/.sypi/skills/; an installed skill toggles through the same skills gate as any other. Security: skills can be malicious. Only install them from sources you trust, review the files before enabling them, and remember that an install count is not a safety guarantee. Imported content is untrusted — the exact skills and target paths are shown in a confirm before anything is written (the confirm is the trust gate), nothing from a skill is ever executed (git/gh run against the URL, not file contents), and the copy is regular-files-only (symlinks skipped), name-sanitized against traversal, and size-capped.
Dual-root discovery (kept, by decision) — project root trust-gated. Skills come from exactly two sypi roots: the user root ~/.sypi/skills/<skill>/SKILL.md and the pre-existing project override .sypi/skills/<skill>/SKILL.md, with the project override winning name collisions. Both roots are retained on purpose — the user root holds machine-wide skills; the explicit in-repo .sypi/ override lets a project ship or shadow a skill. The project root only counts while ctx.isProjectTrusted — in an untrusted clone its skills are never read, listed, prompted, or expanded (the /skills listing says so), so a repo cannot inject a skill through the sypi override path without consent. Nothing else is a sypi skill root. SyPi's native validation now applies: a description is required, and a missing name falls back to the folder name.
Isolation (security) — still enforced, now around the native pipeline. Host-native discovery can find .agents/skills/ in a trusted project, so pointing skillPaths at sypi roots is additive rather than sufficient. Three hooks close those surfaces: (1) before_agent_start rebuilds <available_skills> with enabled sypi-root skills only and caches descriptions after first send; (2) input expands /skill:<name> from a verified sypi file and directs all other skill commands to /skills; (3) context strips expanded skill blocks whose locations are outside sypi roots before a provider request. The native TUI can still autocomplete discovered skills and a steer/follow-up expansion can briefly reach stored session state, but its body never reaches a provider.
Normal prompts may reference exactly one enabled skill as $skill-name; SyPi routes that prompt through the same verified /skill:<name> expansion. In the TUI, typing $ offers matching loaded skills through the existing autocomplete provider. Unknown aliases, multiple distinct aliases, slash commands, and extension-generated input remain unchanged.
