Skill Deployer

Skill Deployer

Install a validated custom skill into user_skills/ (global) or .libragent/skills/ (workspace) so agents load it on the next turn.

Prerequisite: Run skill-creator validation first: python <skill-creator-base-dir>/scripts/validate_skill.py <skill-folder> --strict

This skill covers where and how to install user/workspace skills. It does not cover authoring — use skill-creator. It does not ship skills with the app — that is a developer/repo workflow (see Bundled scope below).

What This Skill Is NOT

Never deploy custom skills to {dataDir}/system_skills/. That folder is a managed mirror of packaged bundled skills. Manual additions are deleted on app startup. Do not create or edit .bundled_manifest.json outside bundled sync — it does not register custom skills.

If the user says "system skill" or points at system_skills, they usually mean global availability. Deploy to user_skills/, not system_skills/.

Scope Decision

Default to workspace when unsure — safest and easiest to remove.

Target Paths

Workspace scope (most common)

{workspace-root}/.libragent/skills/{skill-name}/SKILL.md

Read Workspace Root from the system prompt (## Workspace section).

Example: C:/Users/alice/AppData/Roaming/com.fritzprix.libragent/workspaces/<session-id>/.libragent/skills/my-skill/SKILL.md

NOT {workspace-root}/{skill-name}/ — skills at the session root are never scanned.

Global scope (user skills)

{dataDir}/user_skills/{skill-name}/SKILL.md

Resolve {dataDir} from <available_skills>:

1. Find a skill with source="global" whose <location> contains user_skills (not system_skills).
2. Take the parent of user_skills/ as {dataDir}.
3. If none exist, use OS defaults:

Example: C:\Users\alice\AppData\Roaming\com.fritzprix.libragent\user_skills\my-skill\SKILL.md

NOT {dataDir}/system_skills/ (bundled mirror), {dataDir}/skills/ (legacy), or %APPDATA%\LibrAgent\skills\ (old app ID path).

Assistant scope

{dataDir}/assistants/{assistant-id}/skills/{skill-name}/SKILL.md

The user must provide the assistant ID from the Assistants settings panel.

Agent import scope (IDE / local dev)

Auto-discovered under the workspace root:

• .agents/skills/, .cursor/skills/, .gemini/skills/, .copilot/skills/
• .windsurf/skills/, .claude/skills/, .cline/skills/, .continue/skills/

{workspace-root}/.cursor/skills/{skill-name}/SKILL.md

Bundled scope — do NOT use this skill

Repo path only; managed by app build mirror and startup sync (not user-deployable):

src-tauri/bundled_skills/{skill-name}/

Runtime mirror (read-only for agents; never write custom skills here):

{dataDir}/system_skills/{skill-name}/

Forbidden Locations

Deployment Procedure

Prefer deploy_skill.py over manual file writes. It always runs strict validation before and after copy, blocks forbidden targets, rolls back on post-deploy failure, and prints error codes with fix instructions.

python <skill-deployer-base-dir>/scripts/deploy_skill.py <skill-source-dir> --scope global
python <skill-deployer-base-dir>/scripts/deploy_skill.py <skill-source-dir> --scope workspace --workspace "<workspace-root>"
python <skill-deployer-base-dir>/scripts/deploy_skill.py <skill-source-dir> --scope assistant --assistant-id "<id>"

Validation phases (all strict):

1. Pre-deploy (source) — frontmatter, folder name match, forbidden files, bad source path
2. Post-deploy (target) — same checks on the copied skill; rollback if this fails

Inspect failures manually:

python <skill-creator-base-dir>/scripts/validate_skill.py <skill-folder> --strict --detailed

Each issue prints [CODE], message, and Fix: line (e.g. SKILL-YAML-APOSTROPHE, SKILL-PATH-WORKSPACE-ROOT).

Manual fallback (only if the script cannot run)

Step 1 — Validate (skill-creator)

python <skill-creator-base-dir>/scripts/validate_skill.py <skill-folder> --strict

Do not deploy if validation fails. Fix path/YAML issues before writing files.

Step 2 — Pick scope and target path

Use the scope table above. Construct the full directory:

{target-dir}/{skill-name}/SKILL.md
{target-dir}/{skill-name}/scripts/...
{target-dir}/{skill-name}/references/...

Checklist before writing:

• Target is user_skills/ or .libragent/skills/ (or assistant/agent import path)
• Target is not system_skills/
• Folder name matches frontmatter name:

Step 3 — Write files

Use workspace tools (createFile, etc.) with forward slashes even on Windows.

Copy the entire skill directory tree — not just SKILL.md — when scripts or references exist.

Step 4 — Verify discovery

On the next agent turn, check <available_skills> in the system prompt:

<skill source="global">
  <name>my-new-skill</name>
  <description>...</description>
  <location>.../user_skills/my-new-skill/SKILL.md</location>
</skill>

Confirm:

1. Skill name appears
2. source matches intended scope (workspace, assistant, or global)
3. <location> matches the path you wrote (user_skills for global, not system_skills)

Re-run validate_skill.py --strict on the deployed copy if discovery fails.

Step 5 — Report

Tell the user:

• Full path written
• Scope chosen
• Skill name as it appears in <available_skills>
• That it becomes active on the next agent message

Coalesce Behavior

Skills merge with first-wins by lowercase name. Priority: workspace > assistant > agent import > global > system.

A workspace skill silently overrides a global skill with the same name.

Common Mistakes

• Deploying to system_skills/ — use user_skills/ for global custom skills; ship app-bundled skills via src-tauri/bundled_skills/ in the repo
• Confusing system_skills with global — global user skills live in user_skills/
• Creating .bundled_manifest.json — only bundled sync uses this; it does not register custom skills elsewhere
• Hash-checking against bundled manifest — irrelevant for custom skills; discovery uses directory scan + valid SKILL.md
• Skipping validation — invalid YAML is silently ignored by the Rust scanner
• Workspace root deploy — must be .libragent/skills/{name}/, not {workspace}/{name}/
• Wrong global path — use com.fritzprix.libragent\user_skills\, not legacy LibrAgent\skills\
• Apostrophe in YAML — fix in skill-creator ("it's" not 'it's')
• Name ≠ folder name — breaks @skill:name lookup
• Expecting immediate UI refresh — skills reload at the start of the next agent turn