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

[claude]

PR Review — #479 (Dev → Main)

Note: This PR is already merged. The following is a post-merge audit for tracking purposes and future reference.

---

Summary

This PR adds two new engineering-POWERFUL skills:

• behuman — Self-Mirror Consciousness Loop for more human-like AI responses
• code-tour — CodeTour .tour file generator for VS Code

Both are solid concepts. behuman in particular is well-executed with good examples, an evals file, and clear anti-patterns. code-tour provides a useful structured workflow. A few issues noted below.

---

Issues Found

🔴 Critical

1. SKILL.md frontmatter missing license field (both skills)

Per the PR checklist and CLAUDE.md, SKILL.md must have name, description, and license in YAML frontmatter.

engineering/behuman/SKILL.md:

---
name: "behuman"
description: "..."
# ❌ license field missing
---

engineering/code-tour/SKILL.md:

---
name: "code-tour"
description: "..."
# ❌ license field missing
---

Fix: add license: "MIT" to both.

---

🟡 Medium

2. docs/skills/engineering/index.md count is off

Two skills were added (behuman + code-tour) but the count only went from 51 → 52. Should be 53.

-<p class="domain-count">52 skills in this domain</p>
+<p class="domain-count">53 skills in this domain</p>

3. code-tour skill is incomplete compared to behuman

behuman ships with a full package: SKILL.md, evals.json, references/, plugin.json, docs page, and mkdocs nav entry.

code-tour is missing:

• docs/skills/engineering/code-tour.md — no MkDocs documentation page
• mkdocs.yml nav entry — not discoverable in the docs site
• .claude-plugin/plugin.json — no plugin manifest (can't be installed via claude /plugin install)
• evals.json — no test cases to validate trigger behavior

---

🟢 Minor

4. PR checklist left unchecked

All checklist items were left as [ ]. These should be checked before merging to confirm the contributor verified each item.

5. plugin.json author object includes non-schema field

CLAUDE.md defines the plugin.json schema as allowing only: name, description, version, author, homepage, repository, license, skills. The author object contains a url field:

"author": {
  "name": "Alireza Rezvani",
  "url": "https://alirezarezvani.com"  // ← not in spec
}

Consider flattening to "author": "Alireza Rezvani" to stay within the schema.

6. Content duplication between SKILL.md and docs page

engineering/behuman/SKILL.md and docs/skills/engineering/behuman.md are nearly identical. This creates a maintenance burden — updates must be made in two places. Consider whether the docs page should reference or summarize the SKILL.md rather than duplicating it, or if the docs generation should be scripted (as other skills appear to do via scripts/).

---

What Works Well ✅

• behuman/evals.json — 8 test cases covering both positive triggers and negative exclusions. Exactly the right approach for validating skill activation heuristics.
• Token cost table — clearly communicates the trade-off of running the 3-step loop vs. quiet mode.
• Anti-patterns table in both skills — specific and actionable, not generic.
• code-tour SMIG formula — useful structured approach (Situation, Mechanism, Implication, Gotcha) for step descriptions.
• code-tour validation checklist — the "every file/line must be verified" requirement prevents hallucinated tours.
• Symlinks and codex index correctly updated for both skills.
• behuman philosophy section — grounding in Kahneman's dual-process theory is a nice touch and gives the skill conceptual depth.

---

Suggested Follow-Up

• Add license: "MIT" to both SKILL.md files
• Fix engineering skill count to 53
• Create docs/skills/engineering/code-tour.md and add to mkdocs.yml
• Add engineering/code-tour/.claude-plugin/plugin.json
• Add engineering/code-tour/evals.json