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

Perl module in the Developer Dashboard codebase. This file ships the public POD guide for skill authors working with Developer Dashboard. Open this file when you need the implementation, regression coverage, or runtime entrypoint for that responsibility rather than guessing which part of the tree owns it.

WHY IT EXISTS

It exists to keep this responsibility in reusable Perl code instead of hiding it in the thin dashboard switchboard, bookmark text, or duplicated helper scripts. That separation makes the runtime easier to test, safer to change, and easier for contributors to navigate.

WHEN TO USE

Use this file when you are changing the underlying runtime behaviour it owns, when you need to call its routines from another part of the project, or when a failing test points at this module as the real owner of the bug.

HOW TO USE

Load Developer::Dashboard::SKILLS from Perl code under lib/ or from a focused test, then use the public routines documented in the inline function comments and existing SYNOPSIS/METHODS sections. This file is not a standalone executable.

WHAT USES IT

This file is used by whichever runtime path owns this responsibility: the public dashboard entrypoint, staged private helper scripts under share/private-cli/, the web runtime, update flows, and the focused regression tests under t/.

EXAMPLES

perl -Ilib -MDeveloper::Dashboard::SKILLS -e 'print qq{loaded\n}'

That example is only a quick load check. For real usage, follow the public routines already described in the inline code comments and any existing SYNOPSIS section.

cpanm Developer::Dashboard

perl -MCPAN -e shell
install Developer::Dashboard