agentleFS
app-vitalsapp-vitals/shipwright/.claude/skills/marketplace-dev/SKILL.md

marketplace-dev

Skill16 starsChanged 24 days agoMITView on GitHub

This skill MUST activate when creating, modifying, or reviewing the shipwright plugin or its marketplace entry. Triggers on: editing files under plugins/shipwright/, modifying plugin.json or .claude-plugin/marketplace.json, adding commands/skills/agents/hooks to the shipwright plugin, editing TESTING.md, reviewing or creating pull requests that touch plugins/shipwright/, or when user mentions "version bump", "release", "add command", "add skill", "add hook", "add agent", "marketplace update", "plugin checklist", "plugin.json", or "marketplace.json". This skill prevents version drift and enforces structural conventions for the shipwright plugin in this self-hosted marketplace.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. dork-labs/dorkos★ 11same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository3 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 4 are distinctive, and 11 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 11

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write correct conventional commits — semantic-release derives the bump type from them:

    line 58
  2. Very specific:

    When modifying the shipwright plugin:

    line 107
  3. Very specific:

    Create the component file following conventions (see references/frontmatter-schemas.md)

    line 111
  4. Distinctive:

    If the plugin has a TESTING.md, add test scenarios for the new component

    line 112
  5. Very specific:

    Update plugins/shipwright/README.md if it lists available commands

    line 113
  6. Very specific:

    Write a feat: commit — semantic-release will derive the minor version bump on merge

    line 114
  7. Distinctive:

    Update TESTING.md if test scenarios are affected

    line 119
  8. Very specific:

    Write a fix: or feat: commit as appropriate — do not manually bump the version

    line 120
  9. Very specific:

    Use feat!: as the commit prefix (or add BREAKING CHANGE: to the footer)

    line 124
  10. Distinctive:

    Document the breaking change in the commit body

    line 125
  11. Very specific:

    If you change the description in plugin.json, also sync it to:

    line 130
  12. Very specific:

    Use references/ subdirectory for detailed guidance loaded on-demand

    line 163
  13. Very specific:

    Use assets/templates/ for output templates

    line 164
  14. Very specific:

    Keep SKILL.md under 500 lines.

    line 165
  15. Very specific:

    Use "url" (not "email"), and "App Vitals" (capitalized, with space).

    line 203

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Marketplace Development Guide

This skill encodes the conventions and checklists for working with the shipwright plugin in this self-hosted single-plugin marketplace. Follow it to prevent version drift and maintain consistency.

When This Activates

  • Bumping the plugin version (new feature, bug fix, breaking change)
  • Adding or modifying commands, skills, agents, or hooks
  • Editing plugins/shipwright/.claude-plugin/plugin.json
  • Editing .claude-plugin/marketplace.json (once it exists — see MKT-1.2)
  • Updating plugin descriptions or README content
  • Creating or reviewing PRs that touch plugins/shipwright/

Version Ownership

This is the most important section. Version in this repo is owned by semantic-release and scripts/sync-version.ts — do NOT manually bump version numbers.

How Versioning Works

Versions are determined automatically on every merge to main:

  1. semantic-release analyzes conventional commits since the last tag
  2. It calls scripts/sync-version.ts <nextVersion> via prepareCmd in .releaserc.json
  3. sync-version.ts writes the new version to five locations:
#FileUpdated by
1package.jsonsync-version.ts
2plugins/shipwright/package.jsonsync-version.ts
3metrics/package.jsonsync-version.ts
4agent/package.jsonsync-version.ts
5version.txtsync-version.ts

A sixth location, .claude-plugin/marketplace.json, will also be auto-synced once MKT-1.2 lands (the file does not exist yet).

What Developers Do Instead

Write correct conventional commits — semantic-release derives the bump type from them:

Commit prefixBump typeExample
fix:Patch (1.2.0 → 1.2.1)fix: correct hook timeout
feat:Minor (1.2.0 → 1.3.0)feat: add /audit command
feat!: or BREAKING CHANGE:Major (1.2.0 → 2.0.0)feat!: rename dev-task command
docs:, chore:, ci:, build:No releaseNon-functional changes
refactor:, test:, perf:No releaseNon-functional changes

Never manually edit the "version" field in any package.json, plugin.json, or marketplace.json. The automation owns these.

