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 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 and to keep that installed reference available even when a machine no longer has the source checkout.

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

• isolated CLI commands

• skill-local hook files with RESULT, LAST_RESULT, and explicit [[STOP]] control

• browser pages rendered from /app/<repo-name> and /app/<repo-name>/<id>

• collectors and indicator definitions in skill-local config/config.json that join the managed fleet under repo-qualified names

• an isolated config, docker, state, logs, system-package, 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
dashboard example-skill.hello

Open its bookmark:

/app/example-skill
/app/example-skill/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> or the short dashboard <repo-name>.<command> form 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 RESULT, the immediate previous hook is exposed through LAST_RESULT, and later hooks stop only when a hook writes [[STOP]] to stderr.

config/config.json

Skill-owned JSON config. Developer Dashboard guarantees the file exists, does not impose a rich schema, and merges it into the effective dashboard config under _<repo-name>. If the skill declares collectors there, those collectors join the normal managed fleet under names such as example-skill.status, so serve, restart, stop, prompt rendering, and browser status treat them the same way they treat system-owned collectors.

config/docker/

Reserved root for skill-local Docker or Compose files. The dispatcher exposes this path through DEVELOPER_DASHBOARD_SKILL_DOCKER_ROOT, and docker service lookup includes installed skill docker roots after the home runtime docker config and before deeper project layers.

dashboards/

Bookmark instruction files shipped by the skill, including dashboards/index for /app/<repo-name>.

dashboards/nav/

Skill nav fragments and bookmark pages loaded into the skill app routes. They also join the shared nav strip rendered above normal saved /app/<page> routes such as /app/index, so multiple installed skills can contribute top-level nav at once.

state/

Persistent skill-owned state.

logs/

Persistent skill-owned logs.

local/

Isolated local dependency root.

aptfile

Optional system package declaration. When present, Developer Dashboard installs those packages before it processes the skill cpanfile.

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

• expose the immediate previous hook payload through LAST_RESULT

• skip later hooks only when a hook writes [[STOP]] to stderr

• do not treat plain non-zero exit status as an implicit stop

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

• LAST_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:

• app index: /app/<repo-name>

• app page: /app/<repo-name>/<id>

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

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

Examples:

/app/example-skill
/app/example-skill/welcome
/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 app and older compatibility routes are render surfaces, not browser edit/source surfaces

SKILL COLLECTOR FLEET

Skill collectors are declared inside the skill's config/config.json:

{
  "collectors": [
    {
      "name": "status",
      "command": "printf 'ok'",
      "cwd": "home",
      "indicator": {
        "label": "Example Skill",
        "icon": "E"
      }
    }
  ]
}

When that skill is installed, the collector joins the same managed fleet used by the main dashboard config. The runtime qualifies the collector name with the repo name, so the effective collector becomes example-skill.status instead of a bare status. That qualified name is what the collector runner uses for loop metadata, process titles, and managed indicator rows.

Operationally that means:

• dashboard serve starts skill collectors together with the system fleet

• dashboard restart restarts both the system collectors and the installed skill collectors

• dashboard stop stops the whole managed collector fleet, including skills

• collector indicator config in the skill file feeds the same prompt and browser status surfaces as system-owned collectors

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 pages auto-load dashboards/nav/* into /app/<repo-name> and /app/<repo-name>/... routes, and the same installed skill nav fragments are also rendered above normal saved /app/<page> routes such as /app/index. Skills can still render files such as dashboards/nav/help.tt directly through /skill/<repo-name>/bookmarks/nav/help.tt.

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/ with /app/... routes and the older /skill/.../bookmarks/... route.

Can a skill ship collectors or indicators?

Yes. Declare them in the skill's config/config.json. They join the managed fleet under repo-qualified names such as example-skill.status, and their indicator config participates in the normal prompt and browser status flow.

Can I use isolated Perl dependencies?

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

Can a skill install system packages first?

Yes. Ship an aptfile. Developer Dashboard installs those packages before it processes the skill cpanfile.

Where is the long-form guide?

The repository ships a separate skill authoring guide, while the installed distribution keeps this POD available through perldoc.

SEE ALSO

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 the repository's separate skill authoring guide.

HOW TO USE

Treat it as installed reference documentation. Keep its content synchronized with the repository's separate skill authoring 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 repository skill authoring 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