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

cpanm Developer::Dashboard

perl -MCPAN -e shell
install Developer::Dashboard