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.

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.

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

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. Codex content outside the suvadu:skills markers is preserved. Claude Code and Cursor files at the generated paths are replaced, so edit the library and sync again to update them. Claude Code and Cursor files are not removed when a skill is deleted or archived. Codex refreshes a managed block when its scope still has active skills, but an existing block can remain when the last skill in that scope is removed. Review stale generated content separately.

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, matching sync's existing behavior for any skill (there's no prune-on-deactivate path today). Use suv skills rm suvadu-session-memory to stop it from being materialized.

MCP Discovery and Proposals

The MCP server exposes list_skills, get_skill, search_skills, and the suvadu://skills/index resource. These read active skills. 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.