# Skill-MCP-Claude Analysis — 2026-05-17

## Summary

- **Skill count: 78** — down from 94 claimed in SCHEMA_V1.md and METADATA_AUDIT.md; 16 test-stub/artifact skills were purged per REMEDIATION_PLAN Fix 3.6 (verified complete). The three documentation files reporting 94 are stale.
- **Test suite: 432 passed, 0 failed** — a major increase from the TEST_BASELINE.md figure of 189 (7 new test files added). No regressions.
- **No catalog structural errors**: all 78 skill dirs contain both SKILL.md and `_meta.json`; zero JSON parse errors; zero dangling `depends_on`/`enhances` references.
- **One SKILL.md frontmatter name mismatch**: `skills/3d-building-advanced/SKILL.md` has `name: building-mechanics` in frontmatter but `_meta.json` has `name: 3d-building-advanced`.
- **All 8 required schema fields present in all 78 skills** (`name`, `description`, `tags`, `sub_skills`, `source`, `type`, `depends_on`, `enhances`); tag arrays universally non-empty (0 empty-tag skills, down from 50+).
- **Security posture is sound**: `is_safe_skill_name` and `validate_skill_path` applied on every skill-path read in `server.py`; all REMEDIATION_PLAN Tier 0–3 items verified closed.
- **`brainstorming` has a suspect `depends_on`**: lists `using-git-worktrees` as a dependency but the SKILL.md body has no reference to git worktrees.
- **COMPOSITION_MAP.md and SKILL_CLASSIFICATION.md** still reference the purged `building` and `forms` router skills which no longer exist as directories.

---

## 1. Catalog Health

### 1.1 Skill Directory Count

| Source | Claimed count | Actual count | Status |
|--------|--------------|--------------|--------|
| `ls -d skills/*/` | — | **78** | Ground truth |
| `SCHEMA_V1.md` (generated 2025-03-05) | 94 | 78 | STALE (-16) |
| `METADATA_AUDIT.md` | 94 | 78 | STALE (-16) |
| `TEST_BASELINE.md` (tests, not skills) | 189 | 432 | STALE (+243) |

The 16-skill delta is fully accounted for by Fix 3.6 (test artifact removal). Removed: `binary-import`, `binary-skill`, `safe`, `traversal-test`, `json-import`, `json-skill`, `import-me`, `renamed-skill`, `new-skill`, `my-new-skill`, `integration-test`, `no-skill-md`, `imported-skill`, `source-skill`. All verified absent.

### 1.2 Required Files

All 78 skill directories contain both `SKILL.md` and `_meta.json`. No missing files detected.

### 1.3 JSON Parse Errors

Zero. All 78 `_meta.json` files parse without error.

### 1.4 Required Fields (per `server.py:47` META_SCHEMA v1.2)

The current schema requires: `name`, `description`, `tags`, `sub_skills`, `source`, `type`, `depends_on`, `enhances`. All 78 skills contain all 8 required fields with no missing entries. All `type` values are from the valid set (`template`, `discipline`, `router`, `creative-engine`). Note: `SCHEMA_V1.md` documents only 5 required fields — it predates `type`, `depends_on`, and `enhances`.

Tags are now universally non-empty across all 78 skills (was ~50 empty-tag skills in the prior audit).

### 1.5 Name / Directory Mismatches

`_meta.json` `name` matches directory name in all 78 skills. One SKILL.md frontmatter diverges:

- `skills/3d-building-advanced/SKILL.md` line 2: `name: building-mechanics`. Directory is `3d-building-advanced`; `_meta.json` has `name: 3d-building-advanced`. Likely a legacy value from a rename.

### 1.6 Referential Integrity

Zero dangling references. Every entry in every `depends_on` and `enhances` list points to an existing skill directory (78 skills checked).

Questionable dependency: `brainstorming` lists `depends_on: ["using-git-worktrees", "writing-plans"]`. The `using-git-worktrees` dependency is not justified by the SKILL.md body, which covers design questioning and YAGNI with no mention of git worktrees. This inflates `get_skill_chain` output for `brainstorming`.