For a post-release verification checklist, see references/version-sync-checklist.md.


Plugin Structure

This repo is both the plugin source and the marketplace host. The single plugin is shipwright, living at plugins/shipwright/:

plugins/shipwright/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest (name, version, description, hooks)
├── commands/                # Slash commands (*.md files with YAML frontmatter)
├── skills/                  # Skill definitions
│   └── <skill-name>/
│       ├── SKILL.md
│       ├── references/      # On-demand guidance docs
│       └── assets/
│           └── templates/   # Output templates
├── hooks/                   # Hook implementations
│   ├── hooks.json           # Hook configuration (if not in plugin.json)
│   └── <hook-impl>.sh
├── agents/                  # Agent definitions (*.md)
├── scripts/                 # Utility and build scripts
├── README.md                # Plugin documentation
└── TESTING.md               # Manual test plan

The marketplace manifest lives at .claude-plugin/marketplace.json (root of repo). It does not exist yet — it is created in MKT-1.2.


Plugin Modification Checklist

When modifying the shipwright plugin:

Adding a New Component (command, skill, agent, hook)

  1. Create the component file following conventions (see references/frontmatter-schemas.md)
  2. If the plugin has a TESTING.md, add test scenarios for the new component
  3. Update plugins/shipwright/README.md if it lists available commands
  4. Write a feat: commit — semantic-release will derive the minor version bump on merge

Modifying Existing Behavior

  1. Make the change
  2. Update TESTING.md if test scenarios are affected
  3. Write a fix: or feat: commit as appropriate — do not manually bump the version

Breaking Changes

  1. Use feat!: as the commit prefix (or add BREAKING CHANGE: to the footer)
  2. Document the breaking change in the commit body
  3. semantic-release will cut a major version bump on merge

Changing the Plugin Description

If you change the description in plugin.json, also sync it to:

  • The description field in .claude-plugin/marketplace.json (once it exists)
  • The opening paragraph in plugins/shipwright/README.md

Component Conventions

Commands (commands/*.md)

---
description: Short action-oriented description     # Required
argument-hint: <required-arg> [optional-arg]        # Optional
allowed-tools: [Read, Glob, Grep, Bash]             # Optional
---
  • Filename = command name + .md (e.g., plan-session.md -> /plan-session)
  • Kebab-case filenames only
  • For new work, consider the skills/<name>/SKILL.md layout instead (preferred by Anthropic)

Skills (skills/<name>/SKILL.md)

---
name: skill-name                                    # Required, matches directory name
description: >                                      # Required, ~100 words
  When to trigger and what it does...
---
  • Directory name = skill name, kebab-case
  • Use references/ subdirectory for detailed guidance loaded on-demand
  • Use assets/templates/ for output templates
  • Keep SKILL.md under 500 lines; split to references if exceeding

Agents (agents/*.md)

---
name: agent-name                                    # Required
description: >                                      # Required
  When to use this agent...
model: sonnet                                       # Optional (sonnet, opus, haiku)
tools:                                              # Required
  - Read
  - Edit
  - Grep
---

Hooks

Hooks can be configured in plugin.json directly (simple cases) or in hooks/hooks.json (complex multi-matcher setups). Use shell scripts (.sh) or Python (.py) for implementation.

For complete schemas and examples, see references/frontmatter-schemas.md.


Naming & Consistency Standards

Author Field (Standardized)

"author": {
  "name": "App Vitals",
  "url": "https://github.com/app-vitals"
}

Use "url" (not "email"), and "App Vitals" (capitalized, with space).

Repository and Homepage

"homepage": "https://github.com/app-vitals/shipwright",
"repository": "https://github.com/app-vitals/shipwright"

License

"license": "MIT"

Description Sync Points

The plugin description appears in multiple places. When changing it, update all:

LocationFormat
plugins/shipwright/.claude-plugin/plugin.json"description" field (canonical source)
.claude-plugin/marketplace.json"description" in plugin entry (once it exists)
plugins/shipwright/README.mdOpening paragraph (may be longer form)

References

Load these for detailed guidance when needed:

  • references/version-sync-checklist.md — Post-release verification and a primer on semantic-release ownership
  • references/plugin-scaffolding.md — Templates for plugin component files (plugin.json, README, TESTING.md)
  • references/frontmatter-schemas.md — Complete YAML frontmatter schemas for all component types

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.