update skills

.agents/skills/writing-great-skills/GLOSSARY.md

@@ -0,0 +1,40 @@
+# Instruction-Design Glossary
+
+Use these terms when they clarify a discussion about agent instructions. They are concepts, not a requirement to avoid ordinary synonyms. [SKILL.md](SKILL.md) owns the workflow and Codex invocation mechanics.
+
+## Discovery and cost
+
+- **Predictability:** comparable situations lead to consistent, task-appropriate decisions.
+- **Model-invoked:** available for automatic selection as well as explicit invocation.
+- **User-invoked:** explicitly selected; an explicit-only policy disables automatic selection, not required metadata.
+- **Description:** required frontmatter that summarizes capability and applicability; it is not the invocation-policy toggle.
+- **Context pointer:** a reference plus the condition for reaching its target.
+- **Context load:** tokens and attention spent on available metadata and loaded instructions.
+- **Cognitive load:** what the human must remember or decide to use the system.
+- **Router skill:** selects among genuinely distinct workflows or resources.
+- **Granularity:** how finely instructions are divided; each split must justify its discovery and maintenance cost.
+
+## Information hierarchy
+
+- **Steps:** ordered actions where sequence matters to the task.
+- **Reference:** definitions, constraints, or procedures consulted when relevant.
+- **External reference:** material outside the entrypoint, reached through an appropriate pointer.
+- **Information hierarchy:** the placement of essential actions and constraints versus conditional detail.
+- **Progressive disclosure:** loading supporting detail only when the task needs it.
+- **Co-location:** keeping a concept's definition, rules, and caveats together.
+- **Branch:** a distinct case or mode handled by the skill.
+
+## Execution and maintenance
+
+- **Leading word:** a compact, familiar concept that conveys a useful decision principle without repeated explanation.
+- **Completion criterion:** evidence that the requested outcome has been reached; it should be checkable and cover the important requirements.
+- **Legwork:** investigation needed to meet that criterion rather than transferring discoverable work to the user.
+- **Post-completion steps:** later actions that may distract from an unfinished prerequisite.
+- **Premature completion:** declaring a step or task done without meeting its criterion. Clarify the criterion before adding process.
+- **Negation:** wording framed around what to avoid. Prefer a clear positive target where possible while retaining necessary safety prohibitions.
+- **Single source of truth:** one authoritative home for a rule or fact.
+- **Duplication:** repeated meaning that must be maintained in several places.
+- **Relevance:** whether material still supports the skill's actual task.
+- **Sediment:** stale assumptions accumulated through updates.
+- **Sprawl:** more instruction volume than the task usefully needs.
+- **No-op:** wording that does not materially change the agent's decisions or work.

.agents/skills/writing-great-skills/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: writing-great-skills
+description: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.
+---
+
+# Writing Great Skills
+
+Write guidance that improves decisions while preserving the user's outcome, choices, and authority. Predictability means handling comparable situations consistently—not imposing the same ceremony on every task.
+
+## Codex mechanics
+
+Every skill needs YAML `name` and `description`. Keep the description concise: what the skill does, when it applies, and a boundary only where it prevents likely misrouting.
+
+Automatic discovery is the default. Set `policy.allow_implicit_invocation: false` in `agents/openai.yaml` for a new explicit-only skill only when the user requests it. Preserve existing invocation policies and unrelated UI/dependency fields.
+
+Do not use legacy `disable-model-invocation` or `argument-hint` frontmatter for Codex, or delete descriptions to change invocation. Discovery policy does not grant authority; check authorization at the relevant mutation.
+
+## Write only decision-changing guidance
+
+- State the intended outcome, non-obvious context, genuine constraints, and a recognizable completion condition.
+- Reuse explicit user choices and known context. Ask only for missing information that materially affects the task.
+- Match specificity to risk: fixed sequences belong in fragile workflows, not ordinary open-ended work.
+- Preserve authority boundaries. A review should not silently implement; a plan should not silently publish. Define stopping and retry behavior where failures or duplicate external writes matter.
+- Keep discovery specific. Avoid exhaustive synonym lists and generic triggers that attract unrelated tasks.
+
+## Arrange the information
+
+Keep shared purpose and essential constraints in the entrypoint. Move substantial mode-specific procedures behind a link that says when to read them. Keep simple skills self-contained; add a router only for meaningful branches.
+
+Use one authoritative home for each rule. Read the environment rather than copying readily discoverable configuration into instructions, except where a local gotcha is worth recording.
+
+Use [GLOSSARY.md](GLOSSARY.md) when discussing instruction-design concepts such as context load, progressive disclosure, or premature completion. It defines the vocabulary; this file owns the authoring workflow and Codex mechanics.
+
+## Validate and prune
+
+Check metadata with the target runtime's validator, confirm references are reachable, and run changed helpers with safe representative inputs. Test observable outcomes and invariants, not exact generated wording.
+
+For complex or risky behavior, use a scoped independent evaluation when delegation is available and authorized. Keep fixtures isolated from user work and avoid live side effects.
+
+Remove duplicated rules, stale assumptions, speculative scaffolding, and examples that do not clarify a real choice. Preserve safety and operational invariants even when shortening the text. If a task keeps failing, correct the demonstrated cause rather than adding universal ceremony.

.agents/skills/writing-great-skills/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Writing Great Skills"
+  short_description: "Principles for predictable skills"
+policy:
+  allow_implicit_invocation: false