skill-authoring

To create an offline-friendly Agent Skill, write a self-contained SKILL.md file with mandatory frontmatter fields (name, description) so it can be discovered and activated without external tooling. Use a flat directory structure with optional references, assets, and scripts to extend context.

Mandatory frontmatter for Agent Skill discovery requires at least the name and description fields. These fields enable reliable offline loading and predictable activation by allowing the agent to identify the skill and understand its trigger conditions.

The plan-validate-revise workflow ensures the ordinary execution path works from SKILL.md alone before adding optional assets. Authors first validate the core logic, then deepen context with references, assets, or scripts only when named blockers arise, keeping activation predictable.

Yes, optional directories like references, assets, and scripts extend the skill without breaking the ordinary path. The core workflow executes from SKILL.md alone, while these optional folders provide deeper context or templates only when specific blockers arise during execution.

The best way to structure a cross-platform Agent Skill is using a flat, self-contained directory with SKILL.md at the root. Add optional references, assets, and scripts folders as needed to handle named blockers or templates without mandatory external tooling.

Agent Skills fail to trigger offline if mandatory frontmatter fields are missing or if the ordinary path relies on external tooling. Ensure SKILL.md contains at least the name and description fields and that the core workflow is self-sufficient.