---

## 2. Per-Skill Review

This run covers 15 skills: 1 with a recent SKILL.md commit (`dashboard`, changed in commit `9caec85`), plus a cross-section of 14 from the audio, 3D/shader, GSAP, particles, postfx, discipline, and building clusters.

| Skill | Verdict | Note |
|-------|---------|------|
| `dashboard` | SOLID | Router SKILL.md is concise (1243 chars); routes charts/real-time/filtering sub-skills clearly; type=router is accurate. |
| `audio-reactive` | SOLID | 12 KB; clear "Use when" trigger; runnable Tone.js examples; `depends_on: [audio-analysis, audio-playback]` is accurate. |
| `algorithmic-art` | THIN | 19 KB with rich content but no "Use when" heading in body — trigger is frontmatter-only. `search_content` queries for "use when" won't surface it. |
| `shader-fundamentals` | SOLID | "Use when" clear; code examples cover uniforms, varyings, built-in variables; `enhances: [shader-noise, shader-sdf, shader-effects]` reflects learning progression accurately. |
| `r3f-fundamentals` | SOLID | Strong quick-start with canonical R3F setup; self-described as foundational; 10 KB with solid Canvas/camera/lighting coverage. |
| `gsap-scrolltrigger` | SOLID | 10 KB; clear trigger description; runnable ScrollTrigger examples; `depends_on: [gsap-fundamentals]` is accurate. |
| `particles-physics` | SOLID | 14 KB; R3F-idiomatic code; covers gravity, attractors, velocity fields; `depends_on: [particles-gpu]` is correct. |
| `postfx-bloom` | SOLID | Clear niche (UnrealBloomPass / selective bloom); concrete use-case list (cyberpunk, neon, magic); `depends_on: [postfx-composer]` is accurate. |
| `3d-building-advanced` | THIN | SKILL.md frontmatter `name: building-mechanics` disagrees with directory and `_meta.json` (see §1.5). Content (3 KB) is a compact overview delegating to reference files and scripts; the SKILL.md does not stand alone. |
| `mcp-builder` | SOLID | 9 KB; covers both Python/FastMCP and Node/TypeScript paths; "Use when" in description; tool naming guidance is concrete. Minor: heavy emoji use in body. |
| `systematic-debugging` | SOLID | 5-phase process structure is clear and actionable; code snippet for logging is practical; "Use when" in frontmatter description. |
| `test-driven-development` | SOLID | Clear RED-GREEN-REFACTOR framing; trigger in frontmatter; `type: discipline` is accurate. |
| `brainstorming` | THIN | Good process content, but `depends_on: ["using-git-worktrees", "writing-plans"]` — SKILL.md body has zero reference to git worktrees; dependency appears to be a metadata error. |
| `software-architecture` | SOLID | 9 KB; SOLID principles with before/after TypeScript examples; Clean Architecture layers; "Use when" present and specific; `tags: [process, planning, code-review]` are accurate. |
| `platform-building` | SOLID | 3.5 KB overview with mobile/VR/accessibility coverage; quick-start references scripts documented as existing; clear "Use when" trigger. |

---

## 3. MCP Server Contract

### 3.1 Skill Discovery

`server.py:23` sets `SKILLS_DIR = Path(__file__).parent / "skills"` and iterates it in `load_index()` (line 175). Skills without all required fields are skipped from the index (line 188) but their validation errors are still collected.

### 3.2 Registered MCP Tools (10 total)

| Tool | Function |
|------|----------|
| `list_skills(type, tags)` | Lists all skill domains with optional type/tag filter |
| `get_skill(name)` | Loads a skill's SKILL.md content |
| `get_sub_skill(domain, sub_skill)` | Loads a specific sub-skill reference file |
| `get_skills_batch(requests)` | Loads multiple skills in one call |
| `get_skill_chain(name)` | Resolves full dependency tree (BFS) |
| `search_skills(query, limit)` | Searches names, descriptions, tags, triggers |
| `search_content(query, limit)` | Full-text search across all SKILL.md and reference content |
| `reload_index()` | Reloads from disk; rebuilds full-text index |
| `get_stats()` | Returns uptime, tool call counts, recent searches |
| `validate_skills()` | Checks all skill metadata and file structure |

