Dev

[alirezarezvani]

Summary

Checklist

• Target branch is dev (not main — PRs to main will be auto-closed)
• Skill has SKILL.md with valid YAML frontmatter (name, description, license)
• Scripts (if any) run with --help without errors
• No hardcoded API keys, tokens, or secrets
• No vendor-locked dependencies without open-source fallback
• Follows existing directory structure (domain/skill-name/SKILL.md)

Type of Change

• New skill
• Improvement to existing skill
• Bug fix
• Documentation
• Infrastructure / CI

Testing

[github-actions]

🛡️ VirusTotal Security Scan

File	Analysis
engineering-full-page-screenshot.zip	Report

Scanned with 70+ antivirus engines

Automated by ghaction-virustotal

[claude]

PR Review — Dev merge (#581)

Note: This PR is already merged. This review is for tracking and future reference.

---

Summary

This PR adds two new POWERFUL-tier engineering skills (command-guide, full-page-screenshot), a significant enhancement to llm-cost-optimizer, four new marketing skill reference files and Python scripts, restructures self-improving-agent, and adds a marketing improvement plan doc.

---

Issues Found

🔴 Bug: Truncated description in skills-index.json

.codex/skills-index.json has a malformed description for command-guide:

{
  "name": "command-guide",
  "description": ">"
}

This is clearly a truncated/placeholder value. It should contain the actual skill description from SKILL.md. This breaks skill discoverability via Codex.

🔴 macOS-only fallback in full-page-screenshot.mjs

In captureViaProxy() (tile stitching path), the script calls sips to read tile dimensions:

const sipsOut = execSync(`sips -g pixelWidth -g pixelHeight "${tiles[0].path}"`, ...)

sips is a macOS-only utility. This will silently fail on Linux/Windows with a cryptic error. Since the SKILL.md says the tool has "zero external dependencies beyond Node.js 22+ and Chrome", this is a broken promise on non-macOS platforms. Consider using Python + PIL (already used for stitching) to read dimensions, or use a minimal pure-JS PNG header parser.

🟡 Undocumented CDP proxy dependency

The script references a hardcoded proxy at http://localhost:3456 (the PROXY_URL constant and isProxyRunning() helper), but:

• This proxy server is not included in the skill
• There's no documentation on how to set it up, what it is, or when it's needed
• Users who hit the "browser WebSocket held by proxy" path will get Cannot connect to Chrome and no proxy running. with no guidance

This fallback path either needs documentation or should be removed if the proxy is a separate, undocumented internal tool.

🟡 self-improving-agent removed from skills index without explanation

The PR deletes the self-improving-agent entry from .codex/skills-index.json while simultaneously restructuring the plugin (skills path changed to ./skills/). The skill still exists in the repo, but removing it from the index breaks Codex discoverability. The engineering skill count was decremented from 36→35 accordingly, which may not be the intent.

If this was intentional (the plugin restructure means the skill should be registered differently), that should be noted in the PR description.

🟡 command-guide SKILL.md references non-existent skills

The skill references many agents and skills that don't appear to exist in this library:

• tdd-guide, build-error-resolver, e2e-runner, refactor-cleaner, doc-updater
• verification-loop, tdd-workflow, strategic-compact, frontend-patterns, backend-patterns
• /skill-create, /learn, /build-fix

This may confuse users who try to invoke them. If these are intended as "example/aspirational" agents, they should be clearly labeled as such. If they're real, they need to be added to the library or the references removed.

🟡 SKILL_DIR unexplained in full-page-screenshot SKILL.md

The SKILL.md uses ${SKILL_DIR} in all script invocation examples:

node "${SKILL_DIR}/scripts/full-page-screenshot.mjs" --check

There's no explanation of how this variable is set. Users will need to substitute the actual path manually.

🟡 PR checklist not completed

None of the PR template checklist items were checked, including "Scripts run with --help without errors". The new Python scripts (content_quality_gates.py, ai_content_detector.py, ad_health_scorer.py) and the Node.js script should have been verified.

---

What Looks Good

llm-cost-optimizer rewrite is substantially improved — cleaner structure with a 3-mode classifier upfront, proactive flags table, failure modes section, and handoff triggers. The removal of the "Before Starting" Q&A and replacing it with a pre-classified mode selection is a meaningful UX improvement.

Python scripts (content_quality_gates.py, ai_content_detector.py, ad_health_scorer.py) are well-structured, follow the stdlib-only convention, include --demo flags, support --json output, and have good inline documentation. The burstiness/TTR approach in ai_content_detector.py is a solid deterministic heuristic.

Reference files (ai-citation-readiness.md, content-templates.md, copy-frameworks.md, scoring-system.md) are high-quality knowledge bases — specific, actionable, and well-organized.

full-page-screenshot.mjs core CDP logic is solid — the scroll container expansion, DOM stability detection, lazy-load triggering, and tile stitching approach are all technically sound for the happy path (macOS + direct CDP).

---

Suggested Follow-up

1. Fix the command-guide description in skills-index.json
2. Replace the sips call in full-page-screenshot.mjs with a cross-platform alternative
3. Document or remove the CDP proxy fallback path
4. Clarify the self-improving-agent indexing intent
5. Add a note in command-guide SKILL.md that agent references are examples, not installed skills