Imported from idaibin/skills (AGENTS.md). Install upstream with npx skills add idaibin/skills. Copyright stays with the author.

Agent Instructions

This file defines how AI agents should work on this repository. It is not the primary skill installation guide.

Task Routing

• For repository development, documentation edits, prompt edits, skill package edits, reviews, or commits, follow the repository work rules below.
• Only when the user explicitly asks to install Skills from this catalog's published source, read INSTALL.md and follow that installation flow.
• Do not switch into installation mode just because this repository contains skills/.
• Use repo-map for separate repository mapping, reuse inventory, or docs/code alignment.
• Use api-spec for native API contract design, revision, and OpenAPI validation after business semantics are accepted; route implementation and fixed-change review to their existing owners.
• Use domain-modeling when shared cross-functional business language or rules conflict; load lifecycle or bounded-context depth only when that shared ambiguity requires it. Route feature-local behavior and acceptance to product-spec.
• Use to-task when accepted Product/UI/architecture contracts or later findings need technical decomposition or reconciliation into a durable task ledger with dependencies, acceptance/evidence gates, status, blockers, and next action. It does not execute or schedule tasks. Use host planning for ephemeral reasoning that does not need a maintained task artifact.
• For concrete failures, follow the effective personal or repository diagnosis rules before permanent remediation; use the matching implementation skill only when a source change is requested.
• Use dev-frontend, dev-typescript, dev-java, or dev-rust for requested code changes according to the actual owner.
• Use repo-audit for bounded read-only frontend, Java, or Rust audits of existing surfaces without a change basis. Use repo-review for a fixed Worktree or immutable change basis, including changes involving authentication, authorization, secrets, untrusted input, or other security risks; assess those risks as part of the ordinary Standards axis.
• Use repo-review for read-only review of the current Worktree/index, a fixed immutable SHA/range, or a verified review package. Resolve pull requests to fixed base/head SHAs; apply Release only as a conditional profile over a fixed basis.
• Use ask-ai for local external-AI packages or explicitly authorized review, research, visual exploration, and decision challenge with ChatGPT, Gemini, DeepSeek, Kimi, or another named provider after the Codex-first gate; use ops-browser only for delegated low-level browser operations.
• Use repo-delivery for categorized commits by default, explicit single commits, pushes, evidence-based branch integration, cleanup, and other Git mutations.

Use .codex/ as the local task workspace. Store temporary files directly under one category parent as .codex/<category>/<type>-<YYYYMMDD-HHmmss>.<ext> using local time; use handoffs, reviews, artifacts, or tmp as the category and do not add task, type, or date subdirectories by default. Related review files share one timestamped prefix, such as .codex/reviews/ask-20260730-150931-package.md and .codex/reviews/ask-20260730-150931-response.md. These category directories are ignored. Put only explicitly approved, sanitized, durable handoffs or review evidence under the repository's established docs/ structure.

Repository Work Rules

• Before modifying files, read this file plus directly related docs and code.
• Run git status --short before edits.
• Keep changes scoped to the requested task and preserve unrelated local changes.
• Use existing structure, tools, naming, and style.
• Run validation that matches the change, or state why it could not be run.
• For add, reuse, move, rename, or delete work, keep source, package metadata, references, eval cases, root indexes, installation docs, and stale-name checks synchronized.

Project Structure

• skills/ contains publishable or reusable skill packages.
• skills-index.json is the repository-level semantic discovery and execution- boundary contract used by scripts/search-skills.py; portable runtime activation remains in SKILL.md. Its mutation class is the maximum owned boundary, not proof that every invocation performs that effect.
• scripts/validate-skills.py checks portable package structure, OpenAI metadata, local links, representative eval sections, semantic-index integrity, distribution hygiene, and catalog parity.
• scripts/run-skill-routing-evals.py executes the catalog-wide normal, nearest- boundary, and critical-stop matrix. CI resolves SKILLS_BASE_SHA (or the merge-base with origin/main) to an immutable commit and reads the published baseline there; missing or invalid base authority and any published base without its baseline fail closed.
• scripts/report-skill-context.py reports deterministic entrypoint and direct- reference context estimates as warnings; it does not claim exact model tokens or actual host loading behavior.
• scripts/sync-shared-protocols.py keeps identical self-contained package protocols synchronized from protocols/.
• scripts/test_*.py contains focused validator regressions.

When editing or adding skill packages under skills/, also read skills/AGENTS.md, docs/skills/skill-standard.md, and docs/standards/skill-routing.md. When a provider format changes, update the standard, validator, focused tests, and docs/quality/official-skill-alignment.md together.

Skill Validation

Use the validation matrix in skills/AGENTS.md. During iteration, run focused tests for the changed validator, protocol, route, or package plus exact-path git diff --check. Run the canonical full gate only for merge, release, catalog delivery, final fixed-basis acceptance, or an explicit full-regression request. For a behavior or quality claim, also run the fixed live-Agent cases required by docs/skills/skill-standard.md, capture actual trace/artifacts, and report selection, process, outcome/effect, stop honesty, and efficiency separately. Report any runtime or external behavior that was not exercised; syntax, package, and deterministic routing passes alone are not capability proof. Preserve any explicitly requested independent provider/model in its live case; absent or mismatched provider evidence is Not verified rather than an implicit exemption.