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

## Summary

- **78 skill directories** found; `SCHEMA_V1.md` and `METADATA_AUDIT.md` both claim 94 — a 16-skill gap from the Fix 3.6 stub cleanup that docs have not been updated to reflect.
- **All 78 dirs contain both SKILL.md and `_meta.json`** — zero missing-file violations.
- **Zero `_meta.json` parse errors** and zero missing required fields (`name`, `description`, `tags`, `sub_skills`, `source`, `type`).
- **1 SKILL.md frontmatter name mismatch**: `skills/3d-building-advanced/SKILL.md` declares `name: building-mechanics`, conflicting with the directory name and `_meta.json`.
- **17 non-string sub_skill entries** (objects instead of strings) in 4 skills — not a crash but violates the spirit of referential-integrity checking.
- **Test regression confirmed**: 332 passed, 100 errors vs baseline of 189 passed, 0 errors. All 100 errors trace to `ModuleNotFoundError: No module named 'fastmcp'`; the entire MCP server test suite (88 tests in `test_server.py`, 5 in `test_security.py`) is currently dark.
- **41 broken SKILL.md body reference paths** and **35 `_meta.json`/frontmatter description mismatches** flagged by the automated daily audit.
- All remediation items in `REMEDIATION_PLAN.md` are marked DONE; no open Tier 0–3 items.

---

## 1. Catalog Health

### 1.1 Skill Directory Count

| Source | Claimed | Actual | Delta |
|--------|---------|--------|-------|
| Filesystem (`ls -d skills/*/`) | — | **78** | — |
| `SCHEMA_V1.md` | 94 | 78 | -16 (stale) |
| `METADATA_AUDIT.md` | ~94 rows | 78 | -16 (stale) |
| `REVIEW_SUMMARY.md` | "80 skills validated" | 78 | -2 (stale) |

Fix 3.6 removed 14 stub/test skill directories. Docs pages recording 94 skills have not been updated.

### 1.2 Required Files per Skill Directory

All 78 skill directories contain both `SKILL.md` and `_meta.json`. Zero missing-file violations.

### 1.3 `_meta.json` Parse Errors

None. All 78 files parse cleanly.

### 1.4 Required Field Compliance

Using `server.py`'s `META_SCHEMA` required list (`name`, `description`, `tags`, `sub_skills`, `source`, `type`):

- **0 missing fields** across all 78 files. Every skill has all six required fields plus optional `depends_on` and `enhances`.

Note: `SCHEMA_V1.md` marks only `name` and `description` as required, making it out of date with the actual server enforcement.

### 1.5 Name-Directory Agreement

One mismatch found:

| Skill Dir | `_meta.json` `name` | `SKILL.md` frontmatter `name` | Problem |
|-----------|--------------------|-----------------------------|---------|
| `3d-building-advanced` | `3d-building-advanced` (correct) | `building-mechanics` | Frontmatter uses an outdated name |

### 1.6 Sub-skill Structural Issue (Non-String Entries)

Four skills have `sub_skills` arrays containing **objects** (with `name`, `file`, `triggers` keys) rather than bare strings. This is correct per schema, but the referential-integrity check cannot map their `name` values to top-level skill directories because they are internal label names:

| Skill | Non-String Entries | Label Names |
|-------|--------------------|-------------|
| `3d-building-advanced` | 3 | `multiplayer-networking`, `performance-at-scale`, `structural-physics-advanced` |
| `building-router` | 4 | `performance`, `physics`, `multiplayer`, `terrain` |
| `dashboard` | 3 | `charts`, `real-time`, `filtering` |
| `forms-router` | 7 | `accessibility`, `validation`, `security`, `react`, `vue`, `vanilla`, `ux-patterns` |

The `references/*.md` files pointed to by all 17 entries do exist on disk — no sub-skill file is missing. The label names `structural-physics-advanced` (not a real directory; the actual skill is `structural-physics`) and `performance-at-scale` (a real directory) are inconsistently named.

### 1.7 Referential Integrity (`depends_on`, `enhances`)

All `depends_on` and `enhances` values are strings. All referenced skill names resolve to existing directories. Zero dangling references.

### 1.8 SKILL.md Frontmatter vs `_meta.json` Agreement

