Skip to content

Rule Reference

SEC357lintai-ai-securityguidancequalitypreviewmarkdownwarn

Plugin agent: `hooks` in frontmatter

Plugin agent frontmatter sets `hooks`

Public lane
guidance
Category
quality
Provider
lintai-ai-security
Scope
per-file
Surface
markdown
Tier
preview
Severity
warn
Confidence
high
Detection
structural
Remediation
message only
How to read this lane

Advice-oriented guidance and maintainability review.

How to read this category

Contract, schema, or config correctness signal.

Activation Model

Preset Activation

These presets explain where this rule appears in the product experience.

Lifecycle

Preview Lifecycle Contract

State

preview

Promotion blocker

Plugin agent frontmatter can still include unsupported hook experiments, so the first release stays spec-guidance-only.

Promotion requirements

Needs corpus-backed precision review, external usefulness evidence, and completed stable checklist metadata.

Canonical note

Structural preview rule; deterministic today, but the preview contract may still evolve.

Nearby Signals

Related Rules

Why It Matters

SEC357 flags plugin agent markdown whose frontmatter sets hooks.

For shared plugin agents, this is a poor place to define hook behavior:

  • it mixes execution wiring into agent content
  • it makes review harder because content and runtime hooks are coupled
  • it conflicts with the plugin-agent boundary documented for Claude plugin agents

What Triggers

This rule applies only to plugin agent markdown surfaces and triggers on parsed frontmatter that contains the exact key:

  • hooks

Example that triggers:

yaml
---
hooks:
  on-save: ./hooks/review.sh
---

Examples that stay clean:

  • plugin agents without hooks in frontmatter
  • fixture-like paths under tests/, fixtures/, examples/, or samples/
  • ordinary SKILL.md content outside plugin-agent surfaces

False Positives

This rule now lives in the explicit guidance lane because some repos may still experiment with unsupported plugin metadata. The signal is structural policy guidance, not evidence that the hook itself is malicious.

Remediation

Remove hooks from plugin agent frontmatter and keep hook execution in plugin-level hook configuration instead.