Paderich

Posted on Mar 21

Versioning Your AI Workflow with a Custom Claude Code Marketplace

#learning #ai #career #coding

TL;DR: You can host a Git repository that acts as a personal marketplace for Claude Code skills. Any project you work on can point to it, pin a version, and get your curated skills installed automatically. This is how you move from "chatting with an AI" to "engineering a workflow."

Why Build a Skill Marketplace?

In my previous logs, I talked about the frustration of "black boxes" and the realization that I was only "scratching the surface" with basic setups. If you use Claude Code regularly, you’ve probably noticed a pattern: you end up reexplaining the same architectural standards, user story formats, or code review checklists for every new project.

A personal marketplace treats your AI prompts like managed infrastructure:

Portable: Your skills live in one standalone Git repo. Every project you work on can reference it.
Versioned: You pin to a Git tag (e.g., v1.0.2). If you update a skill, it won't break your older projects until you're ready to upgrade.
Shareable: Push the repo to GitHub and your entire team gets the same "Senior Engineer" level skills.
Zero Copy-Paste: Claude Code handles the fetching and installation. No manual file management required.

Architecture at a Glance

The setup is straightforward. You have the Marketplace Repo (the source of truth) and your Client Repos (the projects where you actually work).

Step 1: Create the Marketplace Structure

Claude Code expects a specific folder hierarchy to discover plugins. Your marketplace repository should look like this:

claude-skills/
├── .claude-plugin/
│   └── marketplace.json       # The "App Store" index
├── plugins/
│   └── user-story-skill/      # A folder for each specific tool
│       ├── .claude-plugin/
│       │   └── plugin.json    # Metadata for this specific plugin
│       ├── commands/
│       │   └── user-story.md  # Defines the /user-story slash command
│       └── skills/
│           └── user-story/
│               └── SKILL.md   # The "Brain" (The actual logic)

Step 2: Define the Manifests

The Marketplace Index

At the root, .claude-plugin/marketplace.json tells Claude what plugins are available in this repo:

{
  "name": "pat-skills",
  "owner": { "name": "Pat" },
  "metadata": {
    "description": "Personal Claude Code skill library",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "user-story-skill",
      "source": "./plugins/user-story-skill",
      "description": "Generate agile stories from plain text",
      "version": "1.0.0"
    }
  ]
}

The Plugin Metadata

Inside plugins/user-story-skill/.claude-plugin/plugin.json, define the individual plugin:

{
  "name": "user-story-skill",
  "version": "1.0.0",
  "description": "Reference skill for agile user stories",
  "author": { "name": "Pat" }
}

Step 3: Writing the "Brain" (SKILL.md)

This is the most critical file. As I noted in Log 003, vague instructions lead to hallucinations. A professional skill file needs a strict contract, including few-shot examples.

Location: plugins/user-story-skill/skills/user-story/SKILL.md

# Purpose
Generate a well-formed agile user story from a plain-language feature request.

## Context
This skill follows standard agile coaching patterns. Stories must be independent, 
negotiable, and small enough to fit in a single sprint.

## Instructions
1. Identify the role from the input. Infer the most likely role if not stated.
2. Format the story: **As a [role], I want [goal], so that [benefit].**
3. Generate 3–5 acceptance criteria using the **Given / When / Then** pattern.
4. If the input is ambiguous, use a `[CLARIFY: ...]` marker rather than guessing.
5. Output must be concise: no preamble, just the story and criteria.

## Examples (Few-Shot)

### Example 1
**Input:** Users should be able to reset their password via email.
**Output:** 
As a registered user, I want to reset my password via email, so that I can 
regain access to my account if I forget my credentials.

Acceptance criteria:
- Given I am on the login page, when I click "Forgot password", then I am 
  prompted to enter my email address.
- Given I submit a valid email, when the system processes it, then I receive 
  a reset link within 2 minutes.

## Quality Criteria
- The role is specific (not "the system" or "a person").
- The benefit explains *why* the user wants this, not just what they want.
- Every acceptance criterion is testable by a QA engineer.
- Ambiguous inputs are flagged with `[CLARIFY]`.

Step 4: Connecting a Project

Once you’ve pushed your marketplace to GitHub (or a local Git path), head to your project directory and start Claude Code:

Type /plugin.
Select Add marketplace.
Enter your Git URL (e.g., https://github.com/your-username/claude-skills.git).

Claude handles the rest, updating your .claude/settings.json. Commit that file so your whole team shares the same skill set.

Pro-tip: In your settings.json, always ensure the ref field points to a specific tag (like v1.0.0) rather than main. This is how you ensure an update to your library doesn't silently change the behavior of an older project mid-flight.

The Reality Check: Testing Skills

As I learned with my "RAG in a box", the magic is in the plumbing. Testing a skill isn't about string matching; it's about behavioral validation.

You should build a tests/ folder in your plugin with JSON files defining your expectations. If a skill doesn't catch a "vague" input or misses a quality criterion, your SKILL.md instructions aren't sharp enough. Fix the instructions, don't just "hope" the AI gets it right next time.

Wrapping Up

Building a marketplace turns your accumulated prompting knowledge into a reusable, versioned, and shareable library. It moves you from being a "prompt user" to an AI Systems Engineer. It takes about 20 minutes to set up, but the compounding value across every new project is massive.

Cheers,
Pat

DEV Community