NAME

Developer::Dashboard::SKILLS - shipped skill authoring reference for Developer Dashboard

SYNOPSIS

# Read the long-form guide in the repository root
perldoc Developer::Dashboard::SKILLS

Skill lifecycle:

dashboard skills install git@github.com:user/example-skill.git
dashboard skills update example-skill
dashboard skills list
dashboard skill example-skill hello arg1 arg2
dashboard skills uninstall example-skill

DESCRIPTION

This module is documentation-first. It exists to ship a human-readable skill authoring reference with the distribution.

For the long Markdown guide, see SKILL.md.

Use a skill when you want a Git-backed package that can ship:

• isolated CLI commands

• skill-local hook files

• bookmarks rendered from /skill/<repo-name>/bookmarks/<id>

• an isolated config, state, logs, and local dependency root

QUICK START

Create a Git repository with at least:

example-skill/
├── cli/
│   └── hello
├── config/
│   └── config.json
└── dashboards/
    └── welcome

Install it:

dashboard skills install file:///absolute/path/to/example-skill

Run its command:

dashboard skill example-skill hello

Open its bookmark:

/skill/example-skill/bookmarks/welcome

LAYOUT

Installed skills live under ~/.developer-dashboard/skills/<repo-name>/.

The prepared layout is:

cli/

Executable skill commands. These are run through dashboard skill <repo-name> <command> and are not installed into the system PATH.

cli/<command>.d/

Executable hook files for a command. They run in sorted order before the main command. Their results are serialized into the RESULT environment variable.

config/config.json

Skill-owned JSON config. Developer Dashboard guarantees the file exists but does not impose a rich schema.

config/docker/

Reserved root for skill-local Docker or Compose files. The dispatcher exposes this path through DEVELOPER_DASHBOARD_SKILL_DOCKER_ROOT.

dashboards/

Bookmark instruction files shipped by the skill.

state/

Persistent skill-owned state.

logs/

Persistent skill-owned logs.

local/

Isolated local dependency root.

cpanfile

Optional Perl dependency declaration. When present, Developer Dashboard runs cpanm -L local --installdeps <skill-root>.

SKILL COMMANDS AND HOOKS

Skill commands are file-based commands. Create runnable files such as:

• cli/report

• cli/report.pl

• cli/report.sh

• cli/report.ps1

Do not rely on a directory-backed run pattern for skill commands. That pattern belongs to dashboard-wide custom CLI commands under ~/.developer-dashboard/cli/<command>/run or ./.developer-dashboard/cli/<command>/run.

Hook files live under cli/<command>.d/ and:

• must be executable to run

• run in sorted filename order

• have their stdout, stderr, and exit codes captured into RESULT

• do not automatically prevent the main command from running

SKILL ENVIRONMENT

Skill hooks and commands currently receive these environment variables:

• DEVELOPER_DASHBOARD_SKILL_NAME

• DEVELOPER_DASHBOARD_SKILL_ROOT

• DEVELOPER_DASHBOARD_SKILL_COMMAND

• DEVELOPER_DASHBOARD_SKILL_CLI_ROOT

• DEVELOPER_DASHBOARD_SKILL_CONFIG_ROOT

• DEVELOPER_DASHBOARD_SKILL_DOCKER_ROOT

• DEVELOPER_DASHBOARD_SKILL_STATE_ROOT

• DEVELOPER_DASHBOARD_SKILL_LOGS_ROOT

• DEVELOPER_DASHBOARD_SKILL_LOCAL_ROOT

• RESULT

• PERL5LIB

If the skill has installed local Perl dependencies, PERL5LIB is prefixed with local/lib/perl5.

BOOKMARKS

Skill bookmark files live under dashboards/.

Current route surface:

• list bookmarks: /skill/<repo-name>/bookmarks

• render bookmark: /skill/<repo-name>/bookmarks/<id>

Examples:

/skill/example-skill/bookmarks/welcome
/skill/example-skill/bookmarks/nav/help.tt

Important current behavior:

• the list route only lists top-level files

