Use Skills (browse, install, edit)

What it is

A Skill is a small markdown file that teaches Claude Code how to do a specific thing — "ship a package", "write a postmortem", "schedule a cron job". Each skill has YAML frontmatter (name, description) followed by prose instructions. Omniscio ships with an in-app Skills browser that lets you install skills from a curated catalog, edit your own, and keep them up to date — all without hunting around the filesystem or hand-editing files in ~/.claude/skills/. Installed skills activate automatically whenever their trigger phrases match what you're asking (e.g. "schedule a cron" loads the omniscio-control skill bundle's cron.md reference).

Where to find it

Open the Skills view by clicking Skills (puzzle-piece icon) in the left sidebar, where it appears as a virtual project alongside Inbox, Gmail and SMS. If the entry is missing, open Settings → Workflow → Features and confirm Enable Skills integration is on; it ships on by default. The view is a sub-sidebar with Installed and Catalog tabs plus a detail pane showing the selected skill's frontmatter, body and token cost, and it carries the Install, Edit, Update and delete actions.

How it behaves

How to use it

1. Open the Skills view. Click Skills (puzzle-piece icon) in the left sidebar — it appears as a virtual project alongside Inbox, Gmail, SMS, etc. If you don't see it, open Settings → Workflow → Features and confirm Enable Skills integration is on (it ships on by default).
2. Browse Installed vs Catalog. The sub-sidebar has two tabs: Installed (skills already on disk — user-authored plus any bundled by plugins; a plugin contributes exactly the skills its own manifest publishes, whatever folder layout it uses internally, so a plugin that ships extra work-in-progress folders it doesn't publish won't show them — Claude Code wouldn't load those either) and Catalog (the curated catalog, pulled from the public amc-skills GitHub repo — you don't need to visit it; everything in it is browsable and searchable right here). Each tab has a search box that filters by name + description; a row shows the description on one line, and hovering it shows the whole description. Arrow keys navigate the list, Enter confirms.
   • A skill folder that is a shortcut counts as installed. Some installers (the skills CLI is the common one — npx skills add <repo>) keep a skill's files somewhere else, typically ~/.agents/skills/<name>, and leave a symlink or Windows junction at ~/.claude/skills/<name>. Claude Code loads those, so Omniscio lists them too: the Installed tab, the composer's / menu and GET /skills all follow the shortcut to the real folder. A shortcut whose target is missing, is a file, or holds no SKILL.md is simply not listed. Editing one is still refused (a CLI owns those files), and removing it moves only the shortcut to the trash — never the real files behind it.
   • Each plugin skill appears once. A plugin's cache can hold several versions side by side after an update; the Installed tab shows only the version Claude Code currently has installed (falling back to the newest cached one if it can't tell), and opening or removing a plugin skill acts on that same version.
3. Install a skill from the catalog. Select a catalog skill to preview it, then click the blue Install button. The first time you install from the catalog, a trusted-source acknowledgement modal appears explaining that you're pulling content from a remote GitHub repo — click Accept to proceed. That consent is remembered (skillsTrustedSourceAcknowledged), so you won't see the modal on subsequent installs.
4. Edit your own skill. Select any non-plugin skill in the Installed tab and click the pencil Edit button. A textarea reveals the raw SKILL.md content — edit it, then save with Cmd/Ctrl+S or the Save button. If you navigate away with unsaved changes, a "Discard changes?" dialog protects your work. Plugin-bundled skills are read-only — selecting one shows a provenance line in the detail-pane header: which plugin it came from, its version, the author, the marketplace it was distributed through, and clickable links to both the marketplace's central repository and the plugin's own Repository (the source repo it was built from). Both links open in your system browser.
5. Update or remove. If a skill you installed has a newer catalog version, an Update button appears — click it to atomically fetch and replace the file on disk (your UUID is preserved so nothing else breaks). To remove, click the red trash icon and confirm. User skills soft-delete to ~/.claude/.amc-skills-trash/ and show an Undo toast; plugin skills hard-delete from their cache. One skill can't be removed: omniscio-control, the skill the seven other Omniscio skills (omniscio-sessions, omniscio-scheduling and the rest) route into. It shows "Needed by 7 other Omniscio skills, so it can't be removed." where the button would be, the Skill Overhead card never offers it, and if an older version archived it, Omniscio puts the whole current skill back on the next launch. The declaration lives in the skill family's manifest (requiredSkillIds in /src/shared/integrations/omniscio-control.ts); the rules are in bundled-skill-feature-gating-contract.md.
6. Spot under-used skills with usage tracking. Each Installed row shows "Last used 2d ago · 45 uses" (or "Never used") derived from your local JSONL session transcripts. The sort dropdown above the list offers Alphabetic / Least used / Never used / Most used / Recently used — "Never used" is the fastest lens for "what should I uninstall?" The header has a Scan button to force an immediate re-scan (otherwise the scanner runs 5s after launch, drains during idle, and re-checks every 60 min). Right-click any installed row to open its actions menu — today that's Reset usage (confirm-gated, per-skill). (There is no longer a three-dot ⋮ button; right-click is the way in.) The header Clear usage button wipes every skill's history in one shot. While a scan is in progress, a small pulsing-dot banner shows "Scanning N files…"; if the AMC_DISABLE_TOOL_INVOCATION_SCANNER=1 kill switch is set, the banner instead warns that usage tracking is disabled.
7. See how many tokens your skills cost. Skills aren't free. Every installed skill's YAML frontmatter is loaded into Claude's skill-discovery index at the start of every conversation — the "always-on" cost you pay whether or not the skill is ever invoked. The body and any linked sibling files load only when Claude actually uses the skill. Two places surface this, and both label every figure as approximate (a chars ÷ 4 estimate, shown with a leading "~"):
   • Globally, a summary line directly under the Installed tab strip reads e.g. "~3k frontmatter · ~30k total". The left number sums the always-on frontmatter across every installed skill; the right number is what you'd pay if every skill fully loaded (frontmatter + body + files). The line is hidden when you have no skills installed (or none carry a measurable cost). Use the frontmatter number to watch your baseline overhead — if it climbs into the tens of thousands, every conversation pays that tax up front, and "Never used" skills (step 6) are the first to consider uninstalling.
   • Per skill, selecting any skill shows a breakdown in the detail-pane header, e.g. "~12k tokens total · Frontmatter ~1k · Body ~10k · Files ~1k", with a tooltip explaining when each part loads.

