---
title: Use Skills (browse, install, edit)
---

# 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. 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](/src/shared/integrations/omniscio-control.ts)); the rules are in [bundled-skill-feature-gating-contract.md](/.claude/memory/contracts/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](/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](/src/renderer/src/features/dashboard/Dashboard.tsx). The UI is two components — [/src/renderer/src/features/skills/SkillsSubSidebar.tsx](/src/renderer/src/features/skills/SkillsSubSidebar.tsx) for the list/search/tabs and [/src/renderer/src/features/skills/SkillsView.tsx](/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](/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](/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](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](/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](/src/shared/types.ts) (default `true`). Feature telemetry is registered in [/src/shared/feature-registry/index.ts](/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](/.claude/memory/postmortems/archived/claude-skills-integration-postmortem.md).

Two rules govern what the scan in `skills-scan.ts` treats as installed, both locked as invariants in [master-skills-inventory-contract.md](/.claude/memory/contracts/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](/.claude/memory/postmortems/bundled-skill-alias-junction-wipe-postmortem.md)).

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](/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](/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](/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](/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](/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](/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](/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](/src/main/services/skills/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](/src/main/services/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](/.claude/memory/contracts/master-skills-inventory-contract.md)
for the gating and invariants.

## Related

- [mcp-servers.md](mcp-servers.md) — the sibling MCP Servers sidebar, sharing the JSONL scanner + `tool_invocations` SQLite table
- [omniscio-control.md](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](create-cron-job-with-ai.md) — the cron walkthrough, now powered by the `omniscio-control` bundle
- [snooze-a-session.md](snooze-a-session.md)