Agent Rules And Skill Author

Purpose

Create or revise repo-local agent rules and .agents-compatible skill packages without leaking project-specific instructions into the wrong layer.

When To Use

• The user asks to create, evaluate, rename, delete, or edit skills.
• The user asks to change AGENTS.md, manifests, validators, common/**, project/**, or skills/**.
• The user explicitly asks for user-facing README documentation changes.
• The screenshot-to-frontend pipeline rules, tool contracts, or skill routing need maintenance.

When Not To Use

• Updating an installed Kit from upstream releases: use webdev-kit-updater.
• The user asks to write a design implementation spec from screenshots. Use design-screenshot-spec.
• The user asks to implement a frontend layout from a spec. Use frontend-layout-implementer.
• The user asks to visually verify rendered UI. Use frontend-visual-qa.
• The user asks to adapt a new project in Plan Mode. Use project-onboarding-adapter.

Required Context

1. Read AGENTS.md.
2. Confirm the classified task is skill-documentation-refactor, documentation, or another .agents rule-maintenance task.
3. Read common/documentation-maintenance.md.
4. Read affected common/**, skills/**, project/**, manifests, validators, templates, examples, and root pointer files for the requested change.
5. Apply common/readme-policy.md: read targeted README sections when the request concerns README, public setup guidance, or docs/implementation drift; verify technical claims through higher evidence.
6. Read relevant references from this skill only when their topic is in scope.
7. Read current OpenAI Codex docs when native skill behavior, AGENTS.md, MCP, plugins, or agents/openai.yaml behavior may have changed.

Tool Contract

• Use filesystem reads and targeted search for local bundle facts.
• Activate openai_platform_docs when current OpenAI or Codex behavior affects the change; follow common/codex-official-docs-policy.md.
• Use context7 and mdn only when authoring rules depend on current framework or web platform behavior.
• Rule maintenance needs source/docs reads, not live Figma access. Encode live design intake through design-screenshot-spec and the capability manifest.

Workflow

1. Classify the target layer: AGENTS.md, manifests, validators, common/**, project/**, templates/**, examples/**, or skills/**.
2. Treat README as optional human-facing context, never runtime policy or validator truth. Do not edit it unless the current user explicitly requests that README change.
3. Confirm whether a new skill is needed or an existing skill/reference/common rule should be edited.
4. Define trigger surface, non-trigger cases, inputs, outputs, defaults, tool contract, failure modes, and validation gates.
5. Keep skill packages in the standard section order used by this bundle.
6. Keep graph frontmatter and Codex UI/invocation metadata synchronized; keep capability declarations in tool-capabilities-manifest.json.
7. Remove stale links after renames or deletions.
8. Validate changed skill packages and run documentation checks.

Output Contract

Final response: return only facts that affect the user's understanding, confidence, or next action. Omit empty fields and workflow narration.

Report:

• files changed;
• skill routing or trigger changes;
• tool dependency changes;
• validation performed;
• unresolved risks or blocked checks.

Validation Gates

• name and description stay first in SKILL.md frontmatter.
• Every skill has Purpose, When To Use, When Not To Use, Required Context, Tool Contract, Workflow, Output Contract, Validation Gates, Trigger Evals, and Reference Map.
• New references are linked from the owning SKILL.md.
• agents/openai.yaml matches skill UI and invocation policy. Only true hard client-tool dependencies belong there; optional providers belong in the capability manifest.
• Live design intake remains read-only, honors explicit role/tool preferences, and defaults to MCP-first with browser fallback. It adds no canvas writes or hard provider dependencies.
• README is not used as runtime policy, routing input, validator truth, or sole technical evidence, and is not edited without an explicit current user request.

Trigger Evals

Should trigger:

• "Create a new skill for visual QA."
• "Audit and rewrite the .agents skill routing."
• "Update AGENTS.md, manifests, and graph links for renamed skills."

Should not trigger:

• "Implement this Design Implementation Spec."
• "Compare the rendered page to the screenshot."
• "Write a layout spec from these screenshots."

Authoring Mode

Default to the source-bundle contract: native name and description plus local graph metadata. Use strict native-portable frontmatter only when the user explicitly requests a standalone skill outside this bundle.

Before material skill changes:

1. Use references/skill-design.md to choose the smallest correct intervention and package shape.
2. Use references/trigger-and-metadata.md to align the description, invocation policy, and agents/openai.yaml.
3. Use references/skill-quality-rubric.md for trigger and workflow evals.
4. Use references/rules-writing.md when policy scope or precedence changes.
5. Use references/documentation-maintenance.md for graph, manifest, rename, or publication changes.
6. Use references/validation-checklist.md before final reporting.

For new skills, use the local scaffolder only after the workflow, resources, compatibility target, and trigger boundary are defined. Keep examples and scripts only when they implement repeatable behavior.

Reference Map

• references/codex-native-skill-contract.md
• references/rules-writing.md
• references/skill-design.md
• references/skill-quality-rubric.md
• references/trigger-and-metadata.md
• references/validation-checklist.md
• common/readme-policy.md
• common/codex-official-docs-policy.md
• references/figma-derived-conventions.md
• references/source-backed-prompting.md
• references/documentation-maintenance.md

Behavioral Evidence Boundary

When editing the kit source repository, use its existing live scenario inventory and run_behavior_evals.py runner for changes that affect agent decisions. Installed host bundles need a separately authorized evaluation environment; never assume the source-only runner is shipped in the skill package. Preserve baseline/candidate traces under comparable client/model/effort settings and assess actual actions and file changes, not just the final answer. Static marker/schema checks and synthetic runner tests are not live model passes. For authorized executable tests follow common/test-policy.md: a missing import is structural failure, not proof of a behavior assertion. Record unrun live scenarios as unverified.