agent-skills: Instructions file for Codex

Contributing to catalyst-skills

This guide explains how to create, extend, and maintain agent skills for Catalyst by Zoho. Read this before submitting a PR.

---

Repository layout

skills/
  SKILL.md                          ← routing layer (do not add technical content here)
  {catalyst-service}/
    SKILL.md                        ← thin entry point: frontmatter + workflow + triggers + references table
    references/
      {topic}.md                    ← detailed technical content loaded on demand

The routing skills/catalyst-by-zoho/SKILL.md routes queries to service-level skills. Service skills route to reference files. Never inline detailed technical content in a SKILL.md — it gets loaded on every match and bloats the context window.

---

How Skills Load (3-Tier Model)

Every agent interaction with skills goes through three loading stages:

Tier	What loads	When
1 — Metadata	YAML frontmatter only (name, description, metadata)	Always — for every skill in the registry, on every request
2 — Body	Full SKILL.md markdown (How It Works, Triggers, Security Checklist, References table)	Only when the skill's description matches the user query
3 — References	Individual references/*.md files	Only when a step in How It Works explicitly loads one

Critical implication: The description field is the ONLY content available at routing time. Every product name, symptom phrase, error term, and common entry point that should trigger this skill MUST appear in the description. The ## Triggers section in the body is the fallback for agents that read the full SKILL.md, but it does not help with initial routing.

Do not put trigger context only in the body. If a user asks about busboy and busboy is not in the description, the skill won't trigger — even if it's in ## Triggers.

---

SKILL.md format

Every skills/{service}/SKILL.md must follow this structure exactly: