Skip to content

commands.md

Latest commit

 

History

History
262 lines (182 loc) · 9.53 KB

commands.md

File metadata and controls

262 lines (182 loc) · 9.53 KB

Commands

Overview

skern init                                    # Initialize .skern/ in current project
skern skill create <name>                     # Scaffold a new skill
skern skill edit <name>                       # Edit skill metadata or body
skern skill search <query>                    # Search skills by name/description
skern skill recommend <query>                 # Recommend: reuse, extend, or create
skern skill list [--scope user|project|all]   # List skills in registry
skern skill show <name>                       # Display skill details
skern skill validate <name>                   # Validate against Agent Skills spec
skern skill remove <name>                     # Remove skill from registry
skern skill install <name>... --platform <p>  # Install one or more skills to platform
skern skill uninstall <name>... --platform <p> # Remove one or more skills from platform
skern platform list                           # List detected platforms
skern platform status                         # Skill x platform installation matrix
skern completion [bash|zsh|fish]              # Generate shell completions
skern version                                 # Print version info

skern init

Initialize the .skern/ directory in the current project (creates the project-scoped skill registry). Optionally writes a skern usage snippet into agent instruction files (AGENTS.md, CLAUDE.md, .claude/CLAUDE.md) so the agent uses skern for all skill-related tasks instead of reading platform-native skill directories.

skern init                                    # creates .skern/ only (default)
skern init --instructions                     # also writes the usage snippet to discovered agent config files
skern init --instructions --tool-forming-loop # adds the search-before-create workflow section
skern init --target ./MY_AGENT.md             # write to a specific file (skips auto-discovery)
skern init --print-instructions               # print the snippet to stdout instead of writing files

Flags:

Flag Description
--instructions Write the skern usage snippet to discovered agent config files (AGENTS.md, CLAUDE.md, .claude/CLAUDE.md). Default: off.
--tool-forming-loop Include the tool-forming-loop section (search-before-create workflow). Default: off.
--target <path> Explicit instruction file path. Repeatable. Disables auto-discovery when set.
--print-instructions Print the rendered snippet to stdout instead of writing files.

The instruction snippet is wrapped in <!-- skern:instructions:start --> / <!-- skern:instructions:end --> markers, so re-running skern init --instructions updates the block in place rather than appending duplicates.

When run on a TTY without --json or instruction flags, skern init prompts the user for both choices (write instructions? include tool-forming loop?). Default to No for both. Non-interactive runs (CI, scripts, --json) honor flag values only — no prompts.

skern skill create

Scaffold a new SKILL.md file in the registry.

skern skill create <name> [flags]

Flags:

Flag Description
--author Author name
--author-type human or agent
--author-platform Platform name (e.g., claude-code)
--description Skill description
--tags Comma-separated list of tags
--scope user or project (default: user)
--force Bypass overlap block
--from-template <dir> Seed from a skill directory containing SKILL.md and optional companion files (see below)

Overlap detection runs automatically during creation. See Overlap Detection for details.

--from-template

--from-template <dir> accepts a skill directory — a directory containing a SKILL.md plus any optional companion files. Skern parses the template's frontmatter and recursively copies every sibling file and subdirectory (references/, templates/, VENDORED.md, …) into the new skill.

Anything else is rejected with a clear error:

  • --from-template <file> → "must point to a skill directory containing a SKILL.md file … pass the parent directory instead"
  • --from-template <dir-with-no-SKILL.md> → "directory has no SKILL.md; a skill template must be a directory containing a SKILL.md file"

The new skill's name is always taken from the CLI argument. Other CLI flags (--description, --tags, --author*, --version) override the template's values when explicitly set; otherwise the template's values are preserved.

skern skill edit

Edit a skill's metadata fields or open the body in an editor.

skern skill edit <name> [flags]

When called with field flags, the specified fields are updated directly. When called without field flags, the skill body is opened in $EDITOR (defaults to vi).

Flags:

Flag Description
--scope user or project
--description New description
--author New author name
--author-type human or agent
--author-platform Platform name
--version New version string
--modified-by Name of modifier (appends to modified-by list)
--modified-by-type human or agent
--modified-by-platform Platform name for modifier

skern skill search

Search skills by name or description.

skern skill search <query> [flags]

Flags:

Flag Description
--tag Filter results to skills with this tag

skern skill recommend

Get recommendations on whether to reuse, extend, or create a skill.

skern skill recommend <query> [flags]

Flags:

Flag Description
--name Agent-suggested skill name
--threshold Minimum relevance score (default: 0.3)
--scope user, project, or all

skern skill list

List all skills in the registry.

skern skill list [--scope user|project|all] [flags]

Flags:

Flag Description
--scope user, project, or all
--tag Filter results to skills with this tag
--with-platforms Include installed_on per-skill: the detected platforms where the skill is currently installed at the same scope

Also runs pairwise overlap detection across all listed skills and appends a "Potential duplicates" section when matches are found (score >= 0.6). In --json mode, these appear in the duplicates array.

Skills that cannot be parsed are reported as parse warnings rather than silently skipped. In text mode these appear as warning lines; in --json mode they appear in the parse_warnings array.

When --with-platforms is set, the JSON output contains an installed_on array on every skill — empty for skills not installed on any detected platform. Without the flag the field is omitted entirely so consumers can distinguish "queried, none" from "not queried".

skern skill show

Display full details for a skill, including author provenance and modification history.

skern skill show <name>

skern skill validate

Validate a skill against the Agent Skills spec.

skern skill validate <name>

See Validation for the full list of checks.

skern skill remove

Remove a skill from the registry.

skern skill remove <name>

skern skill install

Install one or more skills to a single platform.

skern skill install <name>... --platform <platform>

Each invocation targets exactly one platform. Agents are expected to specify the platform they are running on; --platform all is no longer accepted. To deploy a skill across multiple platforms, loop the call per platform.

Multiple skill names can be passed in a single call. Each skill's outcome is reported as a separate entry in the skills array. A failure on one skill does not abort the batch — the command exits non-zero only when every install fails.

The response includes a capacity block reporting the platform's installed-skill count after the operation, the threshold for that scope, and remaining headroom. Use it to decide whether to evict stale skills before the next install.

Flags:

Flag Description
--platform One of: claude-code, codex-cli, opencode, cursor, gemini-cli, github-copilot, windsurf, continue (required)
--scope user or project
--force Overwrite existing installation
--enforce-budget Refuse the operation if it would push the platform's installed-skill count past the per-scope threshold

skern skill uninstall

Remove one or more skills from a platform.

skern skill uninstall <name>... --platform <platform>

Mirrors install semantics: one platform per call, multiple skills allowed, partial failures are reported per-skill, and the response includes a post-op capacity block.

Flags:

Flag Description
--platform One of: claude-code, codex-cli, opencode, cursor, gemini-cli, github-copilot, windsurf, continue (required)
--scope user or project

skern platform list

List all detected platforms.

skern platform list

skern platform status

Show a matrix of skills and their installation status across platforms.

skern platform status [--scope user|project]

skern completion

Generate shell completion scripts.

skern completion bash
skern completion zsh
skern completion fish

skern version

Print version, commit, and build date.

skern version