### 3.3 Security Coverage

`core/security.py` exports `is_safe_skill_name`, `validate_skill_path`, `validate_file_path`, `sanitize_description`, `validate_upload_file`. Applied in `server.py`:

- `_get_skill()` (lines 368, 376): `is_safe_skill_name` then `validate_skill_path`
- `_get_sub_skill()` (lines 407, 424): `is_safe_skill_name` then `validate_skill_path`
- `_get_skill_chain()` (line 462): `is_safe_skill_name`
- `_search_skills()` / `_search_content()`: query length clamped at 1000 chars / 100 words; limit clamped 1–100

No skill-path code path bypasses these validators. Security contract is intact.

### 3.4 Test Suite

```
============================= 432 passed in 1.97s ==============================
```

Prior baseline (TEST_BASELINE.md, 2026-03-05): 189 tests across 3 files. Current: 432 tests across 10 files. New files not in baseline: `test_api_index.py`, `test_app_helpers.py`, `test_audit.py`, `test_core_claude_cli.py`, `test_core_modules.py`, `test_core_utils.py`. Zero failures — no regressions, significant expansion.

---

## 4. Docs Accuracy

| Document | Central Claim | Reality | Status |
|----------|--------------|---------|--------|
| `SCHEMA_V1.md` | 94 files; 5 required fields | 78 files; 8 required fields | STALE — count off by 16; schema 3 fields behind |
| `METADATA_AUDIT.md` | 94 total skills; lists stub skills as present | 78 skills; all stubs removed | STALE — count and skill list no longer match |
| `TEST_BASELINE.md` | 189 tests across 3 files | 432 tests across 10 files | STALE — count off by +243; 7 new test files undocumented |
| `REMEDIATION_PLAN.md` | All Fix 0.1–3.6 marked DONE | Verified: stubs removed, security applied, schema migrated | ACCURATE |
| `COMPOSITION_MAP.md` | Lists `building` and `forms` as router skills | Both directories no longer exist | STALE — references removed skills |
| `SKILL_CLASSIFICATION.md` | Lists skills including all 14 removed stubs | 14 stubs no longer in catalog | STALE — stub skills still listed |
| `SECURITY_REVIEW_FINDINGS.md` | All critical/high issues marked FIXED | Verified in `server.py` and `core/security.py` | ACCURATE |
| `FUTURE.md` | SDLC gaps: cicd, monitoring, feedback; router rethink | Still valid — no new skills in those areas | ACCURATE |
| `.claude/context/progress.md` | Last updated 2026-01-31; predates remediation | Python stack has since had 243 more tests added, all remediations completed | PARTIALLY STALE |

### Open REMEDIATION_PLAN Items

None. All Tier 0–3 items verified closed. Excluded-from-scope items (tag normalization, router architecture, HTTPS, performance monitoring) remain as acknowledged future work.

---

## 5. New Skill Ideas

### 5.1 `ci-pipeline-builder`
**Description:** Use when setting up GitHub Actions, GitLab CI, or similar pipelines for test automation, deployment, and quality gates.
**Type:** `discipline`
**Enhances:** `test-driven-development`, `aws-skills`, `backend-dev-guidelines`
**Rationale:** FUTURE.md flags `cicd` as a zero-coverage SDLC phase. Strong implementation skills exist; no deployment automation layer does.

### 5.2 `observability-setup`
**Description:** Use when adding structured logging, distributed tracing, or metrics to a backend service. Covers OpenTelemetry, Prometheus/Grafana patterns, and error tracking (Sentry).
**Type:** `discipline`
**Enhances:** `backend-dev-guidelines`, `aws-skills`, `software-architecture`
**Rationale:** FUTURE.md flags `monitoring` as a zero-coverage SDLC phase. Complements `systematic-debugging` for production systems.

