Ship Your Stack: A Contributor Guide to Publishing on Cables

One command, then a conversation

If you already have a Claude Code stack worth sharing, the fastest way to publish it is to install the publish-your-stack skill and let Claude walk you through it.

npx -y frenxt-cables add publish-your-stack

Then in a Claude Code session, say:

publish my stack

The skill takes over from there. You stay in the loop at every decision point — it won't publish anything externally without your explicit confirmation.

What the skill does for you

1. Detects your current setup — reads claude plugins list and ~/.claude/skills/. You'll see a summary and pick which plugins/skills you actually want to share.
2. Collects the metadata — asks for slug, title, purpose (fullstack / ai-agent / ux-design / …), and whether to use an existing repo or create a new one via gh repo create.
3. Generates a valid .cables/stack.json from your setup — correct schema, fresh last_verified date, only the plugins you selected.
4. Bundles skills with a privacy check — flags any skill containing credentials, internal paths, or obvious company references and asks before including them.
5. Validates locally with frenxt stack-publish. If the validator rejects, the skill helps you fix the root cause rather than suggesting a bypass.
6. Commits and tags the release (v0.1.0) so installs pin to a reproducible SHA.
7. Opens the submission PR against frenxt/cables with the pointer file at community-stacks/<your-slug>.json. You approve the PR body before it's opened.
8. Reports back with the PR URL and what happens next — the automated review pipeline runs, a maintainer merges, and your stack goes live on frenxt.com/stacks.

When to use the skill path

• Your stack is roughly a subset of what's on your machine — no synthetic assembly needed
• You want the metadata generation and PR plumbing handled for you
• You'd rather spend your time on the content of the stack than on Git mechanics

Where the skill steps aside

The skill still has you drive the parts that require judgment: which plugins and skills to ship, what to name them, whether to ship a flagged skill, and whether to proceed if the validator flags something for human review. It automates the mechanical steps, not the editorial ones.

Updating your published stack

When you've changed your stack and want to ship a new version, say "update my published stack". The skill detects the delta, bumps the version, re-validates, re-tags, and opens a new PR. Users on the old version stay pinned until they opt into the new one.

The shape of the contract

Your stack lives in your own public GitHub repo. You don't fork ours to publish; you just register a pointer. The contract is one file in your repo:

your-repo/
└── .cables/
    └── stack.json

And optionally, skills bundled alongside:

your-repo/
├── .cables/
│   └── stack.json
└── .claude/
    └── skills/
        └── your-skill/
            └── SKILL.md

That's it. No build step, no weird layout. The stack.json looks like this:

{
  "schema_version": 1,
  "slug": "your-stack-name",
  "title": "Your stack's display name",
  "description": "One or two sentences.",
  "purpose": "ai-agent-development",
  "author": { "github": "your-handle" },
  "version": "0.1.0",
  "last_verified": "2026-04-18",
  "claude_plugins": [
    "superpowers@claude-plugins-official",
    "vercel@claude-plugins-official"
  ],
  "skills": ["your-skill"]
}

The full spec with every field is in our repo at docs/community-stack-v1.md. Keep it simple: list the plugins you use, tag a version, and set last_verified to today.

Step 1 — Build your repo

Create a public GitHub repo. Add .cables/stack.json. If you want to ship custom skills, add them under .claude/skills/<slug>/SKILL.md. Commit and push.

If your stack includes plugins from a non-official marketplace (anything other than claude-plugins-official or openai-curated), you need to declare that marketplace in the marketplaces array so the CLI can register it at install time.

Step 2 — Validate locally before submitting

Catch issues before CI does:

npx -y frenxt-cables stack-publish .

You'll get one of three verdicts: approved, needs review, or rejected. The report is explicit about what's wrong — stale verification date, undeclared marketplace, typo-squat suspicion, or schema errors. Iterate until approved. Most stacks are green on the first or second try.

Step 3 — Tag a release

Pin a specific commit so installs are reproducible forever:

git tag v0.1.0
git push --tags

Users who install your stack will always get exactly this commit — even if you push changes tomorrow. They opt into new versions explicitly. That's a feature; it means a future update of yours can't silently change what's installed on someone's machine.

Step 4 — Submit via PR

Fork github.com/frenxt/cables and add one small file at community-stacks/<your-slug>.json:

{
  "schema_version": 1,
  "slug": "your-stack-name",
  "repo": "your-handle/your-repo",
  "ref": "v0.1.0",
  "submitted_by": "your-handle"
}

Open the PR. The submitted_by, the repo owner, and the PR author must all match — that's the identity check we run to confirm you actually own the stack you're registering.

Step 5 — What happens on your PR (the review pipeline)

The moment your PR opens, a GitHub Actions workflow kicks off. It runs in about 90 seconds and aggregates findings from six independent checks into a single sticky comment:

• frenxt validator — schema, semver, stale dates, undeclared marketplaces, typo-squat detection, forbidden shell-execution patterns
• Semgrep (custom rules) — scans your bundled skills for prompt-injection phrasing ("ignore previous instructions", "silently upload"), references to credential paths (~/.aws/credentials, ~/.ssh), destructive commands (rm -rf $HOME)
• Gitleaks — catches any API keys or tokens you accidentally committed
• OSSF Scorecard — grades your publisher repo's hygiene on a 0–10 scale (branch protection, 2FA, signed commits, recent activity). Higher scores mean less friction
• Identity check — confirms PR author, repo owner, and submitted_by all match
• GitHub Copilot code review — LLM-based inline review of the changes. Free forever on public repos. Catches things static rules miss

All of this is free. No paid SaaS, no API keys required from you. Same pipeline runs on our own first-party stacks — we don't give ourselves a pass.

Step 6 — Outcomes

Three paths from here:

• All green → a maintainer merges, usually within 24 hours. Your stack goes live on frenxt.com/stacks
• Flagged for review → the automation surfaced something worth human eyes (typo-squat suspicion, third-party marketplace, low Scorecard). A maintainer will ask questions on the PR
• Rejected → the validator found a hard blocker. The comment tells you exactly what. Fix locally, push an update, checks re-run automatically

Step 7 — Users install your stack

Once merged, anyone can install your stack with one command:

npx -y frenxt-cables stack @your-handle/your-stack-name

Under the hood, the CLI resolves the scoped slug to the submission pointer at community-stacks/your-handle/your-stack-name.json, fetches the pinned ref from your GitHub repo, and runs the install flow: marketplaces registered, Claude Code plugins installed, skills synced to every ~/.claude* profile. Scoped slugs are globally unique by construction — no collisions with other publishers. Codex/other-provider support will ship as separate provider-specific stacks later.

Shipping updates

When you want to ship a new version, it's the same loop. Push changes to your repo, tag v0.2.0, open a PR to frenxt/cables that updates your community-stacks/<slug>.json file with the new ref. Full review runs again. Old users stay pinned to v0.1.0 until they opt into the upgrade.

Where the trust boundaries sit

A few things worth knowing about how this is structured:

• Stack content lives in your repo, always. We don't copy it into ours. We maintain a pointer
• We control the slug namespace. First-come first-served; the PR is how you claim it
• Installs are pinned to reviewed SHAs. A compromised push to your repo tomorrow doesn't affect users already installed on the reviewed version
• We rely on Claude's harness for execution safety. Skills get the same permission confirmations any other Claude skill gets. We're not trying to be the sandbox — we're the listing + review layer
• Takedown is fast. If something slips through, we flip an approved: false flag on the API and new installs stop immediately