Resolves#712 and #714.
Claude Code's plugin spec (code.claude.com/docs/en/plugins-reference) requires
"All paths must be relative to the plugin root and start with ./". CC 2.1.144+
rejects the bare "skills" form with `Validation errors: skills: Invalid input`,
breaking plugin installs from this repo.
Changes:
- 47 plugin.json manifests migrated from "skills": "skills" → ["./skills"]
(canonical post-CC 2.1.144 form, also accepts string "./skills")
- scripts/check_plugin_json.py rewritten to enforce the live spec:
* Hard-fails on non-"./"-prefixed strings (except the legacy "skills" literal)
* Hard-fails on empty strings/arrays and non-string array entries
* Emits WARN (non-fatal) on the legacy "skills" literal as a safety net
for copied templates — the WARN tolerance can be removed later
* Tested against all four canonical forms + 3 garbage forms
- CLAUDE.md §5 rewritten to document the live spec, including the historical
context of the v2.1.107 → v2.1.144 regression window that's now closed
- 15 stale broken symlinks under .gemini/skills/ removed (orphans from older
reorgs that the sync script didn't prune because its cleanup is disabled)
Verification:
- scripts/check_plugin_json.py --all → 0 FAIL, 0 WARN, exit 0 (69 files OK)
- pytest tests/ → 2103 passed
- find . -type l ! -exec test -e {} \; → 0 broken symlinks
- Live spec forms tested: ["./"], ["./skills"], "./skills", ["./a","./b"] all pass
- Garbage forms rejected: bare "./", empty array, non-string entries, plain strings
Claude Code 2.1.133+ rejects "skills": "./skills" with a "Path escapes
plugin directory" warning, even though ./skills resolves to a valid
subdirectory inside the plugin root. Per the upstream docs example, the
correct value is "skills" (no ./ prefix), which works across all CC
versions and other tools (Codex, Gemini CLI, etc.).
Applied to all 47 plugin.json files that used "./skills"; updated
CLAUDE.md ClawHub publishing constraints to document the new convention
and reference the issue.
Karpathy-style review of commit 3806b9b (the prior PR commit) caught real
issues that I missed: agents weren't fully equipped per the optional but
recommended fields in the official sub-agents spec.
Changes:
- engineering/agenthub/agents/hub-coordinator.md: narrow Bash(node *) (too
broad per defense-in-depth) -> moved node into disallowedTools; add
maxTurns: 100 (orchestrators run long); add skills: agenthub:agenthub
(preload the plugin's own guidance into agent context)
- engineering-team/self-improving-agent/agents/memory-analyst.md:
add maxTurns: 30 to bound runaway analysis loops
- engineering-team/self-improving-agent/agents/skill-extractor.md:
add disallowedTools (rm/curl/wget) — agent has Write+Edit so defense-in-
depth applies; add maxTurns: 30
- engineering/karpathy-coder/agents/karpathy-reviewer.md: fix skills field
format from path-style "engineering/karpathy-coder" to spec-correct
namespaced name "karpathy-coder:karpathy-coder" (the path syntax is the
cs-* orchestrator template convention; the official sub-agents spec uses
skill names per code.claude.com/docs/en/sub-agents); add maxTurns: 30
All 6 plugin agents (4 here + 2 in playwright-pro from prior commit) +
the 1 user agent (tech-ingester) now have name + description + tools +
disallowedTools (where write-capable) + model + maxTurns. The skills:
field is set on agents that benefit from preloaded domain skill content.
Functional smoke tests post-fix:
- memory-analyst: PASS (2 turns, 25s, 24K tokens, found 1 real orphan)
- skill-extractor: PASS (0 tool uses, 34s, 17K tokens, generated correct
plan staying read-only with new disallowedTools in effect)
- karpathy-reviewer: PASS (verified in prior session, 28 tool uses)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per https://code.claude.com/docs/en/sub-agents, agents require YAML
frontmatter with name + description, and the field is `tools:` not
`allowed-tools:` (deprecated). Bare `Bash` allows any command including
curl/wget/rm, which violates defense-in-depth.
Changes:
- engineering/agenthub/agents/hub-coordinator.md: add full frontmatter
(name, description, tools allowlist for git/python/node/Agent,
disallowedTools for rm -rf / curl / wget / git push --force, model)
- engineering-team/self-improving-agent/agents/memory-analyst.md:
add frontmatter, read-only tools (Read, Glob, Grep)
- engineering-team/self-improving-agent/agents/skill-extractor.md:
add frontmatter, write tools (Read, Write, Edit, Glob, Grep)
- engineering-team/playwright-pro/agents/test-architect.md:
rename allowed-tools to tools, add model: inherit
- engineering-team/playwright-pro/agents/migration-planner.md:
same rename
- engineering-team/playwright-pro/agents/test-debugger.md:
rename + narrow bare Bash to npx playwright / node / npm patterns,
add disallowedTools for rm / curl / wget / destructive git
- engineering/karpathy-coder/agents/karpathy-reviewer.md:
narrow bare Bash to git read-ops + python, add disallowedTools
All registered agents now load cleanly under the sub-agents spec rather
than falling through to permissive registration.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Claude Code v2.1.126 rejects "skills": ["./"] (array form) at runtime
with the same "Path escapes plugin directory: ./" error as the bare
string form, despite the official plugins reference docs explicitly
showing ["./"] as a valid example. `claude plugin validate` accepts it,
so the bug is in the runtime loader, not the manifest validator.
The proven workaround (already used for self-improving-agent in #536)
is to follow the canonical layout:
<plugin>/
├── .claude-plugin/plugin.json skills: "./skills"
└── skills/<plugin-name>/
├── SKILL.md
├── scripts/
├── references/
└── ...
Applied to 21 single-skill plugins:
- engineering-team/a11y-audit, google-workspace-cli, snowflake-development
- engineering/behuman, code-tour, data-quality-auditor, demo-video,
docker-development, helm-chart-builder, karpathy-coder, llm-cost-optimizer,
llm-wiki, prompt-governance, statistical-analyst, terraform-patterns
- finance/business-investment-advisor
- marketing-skill/video-content-strategist
- product-team/agile-product-owner, apple-hig-expert, code-to-prd,
research-summarizer
Moved with each SKILL.md: scripts/, references/, assets/, templates/,
expected_outputs/. Kept at plugin root (per Claude Code requirements):
agents/, commands/, hooks/, settings.json, README.md.
Bumped patch version on each restructured plugin so /plugin update
picks up the new layout.
Refs #539
PR #587 fixed `"skills": "./"` in 35 plugin.json files but did not bump
versions. Claude Code uses version as the cache key — same version string
means /plugin update is a no-op and users keep loading the cached
plugin.json with the broken path. The /plugin UI shows "1 error" on
every plugin from this marketplace because the installed cache is stale.
Per the official version-management docs:
> If you set `version` in `plugin.json`, you must bump it every time
> you want users to receive changes. Pushing new commits alone is not
> enough.
Bump every plugin.json by one patch using max(plugin_version,
marketplace_version) as the base so no version moves backward. Sync the
new versions back into .claude-plugin/marketplace.json.
After this lands, users run `/plugin marketplace update claude-code-skills`
followed by `/plugin update --all` to pull the fixed manifests.
Claude Code v2.1.107+ rejects bare "skills": "./" with "Path escapes
plugin directory: ./". This blocks every plugin in the marketplace from
loading. Replace with the layout-appropriate form per the official
plugins reference:
- Single-skill plugin (SKILL.md at root):
"skills": ["./"] array form (per docs example)
- Plugin with skills/ subdir:
"skills": "./skills" standard subdir layout
- Multi-skill domain plugin (skills are subfolders at root):
"skills": ["./sub1", "./sub2"] explicit list of skill dirs
The multi-skill case omits "./" from the array so the index SKILL.md
at the plugin root does not register as a skill — that would create
a redundant `marketing-skills:marketing-skills` namespace.
Verified by running `claude plugin validate` against all 35 manifests.
Closes#539
Implements Karpathy's 4 coding principles (Think Before Coding, Simplicity
First, Surgical Changes, Goal-Driven Execution) as an active enforcement
plugin, not just passive guidelines. Derived from Karpathy's X post on LLM
coding pitfalls but goes far beyond the source material with automated
detection tools, a review agent, and CI integration patterns.
Differentiator vs forrestchang/andrej-karpathy-skills (prompt-only, single
SKILL.md): this version ships real tooling that DETECTS violations instead
of just documenting principles.
Plugin contents (engineering/karpathy-coder/):
- SKILL.md with `context: fork` for skill chaining
- 4 Python tools (stdlib only):
- complexity_checker.py — cyclomatic complexity, class density, nesting
depth, function length, premature abstractions (Principle #2)
- diff_surgeon.py — diff noise ratio: comment-only changes, whitespace,
style drift, drive-by refactors, quote-style swaps (Principle #3)
- assumption_linter.py — detects "just", "obviously", "should work",
vague actions, unscoped users, missing format specs (Principle #1)
- goal_verifier.py — scores plan steps 0-3 for verification quality,
flags vague criteria, checks for final verification (Principle #4)
- 1 sub-agent: karpathy-reviewer (runs all 4 principles against a diff)
- 1 slash command: /karpathy-check (dispatches the reviewer)
- 1 pre-commit hook: karpathy-gate.sh (non-blocking, warns on violations)
- 3 reference docs: karpathy-principles.md (full context + when to relax),
anti-patterns.md (10+ before/after examples), enforcement-patterns.md
(Husky, pre-commit framework, GitHub Actions CI integration)
- .claude-plugin/plugin.json manifest (v2.3.0)
- Cross-tool compatible: works with any AGENTS.md-based CLI
All 4 scripts verified: --help passes, smoke tests run correctly.
complexity_checker catches its own nesting depth. assumption_linter
correctly flags "just", "obviously", "should work". goal_verifier
correctly scores plans with/without verification steps.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
