fix: inline SKILL.md descriptions for skills.sh rendering

.github/workflows/skill-frontmatter.yml

@@ -0,0 +1,38 @@
+name: SKILL.md Frontmatter Lint
+
+on:
+  pull_request:
+    paths:
+      - "plugins/**/SKILL.md"
+  push:
+    branches:
+      - main
+    paths:
+      - "plugins/**/SKILL.md"
+
+permissions:
+  contents: read
+
+jobs:
+  lint-description:
+    name: Reject multi-line YAML descriptions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check SKILL.md descriptions are single-line
+        run: |
+          set -e
+          # skills.sh meta-tag generator does not parse YAML scalar styles
+          # (vercel-labs/skills#433), so multi-line frontmatter descriptions
+          # render the literal indicator (e.g. `>-`) instead of the text.
+          bad=$(grep -rnE '^description:[[:space:]]*([>|]|$)' plugins/ --include=SKILL.md || true)
+          if [ -n "$bad" ]; then
+            echo "::error::SKILL.md descriptions must be a single-line plain or quoted string."
+            echo "::error::See vercel-labs/skills#433 — skills.sh does not parse YAML folded/literal scalars."
+            echo ""
+            echo "Offending files:"
+            echo "$bad"
+            exit 1
+          fi
+          echo "All SKILL.md descriptions are single-line."

plugins/trogonstack-ask/skills/ask-question/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: ask-question
-description: >-
-  Ask structured questions one at a time to gather requirements, context, or
-  clarification. Each question includes the intention behind it and current
-  assumptions. Use when the user wants to be interviewed about a topic, gather
-  requirements, or needs help thinking through a problem step by step.
+description: "Ask structured questions one at a time to gather requirements, context, or clarification. Each question includes the intention behind it and current assumptions. Use when the user wants to be interviewed about a topic, gather requirements, or needs help thinking through a problem step by step."
 allowed-tools:
   - Read
   - Write

plugins/trogonstack-datadog/skills/datadog-design-dashboard/SKILL.md

@@ -1,15 +1,6 @@
 ---
 name: datadog-design-dashboard
-description: >-
-  Design new Datadog dashboards, redesign existing ones, or audit dashboards
-  for operational readiness. Covers widget selection, layout organization,
-  template variables, group structure, tab organization, alert threshold
-  validation, and zero-knowledge readability. Uses pup CLI for inspecting dashboards and
-  validating designs. Use when designing new dashboards, redesigning existing
-  ones, auditing before on-call handoff, or reviewing after dashboard changes.
-  Do not use for: (1) Datadog agent installation or configuration,
-  (2) monitor/alert rule design, (3) APM instrumentation or tracing setup,
-  (4) log pipeline configuration.
+description: "Design new Datadog dashboards, redesign existing ones, or audit dashboards for operational readiness. Covers widget selection, layout organization, template variables, group structure, tab organization, alert threshold validation, and zero-knowledge readability. Uses pup CLI for inspecting dashboards and validating designs. Use when designing new dashboards, redesigning existing ones, auditing before on-call handoff, or reviewing after dashboard changes. Do not use for: (1) Datadog agent installation or configuration, (2) monitor/alert rule design, (3) APM instrumentation or tracing setup, (4) log pipeline configuration."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eda/skills/event-definition/SKILL.md

@@ -1,15 +1,6 @@
 ---
 name: event-definition
-description: >-
-  Review or create event definitions for event-driven architecture.
-  Covers event names, payload field names, event_type identity, stream
-  naming boundaries, and record metadata/context/payload placement for
-  both domain events (event-sourcing) and integration events (cross-service).
-  Use when designing a new event definition, reviewing an existing event
-  definition, or auditing event definition consistency across a catalog.
-  Do not use for full event modeling workflows (use trogonstack-eventmodeling
-  skills), event schema evolution or migration strategy, or event store
-  implementation design.
+description: "Review or create event definitions for event-driven architecture. Covers event names, payload field names, event_type identity, stream naming boundaries, and record metadata/context/payload placement for both domain events (event-sourcing) and integration events (cross-service). Use when designing a new event definition, reviewing an existing event definition, or auditing event definition consistency across a catalog. Do not use for full event modeling workflows (use trogonstack-eventmodeling skills), event schema evolution or migration strategy, or event store implementation design."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eventmodeling/skills/eventmodeling-applying-conways-law/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: eventmodeling-applying-conways-law
-description: >-
-  Step 6 of Event Modeling - Apply Conway's Law with swimlanes. Organize events
-  into autonomous system parts that different teams can independently own. Use
-  after defining inputs/outputs. Do not use for: planning feature slice
-  implementation order (use eventmodeling-slicing-event-models) or defining
-  command/read model boundaries (use eventmodeling-designing-event-models).
+description: "Step 6 of Event Modeling - Apply Conway's Law with swimlanes. Organize events into autonomous system parts that different teams can independently own. Use after defining inputs/outputs. Do not use for: planning feature slice implementation order (use eventmodeling-slicing-event-models) or defining command/read model boundaries (use eventmodeling-designing-event-models)."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eventmodeling/skills/eventmodeling-brainstorming-events/SKILL.md

