/ 
App-karr-0.601
/ App::karr::Cmd::Skill

NAME

App::karr::Cmd::Skill - Install, check, and update bundled agent skills

VERSION

version 0.601

SYNOPSIS

karr skill install
karr skill install --agent codex,cursor
karr skill check --global
karr skill update --force
karr skill show

DESCRIPTION

Installs and maintains the bundled karr skill for supported agent clients. The skill is a directory -- SKILL.md, which an agent loads on every trigger, plus references/*.md, which it reads on demand -- and every action below treats that set as one unit. The command can target project-local directories or global skill locations in the current user's home directory, which makes it useful both for direct Perl installs and Docker-wrapped vendor usage.

Writes go into each target file in place, keeping its inode, so a SKILL.md that is one link of a hardlink chain shared across projects stays part of that chain instead of being silently broken out of it.

--global selects the home-directory location instead of the project-local one; the two coincide for claude-code and cursor but differ for codex (see "SUPPORTED AGENTS").

TARGET DIRECTORY

The project-local target is the current working directory: the skill directory is written straight underneath it, at .claude/skills/kanban-issues-karr-cli/ for claude-code and at the equivalent path for the other agents. Nothing is discovered on the way there and no repository is involved -- this command has no board, and installing into a directory that is not a Git repository at all is a supported use. --global is the same idea one level up: the target is the current user's home directory instead. When --agent is omitted, even the auto-detection reads the current directory, so both which agents are touched and where their files land follow from where the command was run.

The root option --dir is therefore refused, in both placements, and both exit 2: karr skill install --dir PATH is an unknown option (this command declares none), and karr --dir PATH skill install is a usage error that names the current directory as the target. --dir is the starting point of a search upward for one repository's root -- which is why it may name any directory inside that repository -- and that is not what this command's target is; handed the same path, the two would answer about different directories. To install into another tree, cd there. Before ticket #226 the root placement was accepted and then discarded without a word, so the file was written into the tree the caller happened to be standing in while the message read as if the named one had been used.

karr init --claude-skill writes the very same directory and does honour --dir: it installs into the root of the repository it is initializing, and it needs a repository in the first place.

SUPPORTED AGENTS

The built-in agent targets are claude-code, codex, and cursor. When --agent is omitted, the command auto-detects available client directories and falls back to all known agents if nothing is detected.

ACTIONS

  • install

    Writes the current bundled skill -- SKILL.md and every references/*.md -- to the selected target locations. A target that already has a SKILL.md is left alone and reported exists unless --force is given, which overwrites every file unconditionally. Every target is reported with the absolute path of its SKILL.md, in the plain output as well as under the path key of --json, so the message says which tree the skill went into.

  • check

    Compares every installed file with the bundled version and exits non-zero when one or more targets are outdated: a shipped file that is missing from the target, or differs from it, makes the target outdated. A target with no SKILL.md is not installed, whatever else is under it.

  • update

    Refreshes installed copies in place: every shipped file that is missing or differs is rewritten, the ones that match are left untouched, and so is anything in the target that is not shipped (a reference file a later release dropped, say). current means every file already matched.

  • show

    Prints the bundled SKILL.md to standard output. With --json the same content is emitted as a JSON object under the content key instead of raw Markdown.

SEE ALSO

karr, App::karr, App::karr::Cmd::Init, App::karr::Cmd::Context, App::karr::Cmd::Config

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/karr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)