docs(skill): plotjuggler-plugin authoring skill for AI agents

[facontidavide]

What

A new Claude Code skill, .claude/skills/plotjuggler-plugin/, that gives an AI agent (or a human in a hurry) the author-oriented fast path for implementing a plugin against this SDK. The existing pj_plugins/docs/ guides remain the full reference; the skill is a navigator + gotcha-sheet + skeleton provider on top:

• SKILL.md — author-vs-maintainer scoping (macro users never touch ABI rules), family decision tree, correct header + macro per family, one CMake story for all three acquisition channels (Conan / pixi-conda / git submodule — all converge on plotjuggler_sdk::plugin_sdk), the manifest two-copies story, and 8 consolidated load-bearing rules.
• references/{data-source,message-parser,toolbox,dialog,builtin-objects}.md — per-family API skeletons and family-specific traps, loaded only when needed.

How it was validated

• Every API name, include path, macro, and signature checked against the headers and examples/ in this repo.
• Reviewed by two independent Fable agents and Codex (GPT); all confirmed findings fixed (two would-not-compile snippets, an Arrow column overstatement, an onStop() join-deadlock in a skeleton, config-round-trip stubs, thread-rule precision, and more).
• Cross-audited against pj-official-plugins (SDK 0.17.0): the skill now teaches the fleet's actual practice — SchemaHandler-first parsers (direct parse() override demoted to legacy note), _parser_config forwarding for delegated ingest, [thread-safe]-tag-accurate threading, system_clock (never high_resolution_clock) for receive timestamps.

SDK issues surfaced during the review (not fixed here — for triage)

1. pj_plugins/docs/message-parser-guide.md:89 shows #include <pj_base/sdk/message_parser_plugin_base.hpp> — the header lives under pj_plugins/sdk/; copying the guide is a compile error.
2. The parser guide's Quick Start teaches the direct-parse() route the header marks "will be deprecated"; consider restructuring around registerSchemaHandler().
3. All four family guides show only in-tree CMake targets (pj_base, pj_dialog_sdk); none shows find_package(plotjuggler_sdk COMPONENTS plugin_sdk) or the pj_plugin_sdk umbrella — the biggest external-author trap.
4. Builtin roster counts are stale: root CLAUDE.md says "16 struct headers / 15 codecs" and docs/builtin_type.md omits PlotMarkers; the enum has 17 concrete types incl. kPlotMarkers (which has a codec).
5. ARCHITECTURE.md §2 module diagram stale on the parser-base location (already acknowledged in pj_plugins/CLAUDE.md).
6. mock_dialog.cpp / mock_source_with_dialog.cpp omit standardButtons on buttonBox, which the dialog guide calls a MUST — copying the example yields a buttonless dialog.
7. data-source-guide.md doesn't document the _parser_config injection/forwarding convention for delegated sources.

pj-official-plugins issues surfaced (separate repo — for triage)

• Genuine bug: data_stream_mqtt/udp/zmq stamp messages with std::chrono::high_resolution_clock (since-boot on MSVC/libc++) — should be system_clock; three near-identical one-line fixes.
• toolbox_fft row-index timestamps + discarded appendRecord statuses (self-acknowledged TODO pending ScatterXY).
• parser_json/parser_protobuf dialogs miss the using …::onValueChanged; name-hiding guard (latent).
• toolbox_quaternion dialog manifest() lacks id.
• Fleet-wide legacy one-arg PJ_DIALOG_PLUGIN (discovery pays an instantiation).
• Inconsistent push-error policy: UDP aborts on push failure, MQTT/ZMQ warn and continue.

Versioning

Markdown-only under .claude/skills/ — invisible to package consumers → no version bump per the release rules. No build/test run needed (nothing in the build graph changed); pre-commit hooks passed.

🤖 Generated with Claude Code