SKILL.md Byte Cap and Trigger‑Rich Description Policy in the Diagram‑Design Repository

The SKILL.md file in cathrynlavery/diagram-design enforces a strict 40,000‑byte size limit and prohibits overly detailed front‑matter descriptions that could trigger unsafe parsing or packaging issues.

The diagram‑design skill defines visual diagram conventions for AI agents. To keep agent context lightweight and secure, the repository implements two hard constraints on its primary skill definition file. These checks run automatically via Python verification scripts that gate every contribution.

---

The 40,000‑Byte Cap on SKILL.md

The repository rejects any SKILL.md that exceeds 40,000 bytes. This limit is enforced in scripts/verify-semantic-motion.py.

Enforcement Logic

# scripts/verify-semantic-motion.py

MAX_SKILL_BYTES = 40_000

with open(skill_path, "rb") as f:
    skill_bytes = f.read()

if len(skill_bytes) > MAX_SKILL_BYTES:
    errors.append(
        f"SKILL.md exceeds {MAX_SKILL_BYTES} bytes: {len(skill_bytes)} bytes"
    )

Reading the file in binary mode ensures accurate byte counting regardless of encoding. The script fails CI if this check triggers, preventing oversized skills from bloating agent context windows.

Why This Limit Matters

• Performance: Agents load skills into limited context windows; large files degrade response latency.
• Predictability: Fixed caps allow deterministic token budgeting across different model providers.
• Maintainability: Forces concise, high‑signal documentation without redundant examples.

---

Trigger‑Rich Description Policy

The front‑matter description — the metadata section at the top of SKILL.md parsed before the markdown body — must stay within the Agent Skills limit and avoid unsafe packaging patterns. This policy is enforced in scripts/verify-docs-sync.py.

Policy Requirements

Rule	Implementation
Length bound	len(frontmatter_description) <= AGENT_SKILL_DESC_LIMIT
Safe paths only	No ../ traversal sequences allowed
Required fields	metadata.version, description, and schema‑compliant keys only

Enforcement Code

# scripts/verify-docs-sync.py (lines 149‑159)

if len(frontmatter_description) > AGENT_SKILL_DESC_LIMIT:
    errors.append(
        "SKILL.md frontmatter description exceeds the Agent Skills limit"
    )

# Disallow unsafe packaged support paths

if re.search(r'\.\./', link):
    errors.append(f"SKILL.md exposes unsafe packaged support path {link!r}")

What "Trigger‑Rich" Means

• Overly descriptive metadata: Lengthy natural‑language descriptions that attempt to embed behavioral triggers or conditional logic.
• Unsafe references: Links or imports that escape the skill's scoped directory.
• Embedded executable hints: Markdown that parsers might misinterpret as dynamic instructions.

The policy keeps descriptions declarative and static, ensuring agents consume them as configuration rather than executable code.

---

Key Files in the Validation Pipeline

File Path	Purpose
skills/diagram-design/SKILL.md	Skill definition containing front‑matter and visual‑type reference tables.
scripts/verify-semantic-motion.py	Validates the 40,000‑byte hard cap on total file size.
scripts/verify-docs-sync.py	Validates front‑matter description length and path safety.
README.md	Documents the skill structure and verification workflow.

Both scripts run as part of the repository's quality gates, blocking merges that violate either constraint.

---

Summary

• SKILL.md byte cap: 40,000 bytes enforced by verify-semantic-motion.py.
• Trigger‑rich description policy: Front‑matter must fit within Agent Skills limit, contain no ../ paths, and remain declarative — enforced by verify-docs-sync.py.
• Violations of either rule fail CI and prevent skill updates from merging.

---

Frequently Asked Questions

What happens if SKILL.md exceeds 40,000 bytes?

The verify-semantic-motion.py script raises an error and exits non‑zero, blocking the pull request. Contributors must reduce content — typically by moving extended examples to separate documentation files.

Where is the Agent Skills description limit defined?

The constant AGENT_SKILL_DESC_LIMIT is imported or defined within scripts/verify-docs-sync.py. This value is separate from the 40,000‑byte total file cap and specifically bounds only the front‑matter metadata section.

Can I include external links in the SKILL.md description?

External URLs are permitted, but relative paths containing ../ are rejected. The regex check r'\.\./' in verify-docs-sync.py catches directory traversal attempts that could expose files outside the skill package.

Why are there two separate verification scripts?

verify-semantic-motion.py handles file‑system and size constraints (binary read, byte counting). verify-docs-sync.py handles semantic and security constraints (YAML front‑matter parsing, path validation). Separation allows targeted failure reporting and independent rule evolution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}