@@ -1,12 +1,6 @@
 ---
 name: eventmodeling-brainstorming-events
-description: >-
-  Step 1 of Event Modeling - Brainstorm all domain events from requirements.
-  Extract every state-changing event the system could have. Use when starting
-  event modeling from requirements or a new domain. Do not use for: arranging
-  events in sequence (use eventmodeling-plotting-events), designing commands
-  or read models (use eventmodeling-designing-event-models), or when a complete
-  event list already exists.
+description: "Step 1 of Event Modeling - Brainstorm all domain events from requirements. Extract every state-changing event the system could have. Use when starting event modeling from requirements or a new domain. Do not use for: arranging events in sequence (use eventmodeling-plotting-events), designing commands or read models (use eventmodeling-designing-event-models), or when a complete event list already exists."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eventmodeling/skills/eventmodeling-checking-completeness/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: eventmodeling-checking-completeness
-description: >-
-  Step 8 of Event Modeling - Completeness Check. Verify every field has origin
-  and destination. Ensure complete event model before code generation. Use after
-  all scenarios defined. Do not use for: architectural validation against event sourcing
-  principles (use eventmodeling-validating-event-models) or elaborating
-  Given-When-Then specs (use eventmodeling-elaborating-scenarios).
+description: "Step 8 of Event Modeling - Completeness Check. Verify every field has origin and destination. Ensure complete event model before code generation. Use after all scenarios defined. Do not use for: architectural validation against event sourcing principles (use eventmodeling-validating-event-models) or elaborating Given-When-Then specs (use eventmodeling-elaborating-scenarios)."
 allowed-tools:
   - Write
 ---

plugins/trogonstack-eventmodeling/skills/eventmodeling-designing-event-models/SKILL.md

@@ -1,13 +1,6 @@
 ---
 name: eventmodeling-designing-event-models
-description: >-
-  Designs event-sourced domain models. Maps business processes to immutable
-  events and state projections. Events are the source of truth; state is
-  derived from events for command validation. Use when designing event streaming
-  architectures from domain analysis. Do not use for: brainstorming events from
-  scratch (use eventmodeling-brainstorming-events), optimizing stream sizing
-  or snapshotting (use eventmodeling-optimizing-stream-design), or translating
-  external system events (use eventmodeling-translating-external-events).
+description: "Designs event-sourced domain models. Maps business processes to immutable events and state projections. Events are the source of truth; state is derived from events for command validation. Use when designing event streaming architectures from domain analysis. Do not use for: brainstorming events from scratch (use eventmodeling-brainstorming-events), optimizing stream sizing or snapshotting (use eventmodeling-optimizing-stream-design), or translating external system events (use eventmodeling-translating-external-events)."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eventmodeling/skills/eventmodeling-elaborating-scenarios/SKILL.md

@@ -1,12 +1,6 @@
 ---
 name: eventmodeling-elaborating-scenarios
