AGENTS.md — skills/

Purpose

Agent-callable skill modules. Each subdirectory is a self-contained skill that an agent can invoke via CLI or programmatic Python API to perform a specific task (progress tracking, handoff, DOM inspection, screenshot capture, error aggregation, etc.). Skills are the primary extension point for agent workflows.

Key Files

Internal Patterns

• One skill per directory — each skill is entirely self-contained; no skill may import another skill.
• SKILL.md is required — every skill directory must contain a SKILL.md describing its name, purpose, workflow, CLI usage, and programmatic API.
• Dual interface — skills expose both a CLI (python skills/<skill>/scripts/<cmd>.py) and a programmatic Python API for use in agent code.
• Append-only shared files — skills that write to docs/exec-plans/ use O_APPEND semantics or fcntl.LOCK_EX; never truncate or overwrite these files.
• Artifact paths are conventional — progress.md, debt.md, perf.md, shared-state.yaml are fixed paths; do not parameterise them unless the SKILL.md explicitly documents the override.
• No inter-skill dependencies — if two skills share logic, extract it into harness_skills top-level utilities, not into a shared skill module.

Domain-Specific Constraints

• Skills are agent-facing, not library code — they are designed to be invoked by an agent in a task session, not imported by framework code.
• shared-state.yaml is ephemeral — it lives only for the duration of a multi-agent session; never treat it as persistent storage.
• Screenshot artifacts must not be committed — screenshots/ and videos/ are gitignored; never stage files from these directories.
• dom-snapshot skill calls dom_snapshot_utility — it must go through the dom_snapshot_skill.py façade in harness_skills, not import dom_snapshot_utility directly, to maintain the boundary.
• context-handoff is write-once per session — call HandoffTracker.write() once at agent teardown; multiple calls per session create confusing duplicate entries.
• Principle SK001 — new skills must include a SKILL.md and at least one runnable CLI script before being considered complete.