Shared Skills

Keep reusable instructions in one local library. Browse and edit them with suv skills, let an MCP-capable agent discover them, or sync them into Claude Code, Cursor, and Codex. Since 0.5.1 a team can also commit skills to the repository, which sync once you have read and trusted them.

Quick Start

# Open the interactive manager
suv skills

# Save instructions for the current project
suv skills add test-workflow --scope here \
  --description "How to validate this project" \
  --body "Run the project test suite and build before proposing a release."

# Preview native files before writing them
suv skills sync --dry-run

Skills live in Suvadu's SQLite database. Human-created skills are active immediately. Adding or editing a skill does not automatically sync its native files; run suv skills sync when ready.

Interactive Manager

Type to filter the active skills list and see a live preview of the selected skill. The manager opens even when the library is empty.

The Add/Edit form collects metadata first. Tab or Enter advances fields; Enter on the last field opens the editor for the Markdown body ($VISUAL, then $EDITOR, then vi). In the review queue, a approves, r rejects, and Esc returns to the library. Rejected proposals are archived and remain visible with list --all. Pasted text is accepted in the search box and the form, and the search box holds up to 200 bytes, typed or pasted.

Repo skills appear in the list with origin repo, their file path and their trust state, read-only: editing, deleting or disabling one is refused with the name of the file to change instead.

Scriptable Commands

# Read a Markdown body from stdin
suv skills add deploy-checklist --description "Pre-deploy steps" \
  --trigger deploy --trigger release < deploy.md

suv skills list
suv skills list --scope here --json
suv skills list --all
suv skills show deploy-checklist --scope global

# Replace the body using stdin
suv skills edit deploy-checklist --scope global --body - < deploy.md

# Update just the summary or triggers
suv skills edit deploy-checklist --description "Release checks" --trigger release

suv skills rm deploy-checklist --scope global

# Stop one syncing without deleting it, and start it again
suv skills disable deploy-checklist
suv skills enable deploy-checklist

# Trust this repository's .suvadu/skills/*.md, or take it back
suv skills trust
suv skills untrust

add reads stdin when --body is omitted. edit reads stdin only with --body -; omitted fields stay unchanged. Repeat --trigger to set multiple keywords. Names contain 1–128 ASCII letters, digits, hyphens, or underscores.

Scopes

• global is the default for new skills.
• --scope here resolves to the current directory.
• --scope /absolute/project/path selects a specific project scope.

The same name can exist in multiple scopes. Pass --scope to show, edit, or rm when you need an exact match. Without it, those commands prefer a global match and can fall back to another active skill with that name; they do not automatically select the current project.

Sync to Agent Files

suv skills sync --dry-run
suv skills sync
suv skills sync --target claude-code
suv skills sync --target cursor
suv skills sync --target codex

Run sync from the project directory whose skills you want to materialize. It includes global skills and active skills whose scope exactly matches that directory; parent-directory scopes are not inherited by sync.

Sync only rewrites content that differs, and --dry-run names each target file and shows the diff before anything is written. Codex content outside the suvadu:skills markers is preserved. A generated file or block edited outside Suvadu since it was written is reported as a conflict and skipped, not overwritten; --force overrides that. A file Sync cannot read (one that is not UTF-8, say) is never replaced, even with --force, and a file reached through a symlink is updated in place, keeping the link and its permissions.

Since 0.5.1, sync also removes what it generated for skills that are gone: a skill removed with suv skills rm, stopped with suv skills disable, or a repo skill no longer trusted or deleted. Only files and blocks that still carry Suvadu's intact marker are removed; a file edited since is reported and kept, and hand-written agent files are not mentioned at all. --dry-run lists them as would remove. suv skills cleanup still does the same on its own.

Use distinct skill names across scopes when syncing to Cursor: global and project skills with the same name target the same .mdc file. Prefer --scope here or a consistent absolute path; relative paths and symlinks are not resolved to a canonical project scope.

Builtin Skills