-description: >-
-  Step 7 of Event Modeling - Elaborate scenarios using Given-When-Then format.
-  Specify behavior of commands and views. Each spec tied to exactly one command
-  or view. Use after defining systems and boundaries. Do not use for:
-  architectural validation (use eventmodeling-validating-event-models) or
-  verifying field completeness across the model (use
-  eventmodeling-checking-completeness).
+description: "Step 7 of Event Modeling - Elaborate scenarios using Given-When-Then format. Specify behavior of commands and views. Each spec tied to exactly one command or view. Use after defining systems and boundaries. Do not use for: architectural validation (use eventmodeling-validating-event-models) or verifying field completeness across the model (use eventmodeling-checking-completeness)."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eventmodeling/skills/eventmodeling-identifying-inputs/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: eventmodeling-identifying-inputs
-description: >-
-  Step 4 of Event Modeling - Identify Commands/Inputs from UI and Processor
-  actions. Map user actions to commands and data. Use after storyboarding UI.
-  Do not use for: identifying read models or outputs (use
-  eventmodeling-identifying-outputs) or elaborating behavior specifications
-  (use eventmodeling-elaborating-scenarios).
+description: "Step 4 of Event Modeling - Identify Commands/Inputs from UI and Processor actions. Map user actions to commands and data. Use after storyboarding UI. Do not use for: identifying read models or outputs (use eventmodeling-identifying-outputs) or elaborating behavior specifications (use eventmodeling-elaborating-scenarios)."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eventmodeling/skills/eventmodeling-identifying-outputs/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: eventmodeling-identifying-outputs
-description: >-
-  Step 5 of Event Modeling - Identify Outputs/Read Models from events. Show
-  what data flows back to UI and Processors. Use after defining inputs. Do not
-  use for: identifying commands or inputs (use eventmodeling-identifying-inputs)
-  or verifying field completeness (use eventmodeling-checking-completeness).
+description: "Step 5 of Event Modeling - Identify Outputs/Read Models from events. Show what data flows back to UI and Processors. Use after defining inputs. Do not use for: identifying commands or inputs (use eventmodeling-identifying-inputs) or verifying field completeness (use eventmodeling-checking-completeness)."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eventmodeling/skills/eventmodeling-integrating-legacy-systems/SKILL.md

@@ -1,12 +1,6 @@
 ---
 name: eventmodeling-integrating-legacy-systems
-description: >-
-  Apply Event Modeling to legacy systems using side-car pattern. Freeze old
-  system, extract events, build new features without rewriting. Use when
-  modernizing legacy applications. Do not use for: greenfield systems without
-  existing legacy constraints (use eventmodeling-orchestrating-event-modeling)
-  or translating inbound events from external APIs (use
-  eventmodeling-translating-external-events).
+description: "Apply Event Modeling to legacy systems using side-car pattern. Freeze old system, extract events, build new features without rewriting. Use when modernizing legacy applications. Do not use for: greenfield systems without existing legacy constraints (use eventmodeling-orchestrating-event-modeling) or translating inbound events from external APIs (use eventmodeling-translating-external-events)."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eventmodeling/skills/eventmodeling-optimizing-stream-design/SKILL.md

@@ -1,12 +1,6 @@
 ---
 name: eventmodeling-optimizing-stream-design
-description: >-
-  Design event streams with proper stream identity to keep streams appropriately
-  sized, avoid unnecessary snapshotting, and balance performance with simplicity.
-  Use when concerned about stream length, planning performance, or validating
-  stream design before implementation. Do not use for: designing the initial
-  event model structure (use eventmodeling-designing-event-models) or
-  general architectural validation (use eventmodeling-validating-event-models).
+description: "Design event streams with proper stream identity to keep streams appropriately sized, avoid unnecessary snapshotting, and balance performance with simplicity. Use when concerned about stream length, planning performance, or validating stream design before implementation. Do not use for: designing the initial event model structure (use eventmodeling-designing-event-models) or general architectural validation (use eventmodeling-validating-event-models)."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eventmodeling/skills/eventmodeling-orchestrating-event-modeling/SKILL.md

@@ -1,14 +1,6 @@
 ---
 name: eventmodeling-orchestrating-event-modeling
-description: >-
-  Orchestrates complete event modeling workflow from requirements to code
-  generation. Models architecture as UI/Processor → Command → Event → Read
-  Model. Use when modeling a domain end-to-end from requirements. Do not use
-  for: executing a single step in isolation (invoke the named step skill
-  directly, e.g., eventmodeling-brainstorming-events for Step 1 or
-  eventmodeling-elaborating-scenarios for Step 7), validating an
-  already-completed model (use eventmodeling-validating-event-models), or
-  modernizing legacy systems (use eventmodeling-integrating-legacy-systems).
+description: "Orchestrates complete event modeling workflow from requirements to code generation. Models architecture as UI/Processor → Command → Event → Read Model. Use when modeling a domain end-to-end from requirements. Do not use for: executing a single step in isolation (invoke the named step skill directly, e.g., eventmodeling-brainstorming-events for Step 1 or eventmodeling-elaborating-scenarios for Step 7), validating an already-completed model (use eventmodeling-validating-event-models), or modernizing legacy systems (use eventmodeling-integrating-legacy-systems)."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eventmodeling/skills/eventmodeling-plotting-events/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: eventmodeling-plotting-events
-description: >-
-  Step 2 of Event Modeling - Arrange events chronologically in logical narrative
-  sequence. Create timeline showing event flow and dependencies. Use after
-  brainstorming events. Do not use for: brainstorming new events (use
-  eventmodeling-brainstorming-events) or designing command/read model
-  architecture (use eventmodeling-designing-event-models).
+description: "Step 2 of Event Modeling - Arrange events chronologically in logical narrative sequence. Create timeline showing event flow and dependencies. Use after brainstorming events. Do not use for: brainstorming new events (use eventmodeling-brainstorming-events) or designing command/read model architecture (use eventmodeling-designing-event-models)."
 allowed-tools:
   - Write
 ---

