/ 
Skilletor-0.001
/ Skilletor::Catalog

NAME

Skilletor::Catalog - Scan a source tree into its installable items, bundles and source metadata

VERSION

version 0.001

SYNOPSIS

use Skilletor::Catalog;

my $cat = Skilletor::Catalog->scan($source_dir);            # the source layout
my $sub = Skilletor::Catalog->scan( $source_dir, ['tools'] );   # a source's `path`

for my $item ( @{ $cat->{items} } ) {
  # { type => 'skill', name => 'perl-moo', dir => 'skills/perl-moo',
  #   files => [ 'skills/perl-moo/SKILL.md', ... ], description => '...', error? }
}

DESCRIPTION

The reference's catalog.ts (spec §4.1): what a source tree offers.

skills/<name>/SKILL.md[.njk] + companion files
agents/<name>.md[.njk]
rules/<name>.md[.njk]
bundles/<name>.yaml|.yml            named item sets (spec §15)
skilletor.json                      { description, vars }
.claude-plugin/plugin.json          a Claude plugin's `skills` paths
.claude/skills|agents|rules/        the Claude project layout, best effort

With a source's path the items are the skills beneath those paths and nothing else (no bundles, no other layout). Names come from the paths; descriptions from the main file's frontmatter, read raw – a .njk file is never rendered for it. A symlink in the tree fails the scan (in .claude/ it is skipped); an agent with both .md and .md.njk, a skill holding f beside f.njk, or one name (ignoring case) in several places is an item carrying an error, never a failed scan. Every message is the reference's; a failing file system call reads as Node's.

scan

Skilletor::Catalog->scan( $dir, $paths );

{ items => [...], bundles => [ { name, files, def | error } ], meta => { description?, vars? } }. Item files are relative to $dir, /-separated, sorted. Throws Skilletor::Error::Catalog.

SKILL_GITIGNORE

The .gitignore skilletor puts into an installed skill.

LOCAL_PREFIX

.local., the name prefix of installed agents and rules.

SUPPORT

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; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.