playbook/antigravity-awesome-skills/skills/skill-writer/references/design-principles.md

Design Principles

Write for agent behavior

• Use imperative instructions that tell the agent what to do.
• Put trigger language in the frontmatter description, not only in the body.
• Keep SKILL.md as a navigation layer when the skill has many modes.
• Put optional depth, examples, rubrics, and tool-specific details in references.

Keep the context budget healthy

• Prefer checklists, tables, and short decision rules over long essays.
• Do not duplicate the same rule in SKILL.md and references unless it is a safety-critical reminder.
• Include only files the agent may actually load during work.

Balance depth and concision

• Add detail where mistakes are costly, repeated, or hard to detect.
• Compress detail where the model already has general knowledge.
• Make every required artifact explicit: files, commands, reports, comments, commits, or validation outputs.

Safety and provenance

• Label risky, destructive, credential-handling, financial, medical, legal, or security guidance clearly.
• Preserve source provenance when adapting external content.
• Prefer safe commands and explicit prerequisites over remote execution shortcuts.