plugins/trogonstack-eventmodeling/skills/eventmodeling-slicing-event-models/SKILL.md

@@ -1,14 +1,6 @@
 ---
 name: eventmodeling-slicing-event-models
-description: >-
-  Break down complete event models into independently implementable feature
-  slices, identify dependencies, and plan parallel implementation across teams.
-  Use when planning team allocation, identifying MVP scope, or establishing
-  implementation order after completing event modeling. Do not use for:
-  organizational team structure based on Conway's Law (use
-  eventmodeling-applying-conways-law) or planning before the event model is
-  complete (complete the full model first using
-  eventmodeling-orchestrating-event-modeling).
+description: "Break down complete event models into independently implementable feature slices, identify dependencies, and plan parallel implementation across teams. Use when planning team allocation, identifying MVP scope, or establishing implementation order after completing event modeling. Do not use for: organizational team structure based on Conway's Law (use eventmodeling-applying-conways-law) or planning before the event model is complete (complete the full model first using eventmodeling-orchestrating-event-modeling)."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eventmodeling/skills/eventmodeling-storyboarding-events/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: eventmodeling-storyboarding-events
-description: >-
-  Step 3 of Event Modeling - Create UI storyboards/mockups showing what users
-  see at each step. Capture all data fields needed from user perspective. Use
-  after sequencing events. Do not use for: identifying commands or processor
-  actions (use eventmodeling-identifying-inputs) or designing read models
-  (use eventmodeling-identifying-outputs).
+description: "Step 3 of Event Modeling - Create UI storyboards/mockups showing what users see at each step. Capture all data fields needed from user perspective. Use after sequencing events. Do not use for: identifying commands or processor actions (use eventmodeling-identifying-inputs) or designing read models (use eventmodeling-identifying-outputs)."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eventmodeling/skills/eventmodeling-translating-external-events/SKILL.md

@@ -1,12 +1,6 @@
 ---
 name: eventmodeling-translating-external-events
-description: >-
-  Translate external system events (webhooks, APIs, IoT) into domain events.
-  Map technical data to business concepts. Use when integrating with external
-  systems that emit events your domain needs to react to. Do not use for:
-  modernizing legacy systems using the side-car pattern (use
-  eventmodeling-integrating-legacy-systems) or designing command handlers for
-  the translated events (use eventmodeling-designing-event-models).
+description: "Translate external system events (webhooks, APIs, IoT) into domain events. Map technical data to business concepts. Use when integrating with external systems that emit events your domain needs to react to. Do not use for: modernizing legacy systems using the side-car pattern (use eventmodeling-integrating-legacy-systems) or designing command handlers for the translated events (use eventmodeling-designing-event-models)."
 allowed-tools:
   - AskUserQuestion
   - Write

plugins/trogonstack-eventmodeling/skills/eventmodeling-validating-event-models-checklist/SKILL.md

@@ -1,12 +1,6 @@
 ---
 name: eventmodeling-validating-event-models-checklist
-description: >-
-  Validate event-sourced CQRS models against 16 architectural checks across
-  7 phases. Identifies anti-patterns and confirms compliance with event sourcing
-  principles. Use when reviewing event models for production readiness or after
-  completing event modeling steps. Do not use for: reviewing incomplete or
-  in-progress models (use eventmodeling-validating-event-models), or for
-  elaborating new scenarios (use eventmodeling-elaborating-scenarios).
+description: "Validate event-sourced CQRS models against 16 architectural checks across 7 phases. Identifies anti-patterns and confirms compliance with event sourcing principles. Use when reviewing event models for production readiness or after completing event modeling steps. Do not use for: reviewing incomplete or in-progress models (use eventmodeling-validating-event-models), or for elaborating new scenarios (use eventmodeling-elaborating-scenarios)."
 allowed-tools:
   - Write
 ---