---
name: contentful-help
description: 'Diagnose, configure, and look up Contentful topics. Trigger keywords: contentful help, contentful doctor, contentful setup'
metadata:
  version: '1.0.0'
argument-hint: '[doctor|setup]'
allowed-tools: 'Bash(scripts/run *) Read mcp__contentful-help__start mcp__contentful-help__advance mcp__contentful-help__topic mcp__contentful-help__topics'
disable-model-invocation: true
---

# contentful-help

This skill is a structured workflow. You interact with it via MCP tools (preferred) or a
CLI binary (fallback), reading its JSON output, following the instructions in the `prompt`
field, and passing your response back. **Do not show the raw JSON or tool calls to the user.**

**Use MCP tools if available.** If you have `mcp__contentful-help__start` and
`mcp__contentful-help__advance`, use MCP mode. Only fall back to CLI mode if MCP tools
are not available in your environment.

## How this skill works

This skill was built with skill-kit, a structured workflow engine. Each step provides
a prompt containing XML-tagged sections:

- **`<system>`** — Behavioral directives: persona, tone, or constraints. Follow as
  guidelines for how to behave, not as tasks to relay to the user.
- **`<prompt>`** — Task instructions: what to do, what context to consider, what to produce.
- **`<ask-user>`** — Ask the user a question. Contains `<option>` children for structured
  choices, or `type="open"` for free-form conversation.
- **`<confirm>`** — Binary yes/no confirmation. Attributes: `default`, `destructive`.
- **`<plan>`** — Present a plan for approval. Contains `<step>` children.
- **`<checklist>`** — Create tracked work items. Contains `<item>` children with status.
- **`<subagent>`** — Delegate work to an isolated sub-agent. If `no-recurse` is set,
  the subagent must not invoke the skill named in the attribute.
- **`<rendered>`** — Pre-rendered output. Emit verbatim — no edits, no added commentary.

A step may contain one or more of these sections in sequence. Follow them in order.

The skill author composed these sections to guide your behavior. The tags and tool
mappings are generated by the SDK based on the author's intent and your host's
capabilities. A skill-level system directive may appear in the preamble — it applies
to all steps unless a step includes its own `<system>` override.

The **preamble** (sent on the first step) contains a table mapping each tag to the
specific tool available in your environment. Refer to it throughout the workflow.

## How to run this skill

### MCP mode (preferred)

If you have MCP tools for this skill (e.g., `mcp__contentful-help__start` and
`mcp__contentful-help__advance`), use them instead of the CLI:

1. Call the `start` tool (with `params` if the skill requires them).
2. Read the `preamble` field (first call only). It maps XML tags to your available tools.
3. Follow the `prompt` instructions. Produce a JSON object matching the `schema`.
4. Call the `advance` tool with the `session`, `step`, and `output`.
5. Repeat steps 3-4 until `status` is `"done"`.

If you get `status: "error"` with `retry: true`, fix your output and resubmit.
**Do not show raw JSON, session IDs, or MCP tool calls to the user.**

Skip the rest of this section — the CLI instructions below are only needed when
MCP tools are not available.

### CLI mode (fallback)

This SKILL.md file is inside the skill directory. Resolve the **absolute path** to `scripts/run`
from this file's location (e.g., `/path/to/skill/scripts/run`). Use the absolute path in all
Bash commands — do not `cd` into the skill directory.

In the examples below, `<skill>/scripts/run` is a placeholder for this absolute path.

### Detect your host

Determine which agent host you are running in, and pass it as `--host`:

- Claude Code: `--host claude-code`
- Codex: `--host codex`
- OpenCode: `--host opencode`
- Gemini CLI: `--host gemini-cli`
- Cline: `--host cline`
- Roo Code: `--host roo-code`
- Kilo Code: `--host kilo-code`
- Cursor: `--host cursor`
- Amp: `--host amp`
- Unknown/other: omit the flag (defaults to generic)

