/agent-rules-skill-author

name: agent-rules-skill-author
description: 'Maintain WebDev Agent Kit source rules, skills, metadata, and validators. Excludes upgrading installed copies.'
id: 'agents.skills.agent-rules-skill-author.skill'
title: 'Agent Rules And Skill Author'
doc_type: 'skill'
layer: 'skill'
status: 'active'
publishable: true
local_only: false
skill: 'agent-rules-skill-author'
tags:
    - 'agents/skill-package'
    - 'agents/authoring'
    - 'agents/skill'
parent:
    - '[[AGENTS|Canonical Agent Policy]]'
related:
    - '[[common/readme-policy|README Read And Edit Policy]]'
    - '[[common/rule-audit-findings|Rule Audit Findings]]'
    - '[[skills/agent-rules-skill-author/references/documentation-maintenance|Documentation Maintenance Workflow]]'
    - '[[skills/agent-rules-skill-author/references/codex-native-skill-contract|Codex Native Skill Contract]]'
    - '[[skills/agent-rules-skill-author/references/figma-derived-conventions|Figma Derived Conventions]]'
    - '[[skills/agent-rules-skill-author/references/rule-audit-checklist|Rule Audit Checklist]]'
    - '[[skills/agent-rules-skill-author/references/rules-writing|Rules Writing]]'
    - '[[skills/agent-rules-skill-author/references/skill-design|Skill Design]]'
    - '[[skills/agent-rules-skill-author/references/skill-quality-rubric|Skill Quality Rubric]]'
    - '[[skills/agent-rules-skill-author/references/source-backed-prompting|Source-Backed Prompting]]'
    - '[[skills/agent-rules-skill-author/references/trigger-and-metadata|Trigger And Metadata]]'
    - '[[skills/agent-rules-skill-author/references/validation-checklist|Validation Checklist]]'
    - '[[common/documentation-maintenance|Documentation Maintenance]]'
depends_on:
    - '[[AGENTS|Canonical Agent Policy]]'

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,