Suvadu itself owns one skill, suvadu-session-memory, seeded automatically rather than authored by hand. It steers a connected agent toward Suvadu's own session-tracking tools (resolve_current_agent_session, get_agent_session, save_session_summary) instead of writing a generic memory note when you ask it to summarize or save a session — closing the gap where an agent has no way to know those tools exist unless something in its context points at them.

It's gated on mcp.allow_session_summaries = true in the global config.toml (no CLI flag yet) and, once enabled, is seeded and materialized automatically — no separate step required:

• suv init claude-code seeds it and writes ~/.claude/skills/suvadu-session-memory/SKILL.md immediately, every time it runs.
• A bare suv skills sync also seeds it first, so it's installed even without ever having run init — and since a skill isn't host-restricted, a default sync (no --target) materializes it into Cursor's project rules and Codex's AGENTS.md too, the same as any other active global skill.

It behaves like any other skill once installed — suv skills show suvadu-session-memory inspects it. Turning allow_session_summaries back off only stops it from being reseeded; an already-active skill keeps syncing as-is. Use suv skills disable suvadu-session-memory (or rm) to stop it, and the next sync removes the files it generated.

Team Skills in the Repository

Since 0.5.1 you can commit skills next to the code, one Markdown file each, in .suvadu/skills/:

---
name: release            # optional; defaults to the file name (release.md)
description: How we cut a release
triggers: [release, tag]
targets: [claude-code, codex]   # optional; default: every agent
---

1. Bump the version in Cargo.toml.
2. Tag, then push the tag.

Everyone who clones the repository gets them, so Suvadu treats them as untrusted until you have read them:

suv skills list                 # repo skills show origin 'repo' and 'untrusted'
suv skills show release         # read one (its file path, trust, body)
suv skills trust --dry-run      # list this repository's skills and their state
suv skills trust                # trust them (or: suv skills trust release)
suv skills sync                 # from the repository root: writes them like project skills

• Where they sync. The project is the nearest directory with a .suvadu/skills/ folder, looking up from where you are but never above the git repository's root. Repo skills sync from that directory into its .claude/skills/, .cursor/rules/ and AGENTS.md, exactly where a project skill would go.
• Trust is per file. suv skills trust records a sha256 of each file's content (--repo PATH for another checkout, a name for just one). When the file changes — after a pull, say — it shows as changed since trusted: the next sync stops writing it and removes the copy it wrote, until you trust it again. suv skills untrust takes trust back, and the next sync removes the copies.
• Suvadu never edits, moves or deletes a repo skill file. Edit the file itself; in suv skills they are read-only and show their path.
• Precedence. A trusted repo skill takes the place of a library skill scoped to the same project with the same name (and shadows a global one there), and the sync says so. An untrusted one changes nothing.
• Removing the file removes its synced copies on the next sync — only copies Suvadu wrote and nobody edited since.
• Skipped files. A file whose name is not letters, digits, - and _, a symlink, a file over 256 KB or not UTF-8, one with no body, or one whose targets names an unknown agent is skipped with a warning naming it.

Trust is stored in your local database as hashes only, never the file's text: the project root, the path inside it, the sha256 and when you trusted it. See Privacy.

MCP Discovery and Proposals

The MCP server exposes list_skills, get_skill, search_skills, and the suvadu://skills/index resource. These read active skills. Since 0.5.1 the three tools also include the repo skills of the project the agent names (scope) or the server runs in, with source repo, the file path and the trust state. An untrusted or changed repo skill is listed by name and path only: its description and body are not served until you trust it. The client decides when to call a tool or load a resource; connecting MCP alone does not guarantee instructions enter the model's context.

Agent proposals are optional. Enable the proposal tool in the global config.toml:

[mcp]
allow_skill_proposals = true

Restart the MCP server after changing its configuration. propose_skill then becomes available as an additional tool. It creates only pending_review skills, which are excluded from normal discovery and sync until a human approves them in suv skills with Ctrl+P. The option is off by default.

Skills are instructions, not executable commands. Your connected AI client controls how it uses their contents and whether it sends them to a model provider.