Skills Design Patterns - SKILL.md and Trigger Conditions

An Agent Skill packages instructions, references, scripts, and templates for a repeatable task. Codex initially sees Skill names and descriptions, then loads full instructions only when needed. This pattern is called progressive disclosure.

Basic structure

.agents/skills/docs-content/
├── SKILL.md
├── scripts/
├── references/
└── assets/

SKILL.md requires name and description.

---
name: docs-content
description: Create or update beginner-facing documentation pages and keep locale indexes synchronized.
---

# Procedure
1. Read the content rules.
2. Confirm the target section.
3. Write Japanese first.
4. Sync the English page.
5. Run link and harness checks.

Explicit and Implicit Activation

Codex can activate a Skill explicitly with $docs-content or implicitly when a request matches its description. Avoid broad descriptions. State the supported task and important exclusions at the beginning.

Storage Locations and Ownership

Repository Skills can live in .agents/skills/, personal Skills in $HOME/.agents/skills/, and administrator Skills in /etc/codex/skills. This repository keeps shared Skill policy in shared/skills/ and synchronizes runtime adapters.

Keep one responsibility per Skill. Split docs writing, blog writing, and CI repair into separate workflows. Package multiple related Skills into a Plugin only when distribution becomes necessary.

Design Checklist

Check that the description defines scope, steps have a clear completion condition, long references are separated, repeated operations become scripts, and no credentials or personal paths are included.

Next, Subagents design separates specialized work into independent contexts.