skills.*

skills.* is the runtime surface over the in-process SkillSystem (the unified SkillSystem v2 registry). Six methods are wired in HandlerRegistry::new() — five real, one plumbing — and the runtime is lazily initialised on the first call. bundled.sync is the explicit refresh trigger for bundled content (skills, plugins); it is registered in the same place.

The markdown_skills.* family is not registered as JSON-RPC. skills.install is the runtime install path; it accepts a git URL / local path / zip, security-scans the bundle, and registers each tool through the shared AlephToolServer.

Methods

skills.status

Return every registered skill — its enabled state, scope, source path, and per-skill dependency list.

Request: no params.

Response: { "skills": [ ...SkillStatus... ] }. Each row carries id, name, enabled, scope (system / tool / standalone / disabled), version, dependencies, plus any per-skill metadata the system surfaces.

skills.update

Update a skill's enabled state and/or prompt scope. Unknown scope values are rejected with INVALID_PARAMS.

Parameter	Type	Required	Description
`skill_id`	string	yes	Skill id (`<source>:<name>`)
`enabled`	boolean	no	`true` / `false`
`scope`	string	no	`system` / `tool` / `standalone` / `disabled`

Response: { "skill": { ...updated SkillStatus... } } on success; INTERNAL_ERROR if the skill cannot be found after the update.

skills.install_dep

Install a skill's dependency (a system package or similar — the dependency descriptor is skill-defined).

Parameter	Type	Required	Description
`skill_id`	string	yes	Skill id
`spec_id`	string	no	Dependency spec id (defaults are skill-defined)

Response: { "result", "skill" | null }. result is the dependency's own Result string.

skills.remove

Remove a skill from the registry. Idempotent: an unknown skill_id returns { "ok": false } (not a JSON-RPC error) so the Settings page can render an idempotent delete UX.

Parameter	Type	Required	Description
`skill_id`	string	yes	Skill id

Response: { "ok": <bool> }.

skills.install

Install a skill bundle from a Git URL, a local path, or a .zip archive. The source is detected server-side by URL/path suffix; the bundle is security-scanned (scan_skill_directory / install_allowed at TrustLevel::Community) and only loaded when the scan passes — a reverse-shell payload alongside a valid SKILL.md is rejected and the directory is removed.

The AgentRevision revision counter is bumped on every successful install so the agent loop's MarkdownSkillRefreshSource can detect changes cheaply.

Parameter	Type	Required	Description
`url`	string	yes	Git URL (`https://…`, `git@…`, or `.git` suffix), local path, or `https://…/*.zip`
`flatten`	boolean	no	Git-only; clone into a hidden cache and copy the contents flat into `~/.aleph/skills/`

Response: { "skills": [ ...MarkdownSkillInfo... ], "count": N }. MarkdownSkillInfo carries name, description, source_path, sandbox_mode (host / docker / virtualfs), requires_bins.

bundled.sync

Explicitly refresh bundled content (skills, plugins, or both) from the external repos. Reserved for explicit triggers (CLI / LLM tool / Hub button); the startup path never auto-pulls. The default kind is all.

Parameter	Type	Required	Description
`kind`	string	no	`skills` / `plugins` / `all` (default)

Response: { "ok": true, "skills", "plugins" } — counts of newly-extracted rows per kind.

Skill directories

The runtime loads skills from, in order of precedence:

~/.aleph/skills/ — user-installed skills
./skills/ — project-local skills
Bundled skills shipped with Aleph

The bundled set is extracted by bundled.sync into the user directory, so the agent loop sees a unified view across all three layers.

Plugin-bundled skills

Since 26.7.17, skills that are installed via a plugin are folded into the skill index and surface in skill_read. The two namespaces share a single ToolCatalog registry, so the same skill id resolves to a tool whether the agent loop discovered it from a plugin's commands/ markdown or from a top-level ~/.aleph/skills/ install.