mirror of
https://github.com/alirezarezvani/claude-skills.git
synced 2026-08-28 04:24:58 +00:00
218b973f81
The user asked us to move everything from alirezarezvani/aeo-box into this
repo, audit every part, rebuild improved, polish for human users.
Audit identified 4 distinct components in aeo-box:
1. **AEO Skill** (`answer-engine-optimization/`) — 9 Python modules, 2,464
LOC, comprehensive SKILL.md. Real value: Answer Engine Optimization is
its own discipline distinct from SEO.
2. **Security-guidance hook** — David Dworken's MIT-licensed PreToolUse
hook catching 9 security anti-patterns in Edit/Write/MultiEdit. Hook-
based plugin pattern we don't have in our repo yet.
3. **Agentic AEO master prompt** — 1,579-line spec for a multi-agent
AEO application using Claude Agent SDK. Future-work spec.
4. **Generic dev infra** — 11 generic agents + 9 generic commands +
GH workflows + TS scripts. We already have equivalents; not worth
porting.
**This PR delivers 1, 2, and 3** (skipping 4 as planned).
## 1. AEO Skill — `marketing-skill/skills/aeo/`
Distilled 9-module Python toolkit into 3 stdlib CLI tools per
claude-skills convention:
- `aeo_audit.py` (445 LOC) — E-E-A-T + structure scoring across 4
dimensions + structure. Composite 0-100 with letter grade. 8 industries
with calibrated thresholds (healthcare/finance/legal 85+ for YMYL;
saas/b2b/media 70; ecommerce 65). Industry-aware top-fix
recommendations.
- `aeo_optimizer.py` (252 LOC) — Generates AEO-improved variants in 3
modes: conservative (schema + footer only), balanced (citation markers
+ heading restructure + schema), aggressive (fact-first lede + full
restructure). Schema.org Article + FAQPage JSON-LD auto-generated.
- `citation_tracker.py` (310 LOC) — Local-first citation ledger at
~/.aeo-data/citations.json. add/list/report/export actions. Computes
per-URL stats: citation count, LLM coverage, velocity, top queries,
verdict (EARLY/EMERGING/STRONG).
Plus:
- `SKILL.md` — Path-B-style spec with workflow, industry table,
anti-patterns, dependencies
- 3 references citing 8 sources each:
- `aeo_eeat_canon.md` — E-E-A-T methodology for AI citation
- `llm_citation_patterns.md` — per-LLM citation behavior
(Perplexity, ChatGPT, Claude, Gemini, Mistral)
- `aeo_vs_seo.md` — strategic choice between disciplines
- `cs-aeo` agent persona — pragmatic content strategist; refuses fake
authority signals; insists on real first-person evidence
- `/cs:aeo` command with audit/optimize/track/report/export actions
All 3 scripts smoke-tested:
- aeo_audit --sample → 43/100 (F) on intentionally-weak sample content
- aeo_optimizer --sample → schema injected + corrections footer added
+ bold-paragraphs promoted to H3 + 1 citation marker
- citation_tracker --sample → 4-event sequence (add → list → report
→ export), verdict EMERGING with 4 citations across 3 LLMs
## 2. Security-guidance hook — `engineering/security-guidance/`
PreToolUse hook ported from David Dworken's MIT implementation. Preserves
the 9 upstream patterns verbatim + adds 3 new patterns:
| Pattern | Upstream | Added |
|---|:-:|:-:|
| GitHub Actions workflow injection | ✓ | |
| child_process.exec / execSync | ✓ | |
| new Function | ✓ | |
| eval() | ✓ | |
| dangerouslySetInnerHTML | ✓ | |
| document.write | ✓ | |
| .innerHTML = | ✓ | |
| pickle | ✓ | |
| os.system | ✓ | |
| subprocess shell=True | | ✓ |
| SQL via f-string or .format | | ✓ |
| yaml.unsafe_load | | ✓ |
Modifications from upstream:
- Debug log moved from /tmp to ~/.claude/security-warnings-log.txt
(persists across reboots)
- Restructured as claude-skills plugin with `attribution` block in
plugin.json (matches caveman/grill-me/grill-with-docs pattern)
- Added comprehensive reference doc: pretooluse_hook_canon.md
(8 sources on hook design discipline)
Hook smoke-tested:
- eval(input()) in Write → exits 2 (BLOCK) with stderr warning ✓
- json.loads(input()) in Write → exits 0 (clean) ✓
- subprocess.run(cmd, shell=True) fresh session → exits 2 ✓
- subprocess.run(cmd, shell=True) cached session → exits 0 ✓
(correct UX: warned once, don't nag)
## 3. Master prompt preserved — `megaprompts/14-aeo-agentic-megaprompt.md`
The 1,579-line multi-agent AEO application spec preserved verbatim as
megaprompts/14 — the next slot after 13-research-megaprompt.md. Path-B
option open for future "build the full agentic AEO app" work.
## Cross-platform sync
- marketplace.json: 55 → 57 plugins (`aeo` + `security-guidance`)
- .codex/skills-index.json: 303 → 305 entries (both new skills indexed)
- .codex/skills/: aeo + security-guidance symlinks created
- .gemini/skills-index.json: 353 → 355 entries
- .gemini/skills/aeo, .gemini/skills/security-guidance: directory mirrors
- .hermes/skills/claude-skills/: re-synced (now includes both new skills
with relative symlinks)
## What's NOT ported (intentional)
- 11 generic agents from aeo-box .claude/agents/ — we have equivalents
(cs-code-reviewer, cs-senior-engineer, cs-skill-author)
- 9 generic commands from .claude/commands/ — we have /git:cm /git:cp
/cs:write-a-skill, etc.
- GitHub workflow YAMLs — repo-specific
- TS scripts (auto-close-duplicates, backfill-duplicate-comments) — GH
issue management, not a skill
Documented this skip-list in the AEO SKILL.md `Source` block + the
security-guidance plugin.json `attribution` block.
## Honest BYO-sync clarifier for Hermes (folded in from prior work)
Earlier merged PR #678 upgraded Hermes Agent integration to first-class
technical support (committed .hermes/ tree, fixed sync script, relative
symlinks). The earlier docs sweep added an install/configure walkthrough
that wasn't in scope for that PR but caught a user-flagged gap. That doc
section is also in this commit (137 lines added to docs/integrations.md
covering: Hermes-itself install steps, first-run walkthrough,
configuration tips, 6 troubleshooting Q&A).
Verification:
- All 3 AEO scripts pass --help and --sample
- Security hook correctly exits 2 on detection, 0 on cached/clean
- All 3 cross-platform syncs ran clean
- marketplace.json: 57 plugins, all required fields, no duplicates
- 13 v2.7.0 + 13 new files for AEO + 6 new files for security-guidance
+ 1 megaprompt + 1 docs update
https://claude.ai/code/session_01FEUmeuYhmnxVFq7EZM8ZSw
|
||
|---|---|---|
| .. | ||
| skills/claude-skills | ||