Skip to main content
skill CX Codex

openship-config — Claude Code skill for designing openship.json

A skill that inspects a repository and builds openship.json with only the overrides OpenShip needs. Use it before a first deploy or when openship config validate fails.

Apache-2.0 ★ 1,216 updated 2026-10-24

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install openship-skills@claude-settings
Open on GitHub

What openship-config does

The skill follows OpenShip's upstream configuration workflow: inspect the repo, declare only necessary overrides, then validate. It checks package scripts, lockfiles, framework settings, Dockerfiles, compose files, workspace layout, and any existing openship.json. Omitted fields are filled by auto-detection.

You run openship config init only when the file is missing. With an existing config, the skill keeps it and adds just what needs to override detection. The $schema stays pointed at https://openship.io/openship.schema.json. Then it runs openship --json config validate with the installed CLI version, fixes errors, and reviews warnings. Unknown keys can pass the runtime even when the editor schema rejects them.

A config file describes intent, not reality: it does not prove a domain moved or a deployment changed. That part belongs to the companion skill openship-deploy. Secrets stay out of committed JSON — secret: true controls storage handling after ingestion, not encryption inside a Git file. Keep example credentials from the docs out of your repo.

What it helps with

  • design openship.json that fits a specific repo
  • figure out which fields auto-detection can supply
  • fix errors from openship config validate
  • set up compose services, ports, dependencies, and persistent volumes
  • understand how secret: true actually handles credentials

Example prompts for the agent

  • Create openship.json for this repository
  • Run openship config validate and fix whatever fails
  • Why does validation reject this config key?

How to install openship-config

1Plugin marketplace

/plugin marketplace add fcakyon/claude-codex-settings
/plugin install openship-skills@claude-settings

This installs the whole openship-skills plugin with all its skills

2Skills CLI (Vercel)

npx skills add fcakyon/claude-codex-settings --skill openship-config -a claude-code

3Manually: put the files in place

~/.claude/skills/openship-config/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/openship-config/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about openship-config

How do I install openship-config in Claude Code?

Through the marketplace: /plugin marketplace add fcakyon/claude-codex-settings, then /plugin install openship-skills@claude-settings. Alternatively, run npx skills add fcakyon/claude-codex-settings --skill openship-config -a claude-code — the file lands in ~/.claude/skills/openship-config/SKILL.md.

What does the openship-config skill do?

It inspects a repo and designs openship.json: picks a single app or compose services, adds only overrides on top of auto-detection, and runs openship --json config validate. It does not rewrite an existing config from scratch.

How is openship-config different from openship-deploy?

This skill only designs and validates the configuration. Deploying and verifying that a domain actually moved is the job of openship-deploy. One writes the file, the other applies it.

Source text

SKILL.md · Apache-2.0
---
name: openship-config
description: This skill should be used when the user asks to "create openship.json", "configure an OpenShip deployment", "make a repo deployable on OpenShip", or fix "openship config validate" errors.
---

# Design openship.json

Use OpenShip's upstream configuration workflow: inspect the repo, declare only necessary overrides, then validate. Auto-detection supplies omitted fields. Prefer self-hosted deployment unless the user selects cloud.

## Design the configuration

1. Inspect package scripts, lockfiles, framework settings, Dockerfiles, compose files, workspace layout, and an existing `openship.json`.
2. Choose a single app, compose services, or detected monorepo apps. Do not combine those shapes casually. `monorepo.apps` overrides detected apps by root directory. It does not discover new applications.
3. Read [fields](references/fields.md) for names and meanings and the bundled [JSON schema](references/openship.schema.json) for editor validation. Use [compose guidance](references/compose-multi-service.mdx) for service topology, ports, dependencies, and persistent volumes.
4. Start with `openship config init` only when the file is absent. Preserve an existing config and add only values that need to override detection. Keep its `$schema` set to `https://openship.io/openship.schema.json`.
5. Run `openship --json config validate` using the deployment's CLI version. Fix errors and review warnings: unknown keys can be ignored by the runtime even though the editor schema rejects them.

A minimal server config can be:

```json
{
  "$schema": "https://openship.io/openship.schema.json",
  "port": 3000,
  "runtime": "docker",
  "domains": ["app.example.com"]
}
```

## Self-hosted details

- Self-hosted defaults to unlimited resources in the bundled release. Declare caps only when intended. Service-level caps override project caps field by field. Check target capacity separately from local config validation.
- Use named persistent volumes for state that must survive an application deploy. Expose only the services intended to receive public traffic.
- Keep actual secret values out of committed JSON. `secret: true` controls storage handling after ingestion. It does not encrypt a credential in a Git file. Read [environment variables](references/environment-variables.mdx) for instance-managed values.
- `openship.json` expresses desired configuration. It does not prove an existing domain has moved or the running deployment has changed. The companion `openship-deploy` skill handles deployment and live verification.

## Source and version

The workflow and [field reference](references/fields.md) derive from the official upstream config skill. [upstream.json](references/upstream.json) records the release and links to its CLI validator, runtime parser, types, parser tests, and deployment preparation code. Consult those sources when docs disagree or a behavior depends on the installed version. The parser and actual deployment implementation decide runtime behavior. The JSON schema serves editor validation.

Read the [configuration guide](references/openship-json.mdx) for additional examples. Do not copy example credentials into a repository.

© fcakyon · Apache-2.0 · fcakyon/claude-codex-settings

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set113

The whole set →
test-audit The test-audit skill reviews new and changed tests, and helps spot duplicates or low-value checks. Use it when adding tests or auditing an existing suite. CX Codex +1 ★ 1,216repo stars webmcp-gen webmcp-gen turns a page workflow into a WebMCP tool and checks that the tool matches the behavior of the existing UI. CX Codex +1 ★ 1,216repo stars start-environment start-environment teaches the assistant how to spin up local development containers via dev docker up, wait for healthchecks, and inspect ports. CX Codex +1 ★ 1,216repo stars service-architecture The service-architecture rule maps Polar’s shared Docker infrastructure and per-worktree app stacks. Use it to understand service addresses, container dependencies, and network boundaries. CX Codex +1 ★ 1,216repo stars app-auth The app-auth skill for Claude Code structures and implements application authentication flows. It activates when handling social login, password recovery, account switching, or sign-in components. CX Codex +1 ★ 1,216repo stars gcloud-usage gcloud-usage is a Claude Code skill that guides Google Cloud log queries and analysis of metrics, traces, and alerts. It supports production debugging and GCP observability work. CX Codex +1 ★ 1,216repo stars dokploy-deploy dokploy-deploy hands the agent Dokploy's own docs: cloud and self-hosted setup, app and Compose deploys, databases, domains, plus a CLI command index. CX Codex +1 ★ 1,216repo stars pr-reviewer The pr-reviewer subagent for Claude Code inspects GitHub pull requests for security flaws and breaking bugs using the gh CLI, without cluttering reviews. CX Codex ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open