### 5.3 `r3f-lighting`
**Description:** Use when configuring three-point lighting, HDRI environment maps, area lights, or baked lighting in React Three Fiber. Covers PBR material responses and shadow setup.
**Type:** `template`
**Enhances:** `r3f-materials`, `r3f-fundamentals`, `postfx-bloom`
**Rationale:** The R3F cluster covers fundamentals, geometry, materials, Drei, and performance — but has no dedicated lighting skill. Lighting is a major quality differentiator in 3D scenes.

### 5.4 `audio-synthesis`
**Description:** Use when generating tones, melodies, effects, or procedural soundscapes with Tone.js or the Web Audio API oscillator stack. Complements audio-analysis (ingests audio) with audio production/generation.
**Type:** `template`
**Enhances:** `audio-reactive`, `audio-playback`, `algorithmic-art`
**Rationale:** The audio cluster covers analysis, playback, and reactive visuals but has no synthesis/generation skill — a clear gap for music tools, game sound, and generative audio art.

### 5.5 `e2e-testing`
**Description:** Use when writing end-to-end tests with Playwright or Cypress. Covers page object patterns, fixture setup, network mocking, and CI integration.
**Type:** `discipline`
**Enhances:** `test-driven-development`, `form-react`, `form-vanilla`, `frontend-dev-guidelines`
**Rationale:** FUTURE.md explicitly flags `e2e-testing` as fragile single-coverage. The existing TDD skill covers unit tests; E2E is a distinct discipline with different tooling and concerns.

### 5.6 `shader-post-integration`
**Description:** Use when composing multiple post-processing passes (bloom + chromatic aberration + vignette + custom GLSL) into a single EffectComposer pipeline with correct ordering and performance budgeting.
**Type:** `template`
**Enhances:** `postfx-composer`, `postfx-bloom`, `postfx-effects`, `shader-effects`
**Rationale:** The postfx cluster has individual effect skills but nothing covering multi-pass composition order, pass interaction (bloom before or after tone mapping), and performance trade-offs. A natural gap for complex visual pipelines.

---

## Diff vs Previous Report

No prior `docs/analysis/ANALYSIS-*.md` file exists. This is the inaugural entry in this directory.

Key changes vs `METADATA_AUDIT.md` (most recent structured audit, 2025-03-05):
- 16 test stub/artifact skills removed
- 3 new schema fields (`type`, `depends_on`, `enhances`) added to all remaining skills
- Tags now universally populated
- Test suite expanded from 189 to 432 tests across 10 files
- All 7 security hardening measures from the security review applied and verified

---

## Recommended Actions (ranked: severity × 1/effort)

| Priority | Action | Effort | Impact |
|----------|--------|--------|--------|
| P1 | Fix `skills/3d-building-advanced/SKILL.md` frontmatter line 2: change `name: building-mechanics` to `name: 3d-building-advanced` | Trivial | Eliminates the only name inconsistency in the catalog |
| P2 | Fix `skills/brainstorming/_meta.json` `depends_on`: remove `"using-git-worktrees"` | Trivial | Corrects dependency chain returned by `get_skill_chain("brainstorming")` |
| P3 | Update `SCHEMA_V1.md` to v1.2: correct skill count to 78, add `type`/`depends_on`/`enhances` to required fields | Low | Prevents future analysts from referencing a 16-skill-off baseline |
| P4 | Update `METADATA_AUDIT.md`: rerun audit against 78 current skills, remove stub references | Low | Eliminates confusion from stale stub references |
| P5 | Update `TEST_BASELINE.md`: document 432-test baseline across all 10 test files | Low | Prevents false regression alerts against the 189 baseline |
| P6 | Update `COMPOSITION_MAP.md` and `SKILL_CLASSIFICATION.md`: remove purged `building` and `forms` router entries | Medium | Keeps the composition map usable for skill discovery |
| P7 | Add a `## Use When` heading inside `algorithmic-art/SKILL.md` body (trigger is frontmatter-only) | Low | Improves `search_content` discoverability |
| P8 | Create `ci-pipeline-builder` and `observability-setup` skills | Medium | Closes the cicd and monitoring SDLC gaps documented in `FUTURE.md` |
