Skill System¶

Per-agent and global skill storage with cross-tool sync between Sygen and external CLI skill homes (Claude Code, Codex, Gemini).

Files¶

workspace/skill_sync.py: discovery, canonical selection, sync, cleanup, watcher
workspace/init.py: startup one-shot sync calls
workspace/paths.py: skills_dir (per-agent) and global_skills_dir (shared) properties
orchestrator/observers.py: starts/stops background skill-sync watcher
api/rest_routes.py: merged REST listing with scope filter

Scopes¶

Skills live in two scopes:

Global skills (shared across all agents)¶

~/.sygen/skills/<name>/

Every agent — main and sub-agents — sees global skills automatically. The path is resolved via SygenPaths.global_skills_dir: for the main agent it is <sygen_home>/skills; for a sub-agent the property walks up from <sygen_home>/agents/<name> and returns the same ~/.sygen/skills/ dir.

Use this scope for general-purpose skills (e.g. skill-creator) that should be available to every agent.

Per-agent skills (private to one agent)¶

~/.sygen/workspace/skills/<name>/                  # main agent
~/.sygen/agents/<name>/workspace/skills/<name>/    # sub-agent

Per-agent skills are visible only to the agent that owns them. Use this scope for specialized skills that belong to a single role (e.g. implement-watchface for prism).

A per-agent skill with the same name as a global skill overrides the global one for that agent only.

Cross-CLI sync¶

Each agent's scopes are mirrored to the external CLI skill homes:

<agent per-agent skills> ─┐
                          ├─> ~/.claude/skills/
<global skills>           ─┤   ~/.codex/skills/ (or $CODEX_HOME/skills)
                          └─> ~/.gemini/skills/

<agent per-agent skills>:

main: ~/.sygen/workspace/skills/
sub-agent: ~/.sygen/agents/<name>/workspace/skills/

Sync algorithm (`sync_skills`)¶

discover skill dirs in all roots (global, per-agent, each CLI dir)
union names across roots
pick canonical source by priority (sygen > claude > codex > gemini)
mirror canonical to the other roots
cleanup broken managed links

Bundled skills¶

Bundled source: sygen_bot/_home_defaults/workspace/skills/.

sync_bundled_skills(paths) mirrors bundled skills into the agent's global_skills_dir (not the per-agent dir), so every agent sees them.

normal mode: symlinks/junctions
Docker mode: managed copies (.sygen_managed)

Docker-mode behavior¶

When docker_active=True:

uses managed copies instead of links
updates only managed copies
preserves unmanaged user directories

Cleanup on shutdown¶

cleanup_sygen_links(paths) removes managed links under CLI skill dirs whose targets point to the agent's managed roots (both per-agent and global).

REST API¶

Method	Endpoint	Description
`GET`	`/api/agents/{agent}/skills?scope=merged`	Merged view: global + per-agent, with `overrides: true` on per-agent entries that shadow a global
`GET`	`/api/agents/{agent}/skills?scope=own`	Per-agent skills only
`GET`	`/api/agents/{agent}/skills?scope=global`	Global skills only
`POST`	`/api/agents/{agent}/skills`	Create a per-agent skill
`GET`	`/api/agents/{agent}/skills/{skill}`	Read skill body (falls back to global if not in per-agent dir)
`PUT`	`/api/agents/{agent}/skills/{skill}`	Update a per-agent skill
`DELETE`	`/api/agents/{agent}/skills/{skill}`	Delete a per-agent skill

scope defaults to merged. Write operations always target the per-agent directory — globals are read-only from the per-agent API.

Admin UI¶

The /skills page exposes a scope filter (Все / Общие / Только агента) and badges each entry: 🌐 Общий, 👤 Агента, or 🌐 ← 👤 Перекрывает общий.

Safety guarantees¶

unmanaged real directories are preserved
broken links are cleaned
hidden/system dirs are skipped
cross-platform link handling (incl. Windows junction fallback)