### Report your tools

Pass the tools you have available as a comma-separated `--tools` flag on the **start**
command. The session remembers them — you don't need to pass `--tools` on advance.

When `--host` is provided, `--tools` is merged with the host's known tool registry.
This means partial reporting is handled gracefully — the registry fills in any tools
you omit. If `--tools` is omitted entirely, the skill infers tools from `--host`.
If both are omitted, all interactions use generic fallbacks.

### Subagent invocations

If you are a **subagent** (spawned by another agent, not the top-level agent the user
is talking to), add `--subagent` to the start command. This tells the skill that your
reported tools are a genuine subset — the skill will not merge them with the host registry.

Without `--subagent`, the skill assumes you are a top-level agent and merges your tools
with the registry (since top-level agents often under-report their tools).

## Parameters

This skill takes no parameters. Pass `--params '{}'`.

### Step 1: Start with a session

```bash
<skill>/scripts/run --params '{}' --host claude-code --tools <your-tools> --session new 2>/dev/null
```

This returns a JSON pointer with `sessionId`, `file`, and `line`. The `line` field tells you
which line to read — it will be `2`, not `1` (line 1 is an internal header, never read it).

Read **only** line `line` from `file`. It contains the step prompt, schema, and preamble.

**Read the `preamble` first.** It contains a table mapping XML tags to the tools
available in your environment. Refer to it throughout the workflow.

### Step 2: Follow the prompt

Read the `prompt` field. It contains XML-tagged sections (described in "How this skill
works" above): `<system>` directives to follow, `<prompt>` instructions to act on, and
interaction tags (`<ask-user>`, `<confirm>`, `<plan>`, `<checklist>`, `<subagent>`)
to execute using the tools mapped in the preamble. If a `<rendered>` block appears,
emit its content verbatim.

Produce a JSON object matching the `schema`.

### Step 3: Advance

Pass your output back with the step name:

```bash
<skill>/scripts/run advance --step <step-name> --output '<your-json>' --session abc123 2>/dev/null
```

This returns a single line number (e.g., `4`). Read **exactly and only that line** from the session file — it contains the next prompt. Do not read any other lines.

### Step 4: Repeat until done

Keep advancing until the line you read contains `"type":"done"`. The `finalOutput` field
contains the skill's result. Present it to the user.

### Step 5: Cleanup

After presenting the result, remove the session file:

```bash
<skill>/scripts/run cleanup --session <session-id> 2>/dev/null
```

### Important

- **Never show raw JSON output or Bash commands to the user.** The user sees your natural
  language responses, not the protocol.
- **If you get a validation error** (the response has `"error": "validation"` or `"type":"error"`),
  read the `message` field, fix your output, and retry the same step.

## Steps in this skill

- **choose**: (dynamic)
- **get-space**: Ask the user for their Contentful space ID, or detect it from CONTENTFUL_SPACE_ID in the environm...
- **ask-topic**: (dynamic)

## Sub-skills

This skill contains sub-skills that the workflow routes to automatically.
Start the skill normally — the dispatcher will determine which sub-skill to use.
Only use direct sub-skill access if the user explicitly requests a specific sub-skill by name.

Sub-skill step names are prefixed: `<subskill>/<step>` (e.g., `doctor/diagnose`).

### Direct sub-skill access

```bash
<skill>/scripts/run <subskill> --params '<json>' --session new
<skill>/scripts/run <subskill> advance --session <id>
```

### Available sub-skills

- **doctor**: Diagnose and fix common Contentful issues. — params: `spaceId` (string)
- **setup**: Guided Contentful space setup and configuration.

## Reference topics

Quick-reference topics accessible without running the full workflow:

```bash
<skill>/scripts/run topics              # list all topics
<skill>/scripts/run topic <name>         # load a specific topic
```

- **rate-limits**: API rate limits and throttling
- **locales**: Content localization and locale configuration