- **1 name mismatch**: `3d-building-advanced` (detailed above, `server.py:66` catches this at load time and logs a validation error but still loads the skill).
- **35 description mismatches**: Catalogued in `reports/2026-05-18.md`. Most are truncation-level differences. A minority are substantively different — e.g., `brand-guidelines` meta says "Access Anthropic official brand identity..." vs frontmatter "Applies Anthropic's official brand colors and typography...". Because `server.py` indexes `_meta.json` descriptions for search, the often-superior frontmatter description is invisible to MCP search.

### 1.9 Broken Internal References

41 error-severity broken references (references/*.md paths cited in SKILL.md bodies that do not exist on disk), across 21 skills. Full list in `reports/2026-05-18.md` rows 9–49. Notable clusters: the entire form-* cluster (9 skills, 16 broken links), R3F cluster (5 skills, 11 broken links), shader cluster (4 skills, 6 broken links).

---

## 2. Per-Skill Review

This run reviews 15 skills: the 2 touched in the most recent commits (`audio-analysis` changed 2026-05-18, `algorithmic-art` changed 2026-05-17) plus 13 from a rotating sample spanning all four types.

| Skill | Type | Verdict | Note |
|-------|------|---------|------|
| `audio-analysis` | template | **SOLID** | Clear "Use when extracting audio data..." trigger; good FFT/waveform code examples using Tone.js API; 465 lines, well-organized. Tags corrected to `["audio","javascript","code-generation"]` in latest commit. No broken references. |
| `algorithmic-art` | creative-engine | **THIN** | Tags `["3d","shaders","glsl","design"]` are categorically wrong — skill is p5.js generative art, not Three.js shaders. `enhances` chain (`shader-fundamentals`, `shader-noise`) also reflects this category error. Two-phase philosophy-then-code structure is well-documented but metadata misleads search. |
| `forms-router` | router | **SOLID** | "Use when creating forms..." trigger is direct. Routes to 7 leaf skills. 105 lines, compact. `_meta.json` description shorter than frontmatter (automated truncation artifact). Automated audit recommends deprecating the router since all leaves have strong standalone descriptions — worth evaluating. |
| `shader-fundamentals` | template | **SOLID** | Clear scope ("The foundational skill for all shader work"). 401 lines of GLSL fundamentals. `enhances` correctly chains to `shader-noise`, `shader-sdf`, `shader-effects`. Two broken references in body (`references/builtin-functions.md`, `references/coordinate-spaces.md`). |
| `r3f-fundamentals` | template | **SOLID** | Strong description enumerating 5 concrete trigger scenarios. 472 lines with Canvas, scene hierarchy, lighting. Two broken references (`canvas-props.md`, `event-system.md`). Tags and `enhances` accurate. |
| `gsap-fundamentals` | template | **SOLID** | 493 lines of core GSAP. "Use when implementing basic animations" trigger clear. `enhances` chain accurate. No broken references. |
| `brainstorming` | discipline | **SOLID** | "Use when starting any feature, project, or design work" — highly discoverable. 139 lines. Concrete incremental-questioning process. `enhances` `writing-plans`, `doc-coauthoring`. No redundancy. |
| `systematic-debugging` | discipline | **SOLID** | "Use when encountering any bug, test failure, or unexpected behavior" — unambiguous. 139 lines. Scientific method approach well-articulated. No issues. |
| `test-driven-development` | discipline | **SOLID** | "Use when implementing any feature or bugfix, before writing implementation code" — correctly positioned. 95 lines. Strict RED-GREEN-REFACTOR discipline. `enhances` is empty; `systematic-debugging` would be a natural addition. |
| `software-architecture` | discipline | **SOLID** | 402 lines covering Clean Architecture and SOLID. "Use when designing systems, reviewing architecture" is clear. `enhances` chain accurate. |
| `mcp-builder` | template | **SOLID** | 236 lines. "Use when building MCP servers" trigger specific. Tags (`meta-tooling`, `typescript`, `scaffolding`) accurate. `enhances` is empty; `software-architecture` would be a natural addition. |
| `skill-creator` | template | **THIN** | 356 lines but 9 broken body references (`scripts/rotate_pdf.py`, `references/finance.md`, `references/mnda.md`, etc.) — these appear in illustrative example content but generate noise in the audit. Description diverges between meta and frontmatter; frontmatter version is more accurate. |
| `component-library` | template | **SOLID** | Frontmatter description excellent (enumerates 6 concrete use cases). 221 lines with shadcn/ui, CVA, Radix UI. `enhances` well-chosen. Meta description significantly shorter than frontmatter — search quality degraded by the gap. |
| `d3js-visualization` | template | **SOLID** | 317 lines. "Use when building bar charts, line charts, scatter plots..." trigger explicitly enumerated. `enhances` `dashboard`. No broken references. |
| `subagent-driven-development` | discipline | **SOLID** | 180 lines. "Use when executing implementation plans" is a clear contextual trigger. Naturally positions after `writing-plans`. `enhances` chain correct. |

**Summary by verdict**: SOLID: 13, THIN: 2, STALE: 0, OVERLAP: 0.

---

## 3. MCP Server Contract

### 3.1 Skill Discovery

`server.py:23` sets `SKILLS_DIR = Path(__file__).parent / "skills"`. `load_index()` at line 165 iterates `SKILLS_DIR.iterdir()`, reads `_meta.json`, validates against `META_SCHEMA`, and populates `_INDEX["skills"]`. `build_content_index()` at line 103 additionally indexes `SKILL.md`, `references/*.md`, and `scripts/*.{md,py,js,ts,jsx,tsx}`. Discovery is correct and operational.

### 3.2 Registered MCP Tool Names (10 tools)

`list_skills`, `get_skill`, `get_sub_skill`, `get_skills_batch`, `get_skill_chain`, `search_skills`, `search_content`, `reload_index`, `get_stats`, `validate_skills` — all registered via `@mcp.tool()` in `server.py:770–893`.

### 3.3 Security Checks Applied on Skill-Path Code Paths

`core/security.py` implements `is_safe_skill_name` and `validate_skill_path`. Both are applied correctly:

- `_get_skill()` (`server.py:368–376`): `is_safe_skill_name(name)` then `validate_skill_path(skill_dir)`.
- `_get_sub_skill()` (`server.py:407–424`): `is_safe_skill_name(domain)` then `validate_skill_path(file_path)`.
- `_get_skill_chain()` (`server.py:463`): `is_safe_skill_name(name)`.

No bypass surfaces identified. All filesystem-touching paths are gated.

### 3.4 Test Suite Results

**Run: 2026-05-18 — `python3 -m pytest -q`**

```
332 passed, 100 errors in 2.47s
```

**Baseline (`TEST_BASELINE.md`, 2026-03-05): 189 passed, 0 errors**

The 143 additional passing tests come from new test files added after the baseline: `test_api_index.py` (55 tests), `test_app_helpers.py` (7), `test_audit.py` (33), `test_core_claude_cli.py` (26), `test_core_modules.py` (34 net), `test_core_utils.py` (21 net), plus expanded `test_security.py`.

**All 100 errors are a single root cause**: `ModuleNotFoundError: No module named 'fastmcp'`. The `server_module` fixture at `tests/conftest.py:310` does `import server`, which immediately fails at `server.py:2` (`from fastmcp import FastMCP`). `fastmcp>=0.1.0` is in `requirements.txt` but not installed in the test environment. This makes the following test classes fully dark:

- `test_server.py`: all 95 errors (88 tests that were passing at baseline, plus 7 new).
- `test_security.py`: 5 errors (`TestServerPathTraversal` 3 tests + `TestServerShutdown` 2 tests).

**This is a regression against baseline intent**: the 88 MCP server behavioral tests documented in `TEST_BASELINE.md` as all-PASS are now all-ERROR.

---

## 4. Docs Accuracy

| Document | Status | Key Issues |
|----------|--------|-----------|
| `SCHEMA_V1.md` | **STALE** | Claims 94 skills (actual: 78); lists only `name`/`description` as required (actual: 6 required fields); omits `type`, `depends_on`, `enhances`; still calls 4 skills "missing source" when all 4 now have it |
| `METADATA_AUDIT.md` | **STALE** | Contains ~94 rows including 16 deleted skills; no `type`/`depends_on`/`enhances` columns |
| `TEST_BASELINE.md` | **PARTIALLY STALE** | Baseline is 189 tests from 2026-03-05; suite now has 432 items; 100-error regression not documented |
| `REMEDIATION_PLAN.md` | **ACCURATE** | All Tier 0–3 items marked DONE; accurately reflects codebase state |
| `SECURITY_REVIEW_FINDINGS.md` | **ACCURATE** | All critical/high fixes confirmed applied; findings remain valid as historical record |
| `SKILL_CLASSIFICATION.md` | **MOSTLY STALE** | Lists 12 router skills including `building` and `forms` (both deleted); actual router count is 10 |
| `COMPOSITION_MAP.md` | **PARTIALLY STALE** | References deleted `building` and `forms` in the Routers table; `multiplayer-building` misclassified as discipline |
| `FUTURE.md` | **ACCURATE** | All items genuinely open; SDLC gap skills still absent from catalog |
| `REVIEW_SUMMARY.md` | **STALE SNAPSHOT** | Shows unresolved Critical/High issues that were subsequently fixed; "80 skills" claim is stale |

---

## 5. New Skill Ideas

| Proposed Name | Description | Type | Enhances |
|---------------|-------------|------|---------|
| `github-actions` | CI/CD workflow authoring for GitHub Actions: job matrices, caching, deploy workflows, reusable workflows. Fills the cicd SDLC gap from `FUTURE.md`. | template | `test-driven-development`, `software-architecture`, `aws-skills` |
| `observability-setup` | Instrumentation patterns: OpenTelemetry, structured logging, error tracking (Sentry), health-check endpoints. Fills the monitoring SDLC gap from `FUTURE.md`. | template | `backend-dev-guidelines`, `aws-skills`, `mcp-builder` |
| `audio-synthesis` | Tone.js synthesis: oscillators, filters, effects chains, generative music. The audio cluster covers analysis/playback/reactivity but has no synthesis/generation leaf. | template | `audio-reactive`, `algorithmic-art` |
| `e2e-testing` | End-to-end test authoring with Playwright or Cypress: page object models, fixture management, CI integration, visual regression. Fills the testing SDLC gap from `FUTURE.md`. | template | `test-driven-development`, `github-actions`, `frontend-dev-guidelines` |
| `r3f-animation` | Animation patterns specific to React Three Fiber: `useFrame` loop, `@react-spring/three`, `framer-motion-3d`, GSAP-R3F integration. The R3F cluster has no animation-focused leaf skill. | template | `r3f-fundamentals`, `gsap-react`, `r3f-performance` |
| `api-design` | RESTful and GraphQL API design: resource modeling, pagination, versioning, error schemas, OpenAPI documentation. Complements `backend-dev-guidelines` at the contract layer. | discipline | `backend-dev-guidelines`, `mcp-builder`, `software-architecture` |

---

## Diff vs Previous Report

No previous `docs/analysis/ANALYSIS-*.md` exists — this is the first report in this directory. Compared to the automated daily audit (`reports/2026-05-18.md`) which serves as the closest prior baseline:

- Skill count unchanged at **78**.
- Type distribution unchanged: creative-engine=3, discipline=13, router=10, template=52.
- `audio-analysis` `_meta.json` updated in commit `fc02c4a` (2026-05-18): added `last_reviewed_at`, `review_score`, `relevance_tier` fields.
- `algorithmic-art` `_meta.json` updated in commit `5ae6867` (2026-05-17): same review metadata fields added.
- GitHub Actions workflow (`skills-audit.yml`) added for automated daily audit.
- No skills added or removed since the most recent daily audit.

---

## Recommended Actions

Ranked by severity × (1/effort):

| Priority | Action | Severity | Effort |
|----------|--------|----------|--------|
| 1 | **Install `fastmcp`** in CI/test environment (`pip install fastmcp`) — 100 errors disappear; 88 MCP server tests become active again | Critical | Trivial |
| 2 | **Fix `3d-building-advanced/SKILL.md` frontmatter `name`**: change `building-mechanics` → `3d-building-advanced` | High | Trivial |
| 3 | **Create 41 missing reference stubs** (form-* cluster 16 links, R3F cluster 11 links, shader cluster 6 links, others 8 links) | High | Medium |
| 4 | **Fix `algorithmic-art` tags**: replace `["3d","shaders","glsl","design"]` with `["generative-art","p5js","javascript","creative-engine"]` | Medium | Trivial |
| 5 | **Update `SCHEMA_V1.md`**: correct skill count to 78, add `type`/`depends_on`/`enhances` field definitions, remove "missing source" observations | Medium | Low |
| 6 | **Update `METADATA_AUDIT.md`**: remove 16 deleted skill rows, add `type` column | Medium | Low |
| 7 | **Sync 35 description mismatches**: for each, choose one canonical description and copy to both `_meta.json` and SKILL.md frontmatter | Medium | Medium |
| 8 | **Archive/update `REVIEW_SUMMARY.md`**: it still shows "2 Critical remaining" that were fixed | Low | Trivial |
| 9 | **Update `TEST_BASELINE.md`**: document 432-item suite, current 332-pass/100-error split, root cause | Low | Low |
| 10 | **Add `r3f-animation` and `audio-synthesis` skills** | Low | High |
