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.

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.