For agents

How it works

Skills is registered as a virtual project via SKILLS_PROJECT_ID = '__skills__' in /src/shared/virtual-project-ids.ts; the Dashboard routes it into the sub-sidebar + main-view split at /src/renderer/src/features/dashboard/Dashboard.tsx. The UI is two components — /src/renderer/src/features/skills/SkillsSubSidebar.tsx for the list/search/tabs and /src/renderer/src/features/skills/SkillsView.tsx for the frontmatter header, markdown body, and edit/view toggle — backed by a Zustand store at /src/renderer/src/stores/skills-store.ts that tracks activeId, mode (view/edit), draft, and dirty. The backend's public surface is /src/main/services/skills/skills-service.ts — a thin factory wiring focused skills-* leaves (skills-scan, skills-catalog-enrich, skills-install, skills-remove, skills-fs, skills-errors) — exposing listInstalled(), listProjectSkills(workdir) (the composer slash menu's per-session scan of <workdir>/.claude/skills, tagged source: 'project' — see send-a-message.md; it never surfaces in this sidebar), install(), save(), remove(), and updateOne() with atomic writes (<path>.amc.tmp → SHA-256 verify → rename) and a server-side plugin-rejection guard (defense-in-depth on top of the Zod regex at the IPC layer). Catalog metadata is fetched by /src/main/services/catalog-fetcher.ts from the public GitHub repo, with a host allow-list (raw.githubusercontent.com, objects.githubusercontent.com) to prevent SSRF. The master toggle enableSkillsIntegration lives in AppSettings (default true). Feature telemetry is registered in /src/shared/feature-registry/index.ts under domain skills with a strict metadataAllowList — skill body content is never emitted in events, only {name, source}. Full design + invariants are in the Claude Skills Integration postmortem.

Two rules govern what the scan in skills-scan.ts treats as installed, both locked as invariants in master-skills-inventory-contract.md. User roots follow links: a directory entry that is a symlink or Windows junction is stat-ed through and accepted when the target is a directory with a SKILL.md (user:<name> / project:<name>, folderPath = the link path) — this is the skills-CLI layout Claude Code already loads, and dropping links is what hid it. Any stat failure on a linked entry skips that entry only: the per-entry worker runs under a fail-fast mapWithConcurrency whose callers fall back to an empty list, so a propagated error would blank the whole user list. The plugin-cache directory walk is deliberately exempt and still skips links — the Claude CLI owns that tree. The plugin walk visits one version per plugin: the row id omits the version, so walking every cached version produced duplicate ids; the active version comes from ~/.claude/plugins/installed_plugins.json when it is actually cached, else the newest cached, and listInstalled() / read() / remove() share the one pickActivePluginVersion (the manifest-aware findPluginSkillFolder is only ever handed that version) so they cannot disagree. Write paths are unchanged: save() lstat-refuses a linked folder, remove() renames the link itself, and rmRecursiveSafe now detaches a link — top-level or nested — rather than recursing through it (see the junction-wipe postmortem).

