Inter-Skill References - Executive Summary

Inter-Skill References - Executive Summary

Date: 2025-11-30 Full Report: inter-skill-references-analysis-2025-11-30.md

Quick Stats

Severity Breakdown

┌─────────────────────────────────────┐
│ CRITICAL (Hard Dependencies): 8     │  █████████░░░░░░░░░░░░░░░░░░░░ 9%
│ - Break without referenced skills   │
├─────────────────────────────────────┤
│ MEDIUM (Soft References): 19        │  ███████████████████████░░░░░ 22%
│ - Informational, won't break        │
├─────────────────────────────────────┤
│ LOW (Self-Contained): 60            │  ████████████████████████████ 69%
│ - No inter-skill dependencies       │
└─────────────────────────────────────┘

Top 8 Critical Skills (Must Fix)

Total: 23 hard reference links that will break in flat deployment

Reference Types Found

Type 1: Hard Path Dependencies

Example: ../../frameworks/fastapi-local-dev/SKILL.md Problem: Assumes hierarchical structure, breaks in flat deployment Count: 23 links across 8 skills

Type 2: Soft References

Example: "See test-driven-development skill for workflow" Problem: Informational only, doesn't break functionality Count: 35+ mentions across 19 skills

Type 3: Hierarchical Parent/Child

Example: react → react/state-machine Problem: Explicit nesting structure Count: 2 explicit pairs, more implicit

Type 4: Progressive Disclosure (References Directory)

Example: references/integration.md links to other skills Problem: Not a problem - advanced content by design Count: 10+ skills with integration docs

Cross-Reference Patterns

Within Toolchains (Ecosystem)

Python Ecosystem:
pytest → fastapi-local-dev
pytest → test-driven-development
asyncio → fastapi-local-dev
pydantic → fastapi, sqlalchemy, django
mypy → pytest, fastapi, pydantic

Across Toolchains (Cross-Language)

TypeScript ← → JavaScript:
jest → react
vitest → react

Multi-Language:
MCP → typescript-core, python-core
WordPress → pytest (Python)

Toolchain → Universal

All Testing Tools → test-driven-development:
- pytest
- jest
- vitest

All Skills → systematic-debugging:
- pytest
- asyncio
- root-cause-tracing

Recommended Solution: Smart Bundling

Phase 1: Immediate (Stop the Bleeding)

✅ Stop adding new ../../ references ✅ Document skill reference convention ✅ Create self-containment checklist

Phase 2: Short-Term (Fix Critical)

🔧 Fix 8 high-severity skills 🔧 Inline critical snippets 🔧 Convert paths → skill names

Phase 3: Long-Term (Bundling)

📦 Create ecosystem bundles:

• python-testing-stack (pytest + TDD + debugging)
• typescript-data-stack (kysely + drizzle + migrations)
• react-ecosystem (react + state-machine + testing)

📦 Deploy universal skills always:

• test-driven-development
• systematic-debugging
• verification-before-completion

Before/After Example

❌ Current (Broken in Flat Deployment)

## Related Skills

- **[fastapi-local-dev](../../frameworks/fastapi-local-dev/SKILL.md)**: FastAPI patterns
- **[test-driven-development](../../../../universal/testing/test-driven-development/)**: TDD workflow

Problem: Paths break when deployed to ~/.claude/skills/pytest/

✅ Proposed (Self-Contained)

## Related Skills

When using pytest, consider these complementary skills:

- **fastapi-local-dev**: FastAPI server patterns and test fixtures
- **test-driven-development**: TDD workflow (RED/GREEN/REFACTOR)

> These skills can be deployed via: @skills/python/frameworks/fastapi-local-dev

## Quick TDD Reference

Since test-driven-development is commonly needed:

1. **RED**: Write failing test
2. **GREEN**: Make test pass (minimal code)
3. **REFACTOR**: Clean up while keeping tests green

[See full TDD workflow in test-driven-development skill if available]

Benefits:

• Works standalone (essential TDD info inlined)
• Graceful degradation (references other skills if available)
• No broken links

Impact of Full Self-Containment

Content Duplication Estimate

Trade-off: 385KB duplication vs. broken references

Recommendation: Smart bundling reduces duplication to <100KB

Next Actions

🔴 Priority 1 (Immediate)

1. Update CONTRIBUTING.md with no-../../-paths rule
2. Create skill reference style guide
3. Add self-containment to PR checklist

🟡 Priority 2 (Short-Term)

4. Fix 8 critical skills (pydantic, pytest, asyncio, jest, vitest, kysely, flask, mcp)
5. Create pilot bundle: python-testing-stack
6. Test bundling strategy

🟢 Priority 3 (Long-Term)

7. Implement full bundling for all ecosystems
8. Build skill discovery/suggestion system
9. Create deployment automation

Deployment Architecture (Proposed)

User Project Detected
        ↓
┌───────────────────┐
│ Toolchain Detect  │
└───────────────────┘
        ↓
    ┌───┴────┐
    ↓        ↓
Python?   TypeScript?
    ↓        ↓
Deploy:  Deploy:
├─ python-testing-stack    ├─ typescript-core
├─ python-frameworks       ├─ typescript-testing
├─ python-data            └─ typescript-data
└─ python-async

        ↓
┌───────────────────┐
│ Always Deploy     │
│ (Universal)       │
├─ TDD              │
├─ Debugging        │
├─ Verification     │
└─ Patterns         │
└───────────────────┘

Key Insights

1. 31% of skills have inter-references - significant but manageable
2. Only 9% are critical - 8 skills with hard dependencies
3. 69% are already self-contained - good foundation
4. Progressive disclosure works - references/ directories not the problem
5. Bundling is feasible - ecosystem groupings make sense

Success Criteria

✅ All skills deployable in flat structure without broken links ✅ Essential content inlined, advanced content in references/ ✅ Clear skill name references (no relative paths) ✅ Bundled ecosystems for common workflows ✅ Universal skills always available ✅ <100KB content duplication (via smart bundling)

Full Analysis: See inter-skill-references-analysis-2025-11-30.md for complete details, examples, and implementation roadmap.