Back to portfolio

Building a Claude Code Plugin Marketplace

8 min read View repo

The Problem

Claude Code is powerful out of the box, but every developer's workflow is different. Some teams need structured feature planning before writing code. Others need bulk refactoring across hundreds of files. Some want to generate architecture diagrams from their codebase. The challenge: how do you extend Claude Code's capabilities in a way that's reusable, composable, and natural to invoke?

What Are Skills?

Skills are model-invoked capabilities — unlike slash commands that require explicit user activation, Skills are automatically triggered by Claude based on context. Say "fix the failing tests" and the test-fixing skill activates. Say "push these changes" and git-pushing handles it.

Each Skill consists of a SKILL.md file with YAML frontmatter and detailed instructions. Skills can also include reference materials and helper scripts. The key insight is that the description is the activation trigger — write it like you'd describe the scenario to a colleague, and Claude will activate the skill when those scenarios arise naturally.

Architecture

The marketplace is organized as a collection of plugins, each containing related skills:

claude-skills-marketplace/
├── engineering-workflow-plugin/     # Git, testing, planning, code review
├── visual-documentation-plugin/    # Diagrams, dashboards, flowcharts
├── productivity-skills-plugin/      # Auditing, documentation, bootstrapping
├── code-operations-plugin/          # Bulk refactoring, file analysis
└── execution-runtime/               # Local Python execution for token savings

Skills and Agents work together: the feature-planning skill creates a detailed implementation plan, then hands off each task to the plan-implementer agent for execution. This separation means planning uses the full Opus model for strategic thinking, while implementation runs on Haiku for cost efficiency.

The Execution Runtime: 97% Token Savings

The most impactful addition was the execution runtime, implementing Anthropic's code execution pattern. Instead of Claude reading and editing 50 files through the context window (burning ~25,000 tokens), it writes a Python script that runs locally and returns a summary (~600 tokens).

The runtime provides a sandboxed API that scripts can import:

  • File discovery and pattern matching
  • AST-based code transformations
  • Bulk search and replace with rollback
  • PII/secret masking for safety

This turned operations that were impractical (refactoring 100+ files) into routine tasks.

Lessons Learned

1. Description quality determines activation quality. A vague description like "helps with code" won't activate reliably. "Activates when users want to fix failing tests, mentions test failures, or runs test suite and failures occur" gives Claude clear signals.

2. Progressive disclosure works. SKILL.md files under 500 lines load faster. Move detailed reference material to separate files that skills load on demand.

3. Skills compose better than monoliths. Five focused skills that integrate cleanly beat one mega-skill that tries to do everything. The engineering workflow plugin demonstrates this — each skill has a clear boundary, but they chain naturally in a development flow.

4. Test across models. Skills behave differently on Opus, Sonnet, and Haiku. The plan-implementer agent specifically uses Haiku because implementation tasks benefit more from speed than reasoning depth.

Impact

The marketplace has grown to 439+ stars, with the community contributing new plugins. The most popular skills are feature-planning (for its structured approach to complex features) and code-execution (for the dramatic token savings on bulk operations).

The plugin architecture means teams can fork individual plugins, customize them for their stack, and still pull updates from upstream — a pattern that's worked well for enterprise adoption.