/ 
App-karr-0.602
/ App::karr::Cmd::Skill

NAME

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

VERSION

version 0.602

SYNOPSIS

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

DESCRIPTION

Installs and maintains the bundled karr skills for supported agent clients. Two skills ship:

  • kanban-issues-karr-coordination

    Reading a board, picking, claiming and creating cards, handing them to subagents, filing on another repository's board, configuring and syncing karr.

  • kanban-issues-karr-ticket

    Working the one card an agent was handed: reading it, noting progress, blocking it, handing it to review.

Each skill is a directory -- SKILL.md, which an agent loads on every trigger, plus references/*.md where it has them, which it reads on demand -- and every action below handles the two skills as one set. 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.

Earlier releases shipped a single skill, kanban-issues-karr-cli, that the two above replace. A directory of that name next to them is a leftover: install and update remove it and report it removed, check reports it stale (see "ACTIONS").

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 directories are written straight underneath it, at .claude/skills/kanban-issues-karr-coordination/ and .claude/skills/kanban-issues-karr-ticket/ for claude-code and at the equivalent paths 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 directories 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

Every action reports one line per agent and skill, and with --json one object per agent and skill, each carrying agent, skill and status (plus path where a directory or file was written or removed), in one JSON array. A retired skill directory is reported under its own name in the skill key.

  • install

    Writes the current bundled skills -- each one's SKILL.md and every references/*.md -- to the selected target locations. A skill whose target already has a SKILL.md is left alone and reported exists unless --force is given, which overwrites every file unconditionally. Every written skill is reported installed 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. A retired kanban-issues-karr-cli directory beside them is removed and reported removed, with the path of the directory.

  • check

    Compares every installed file with the bundled version. Per skill: a target with no SKILL.md is not installed, whatever else is under it; a shipped file that is missing from the target, or differs from it, makes the skill outdated; otherwise it is current. Once an agent has either skill (or the retired one) installed, the other one missing counts as outdated too: the two are one set. A retired kanban-issues-karr-cli directory is reported stale. The command exits 1 when anything is outdated or stale -- the check ran and found work for update -- and 0 otherwise; not installed alone is not a failure.

  • update

    Brings the installed set current, 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). An agent counts as installed when it has either skill or the retired one; for such an agent, a skill that is missing is written whole. current means every file already matched, updated that something was written. A retired kanban-issues-karr-cli directory is removed and reported removed -- so update alone migrates a target from the single skill of earlier releases to the pair. An agent with none of them is not installed and left alone.

  • show [NAME]

    Prints a bundled SKILL.md to standard output: the one of skill NAME when given (kanban-issues-karr-coordination or kanban-issues-karr-ticket), otherwise every bundled skill's in the order above, separated by one blank line. Each file is printed as it ships, frontmatter included, so the name: line at the top of each says which skill follows. With --json the output is a JSON array of objects with skill and content -- one per skill printed, so a single NAME gives an array of one. An unknown NAME is a usage error (exit 2).

SEE ALSO

karr, App::karr, App::karr::Cmd::Init, App::karr::Role::SkillFile, 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)