• nested bookmark files can still be rendered directly when the path is known

• the skill route is a render surface, not a browser edit/source surface

BOOKMARK LANGUAGE

Bookmark files use the original separator-line syntax with directives such as:

• TITLE:

• ICON:

• BOOKMARK:

• NOTE:

• STASH:

• HTML:

• CODE1: and other CODE* blocks

Rules that matter:

• TITLE: sets the browser title and is exposed to templates as title

• Earlier CODE* blocks run before final template rendering

• Returned hashes merge into stash

• Printed STDOUT becomes visible runtime output

• STDERR becomes visible error output

• --- can also act as a section separator

BOOKMARK HELPERS

The bookmark bootstrap exposes:

• fetch_value(url, target, options, formatter)

• stream_value(url, target, options, formatter)

• stream_data(url, target, options, formatter)

Bookmark pages can also use the built-in /js/jquery.js compatibility shim for $, $(document).ready(...), and $.ajax(...).

For normal saved runtime bookmarks, Ajax(file => 'name', ...) can create stable saved Ajax endpoints. That capability is tied to the saved runtime bookmark path. Skill bookmarks render through the skill route surface, so do not assume stable saved /ajax/<file> handlers there unless you have tested that path explicitly.

NAV AND DASHBOARD-WIDE CLI

Normal runtime bookmarks support shared nav/*.tt fragments above non-nav saved pages. Skill bookmarks can still render files such as dashboards/nav/help.tt directly through /skill/<repo-name>/bookmarks/nav/help.tt, but the shared nav auto-insert behavior belongs to the saved runtime bookmark path.

Dashboard-wide custom CLI hooks are separate from skill hooks. They live under ./.developer-dashboard/cli/<command>.d or ~/.developer-dashboard/cli/<command>.d and are used for normal dashboard <command> commands. They can also use directory-backed run commands, which skill commands do not currently use.

FAQ

Do I need every folder?

No. Use the parts your skill actually needs.

Can a skill expose browser pages?

Yes, through dashboards/ and the /skill/.../bookmarks/... route.

Can I use isolated Perl dependencies?

Yes. Ship a cpanfile. Dependencies install into local/.

Where is the long-form guide?

See SKILL.md.

SEE ALSO

SKILL.md, Developer::Dashboard, Developer::Dashboard::SkillManager, Developer::Dashboard::SkillDispatcher

PURPOSE

This module is documentation-only and ships the long-form skill authoring reference inside the installed distribution. It explains the skill directory layout, command and hook model, bookmark routing, isolated dependency root, and environment variables visible to skill commands.

WHY IT EXISTS

It exists because a source-tree-only markdown guide is not enough for tarball and CPAN installs. The skill system needs a shipped manual that survives installation and can be read through perldoc on a machine that does not have the Git checkout.

WHEN TO USE

Use this file when the skill feature gains new layout rules, command semantics, environment variables, or bookmark routing behavior, or when the shipped skill authoring manual needs to stay aligned with SKILL.md.

HOW TO USE

Treat it as installed reference documentation. Keep its content synchronized with the markdown skill guide and focus on explaining how skill authors should structure repos and commands rather than on internal implementation details.

WHAT USES IT

It is used by perldoc Developer::Dashboard::SKILLS, by release metadata checks that compare the shipped docs to the markdown guide, and by contributors authoring or reviewing dashboard skills.

EXAMPLES

Example 1:

perl -Ilib -MDeveloper::Dashboard::SKILLS -e 1

Do a direct compile-and-load check against the module from a source checkout.

Example 2:

prove -lv t/19-skill-system.t t/20-skill-web-routes.t

Run the focused regression tests that most directly exercise this module's behavior.

Example 3:

HARNESS_PERL_SWITCHES=-MDevel::Cover prove -lr t

Recheck the module under the repository coverage gate rather than relying on a load-only probe.

Example 4:

prove -lr t

Put any module-level change back through the entire repository suite before release.

cpanm Developer::Dashboard

perl -MCPAN -e shell
install Developer::Dashboard