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
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install openship-skills@claude-settingsWhat 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.jsonthat 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: trueactually handles credentials
Example prompts for the agent
- Create
openship.jsonfor this repository - Run
openship config validateand 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-settingsThis 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-code3Manually: put the files in place
~/.claude/skills/openship-config/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/openship-config/
1Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill openship-config -a codex2Manually: put the files in place
.agents/skills/openship-config/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill openship-config -a cursor2Manually: put the files in place
.cursor/skills/openship-config/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install fcakyon/claude-codex-settings plugins/openship-skills/skills/openship-config2Manually: put the files in place
.github/skills/openship-config/SKILL.md1Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill openship-config -a gemini-cli2Platform CLI
gemini skills install https://github.com/fcakyon/claude-codex-settings --path plugins/openship-skills/skills/openship-configManually: put the files in place
.devin/skills/openship-config/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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