Each installed row's actions (today just Reset usage) live in a right-click context menu — the shared /src/renderer/src/components/ui/UsageRowContextMenu.tsx, owned by the list (one menu, repositioned at the cursor) and reused by the MCP Servers sidebar; there is no per-row three-dot button. Plugin provenance (author, the plugin's own repositoryUrl, and the marketplace's marketplaceUrl) is read by scanPluginSkills in skills-scan.ts from each plugin's .claude-plugin/plugin.json and ~/.claude/plugins/known_marketplaces.json; only http(s) URLs survive, and a missing or malformed manifest degrades to "no links" rather than dropping the skill. SkillsView renders these in the detail-pane header for source: 'plugin' skills only.

Token costs come from /src/shared/skill-token-cost.ts, which splits each SKILL.md into its frontmatter block (the opening --- through the first closing ---, delimiters included so the count matches what Claude's index actually sees) and its body, runs both through the chars/4 estimateTokens heuristic in /src/shared/token-estimate.ts, and adds the estimated size of any sibling files in the skill folder — producing the { frontmatter, body, files, total } shape carried on each skill row's optional tokenCost field (optional because sibling-file enrichment can fail, and we'd rather show the row with a missing cost than blank the list). The per-skill breakdown renders in SkillsView; the global summary line in SkillsSubSidebar sums every installed skill via two pure helpers — sumSkillFrontmatterTokens() (the always-on subset) and sumSkillTokenTotals() (the full-load total) — each skipping any skill whose tokenCost is undefined so one failed enrichment never blanks the aggregate. The summary line is gated on a non-zero total and on the Installed tab being active. The same sumSkillFrontmatterTokens() figure also feeds the session Context Details popover's "Skills (frontmatter)" line (via computeSkillsFrontmatterTotal() in /src/main/ipc/context-handlers.ts), so the always-on number stays consistent between the Skills view and the per-session context breakdown.

Usage tracking is derived from the same JSONL scanner that powers the MCP Servers view. /src/main/services/tool-invocation/tool-invocation-scanner.ts walks ~/.claude/projects/**/*.jsonl, parses every tool_use block, and upserts an aggregate row into the tool_invocations SQLite table — kind = 'skill' rows are keyed by skill slug (extracted from the Skill tool's input.skill field). The scanner is resumable per-file via tool_invocation_scanner_state (mtime + byte-offset cursor) and is scheduled by /src/main/services/tool-invocation/tool-invocation-scanner-scheduler.ts on four triggers (5s post-launch backfill, 30s blur-delay idle drain, 60min periodic, manual triggerScanNow()). The Skills store joins the per-skill aggregate to installed rows by folderName, and the sort helper /src/renderer/src/features/skills/sort-installed-skills.ts is a pure module so node-env unit tests don't pull React in. Reset/clear actions are optimistic in the store with rollback on IPC failure. Kill switch: AMC_DISABLE_TOOL_INVOCATION_SCANNER=1.

Cross-provider delivery — one master inventory, every provider

Every provider session Omniscio launches sees the same master skill list, delivered through whichever channel that provider can use. master-skill-inventory.ts is the single source of "what skills exist": it scans the canonical ~/.claude/skills user root plus every marketplace plugin's bundled skills, merged and sorted, metadata only (never a skill body). Two consumers derive from it:

• Native-root delivery. Providers with native skill support — Claude + the anthropic-compat vendors, Codex, Gemini, OpenCode, Cursor — receive your actual skill folders through their own skill root via the existing config-sync / mirror system (provider-config-sync/sync-skills.ts); nothing is injected into the session prompt.
• Prompt index. Providers with no native skill surface (Antigravity, Hermes, Grok, Pi, KimiCode, OpenClaw, Devin, terminal, …) receive a compact metadata-only index in their first message — each skill's name, a one-line description, and where it came from, plus guidance to ask the operator to enable a skill or paste its full instructions. Full skill bodies are never injected; they load only through a provider's native invocation path or that explicit follow-up.

Clean Room and virtual/helper sessions strip skills entirely — a control-group Clean Room baseline carries none of your customizations, and a virtual/__-prefixed helper project carries purpose-built context, never user skills. See the Master Skills Inventory contract for the gating and invariants.

Related

• mcp-servers.md — the sibling MCP Servers sidebar, sharing the JSONL scanner + tool_invocations SQLite table
• omniscio-control.md — the consolidated Omniscio-control skill bundle (cron, automations, settings, recipes, sessions, projects, tags, away-mode, keybindings, pending actions)
• create-cron-job-with-ai.md — the cron walkthrough, now powered by the omniscio-control bundle
• snooze-a-session.md