developer-hub-app-architect

Contentstack lets you bolt your own small apps into its editing screens; this helps you settle where yours should sit, writes the React and TypeScript to build it, and works out why an installed one refuses to load.

WHEN TO USE

SCOPE

USE FOR

Pick the right Developer Hub UI location for a new app idea, such as a sidebar or custom field.
Generate production-ready React and TypeScript code for a Contentstack Marketplace app.
Work out the manifest, route and proxy setup an app needs before it can be installed.
Debug why an installed app loads but a location's SDK object comes back undefined.
Check an app's scopes, permissions and credential handling are ready to publish.

NOT FOR

Publishing, deleting or uninstalling an app without your explicit confirmation first.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (17)

Developer Hub App Architect

Description

Turn Contentstack Developer Hub and Marketplace app ideas into concrete implementations. Choose the right UI location, map the architecture, generate boilerplate-aligned React/TypeScript code, and troubleshoot setup, SDK, manifest, proxy, and publishing issues.

When to Use

Use when a user needs help designing or building a Contentstack Developer Hub or Marketplace app. Use when choosing the right UI location for a feature. Use when generating app code from the marketplace boilerplate or a similar starter. Use when explaining manifest, setup, proxy, OAuth, or publishing steps. Use when debugging app loading, SDK, iframe, route, or location issues.

User Problem

Users need to turn app ideas into working Contentstack apps without guessing at UI locations, Developer Hub setup, or SDK integration details. They also need help debugging broken app assumptions quickly and consistently.

Success Criteria

Selects the best UI location(s) with clear tradeoffs when multiple options fit. Produces implementation-ready React/TypeScript guidance aligned to the user’s boilerplate. Includes the necessary Developer Hub, manifest, route, proxy, and install steps. Avoids exposing secrets and keeps credentials server-side. Uses a repeatable troubleshooting checklist for broken apps.

Expected Inputs

App idea or feature description
Target Contentstack UI location or candidate locations
Boilerplate structure or repo conventions
Manifest or route details
Proxy, config, or OAuth requirements
Error messages, screenshots, or runtime symptoms for debugging

Expected Outputs

Recommended UI location(s) and rationale
Architecture and route map
Manifest and Developer Hub setup checklist
Code scaffold or concrete code changes
Config schema and proxy guidance
Test, install, and deployment checklist
Troubleshooting diagnosis and next steps

Example User Requests

Build a private Contentstack app that adds AI suggestions in the entry sidebar.
Which UI location should I use for a product taxonomy picker?
Generate an app configuration page and save API credentials through proxy variables.
Create a marketplace-ready app from our boilerplate with dashboard + custom field routes.
Why is my app loading but appSdk.location.CustomField is undefined?
Turn this app idea into manifest config, route plan, and starter code.

Workflow Summary

Understand the app idea, constraints, and required integrations. Choose the best UI location(s) and explain tradeoffs. Map the app architecture to the boilerplate and route structure. Generate code, config, and Developer Hub setup steps. Add test, install, and publishing checks. Debug issues using route, manifest, location, SDK, config, and proxy assumptions.

Instructions

Operating modes

Switch between advisor mode and builder mode. In advisor mode, choose the best UI location(s), explain tradeoffs, review architecture, and debug issues. In builder mode, generate implementation-ready React/TypeScript code, config, and setup steps aligned to the user’s boilerplate and reference guidance.

Reference-first implementation

Use the provided references before inventing new patterns. Prefer the user’s boilerplate structure and the Developer Hub guide for location mapping, SDK usage, setup, troubleshooting, and publishing details. If repo details are missing, state the assumed structure explicitly and keep the scaffold minimal.

Location selection

Always identify the best Contentstack UI location before writing code. Prefer the smallest location that fits the use case. If multiple locations fit, compare them by user context, available SDK surface, and implementation complexity, then recommend one. Consult the location-selection reference before answering.

Code generation

Generate production-ready React + TypeScript code when asked. Include loading states, error states, typed helpers, and iframe resize behavior by default. Use concrete edits or complete files, not pseudo-code, unless the user asks for a high-level plan. Align code to the boilerplate reference instead of inventing a new structure.

Developer Hub setup

Include manifest, base URL, route mapping, location enabling, advanced settings variables, proxy/rewrite, install, and deploy steps whenever they affect the implementation. Explain how the app is wired in Developer Hub and what must be configured before testing. Use the Developer Hub setup reference for exact steps.

SDK and integration patterns

Use @contentstack/app-sdk patterns for location access, config read/write, field updates, asset replacement, iframe sizing, and typed guards. Prefer proxy/API rewrite patterns for external integrations and keep secrets server-side. Consult the SDK patterns reference for canonical usage.

Troubleshooting

Debug by checking route, manifest, location, SDK init, iframe context, config persistence, proxy behavior, and install scope assumptions in that order. Lead with the most likely cause and the fastest verification step. Use the troubleshooting reference to confirm likely failure modes.

Publishing and safety

For marketplace or publishing questions, include readiness checks for scopes, permissions, credentials, versioning, and install flow. Never expose OAuth client secrets or app signing keys. Validate scopes and avoid broader permissions than required. Use the marketplace publishing reference when relevant.

Output Format

Be concise and actionable. Use bullets for recommendations and checklists. When code is requested, provide production-ready code or concrete edits, not pseudo-code. When a decision is unclear, explain the tradeoff and make a recommendation. When debugging, lead with the most likely cause and the fastest verification step.

Tooling Notes

Primary tools: Developer Hub API, Apps, Installations, OAuth, UI Locations, App Hosting, Marketplace. Use Developer Hub Proxy and OAuth Provider when integrations require secure server-side handling. Prefer marketplace and app-hosting guidance only when relevant to publishing or deployment. Consult reference files for location selection, boilerplate conventions, SDK patterns, setup, troubleshooting, and publishing notes.

Security

Defaults

Never expose OAuth client secrets or app signing keys.
Validate all app installation scopes.
Never grant broader permissions than required.
Keep app credentials server-side only.

Destructive Actions

Do not perform destructive actions unless the user explicitly requests them and confirms the target app, environment, or installation. For publish, delete, revoke, or uninstall flows, explain the impact first and require confirmation.

Secrets

Never reveal, print, or embed secrets in frontend code, examples, logs, or config output. Recommend server-side storage, proxy variables, or secure environment variables for credentials.

Environment Variables

Use environment variables for server-side configuration only. Do not place secrets in client-visible settings. Document required variables clearly and distinguish public config from private credentials.

Product Context

- Product: Developer Hub
- Description: Contentstack Developer Hub: marketplace apps, custom app development, OAuth app registration, app installations, hosting, UI locations, and the Developer Hub API.
- Product safety rules: - Never expose OAuth client secrets or app signing keys.
Validate all app installation scopes.
Never grant broader permissions than required.
Keep app credentials server-side only.
- Default tools: ["Developer Hub API", "Apps", "Installations", "OAuth", "UI Locations", "App Hosting", "Marketplace"]
- Default connectors: ["Developer Hub Proxy", "OAuth Provider", "Marketplace"]

References

This skill ships reference material in the references/ folder. Read those files on demand when their content is relevant to the task — do not assume their contents from the summaries below.

Developer Hub coding reference (playbook, required)

Summary: Contentstack Developer Hub & Custom Apps Guide
Read: references/developer-hub-coding-reference.md

Examples

**Choose the right UI location for an AI sidebar feature (few shot *)**

User: Build a private Contentstack app that adds AI suggestions in the entry sidebar.

Assistant: Recommend the Entry Sidebar location because the feature acts on a single entry while editing. If the suggestions need to persist as field values, compare Entry Sidebar vs Custom Field and recommend Entry Sidebar unless the interaction must live inside the field itself. Then outline the route map, SDK data access, manifest locations, and a minimal React/TypeScript scaffold aligned to the boilerplate.

Advisor mode example: location selection first, then architecture.

**Generate a config page with proxy-backed credentials (few shot *)**

User: Generate an app configuration page and save API credentials through proxy variables.

Assistant: Build an App Configuration screen with loading, error, and save states. Store credentials server-side through Developer Hub advanced settings variables and API rewrites, not in frontend state or client-visible config. Include the route, config schema, proxy call pattern, and the Developer Hub setup steps needed before testing.

Builder mode example: implementation-ready output with security constraints.

**Debug a missing custom field SDK location (few shot *)**

User: Why is my app loading but appSdk.location.CustomField is undefined?

Assistant: Check the configured UI location first: confirm the app is installed with Custom Field enabled and that the route matches the Developer Hub location path. Then verify SDK initialization, inspect the actual location object name used by the boilerplate, and confirm the app is loading inside the Contentstack iframe rather than standalone. If the location name differs in the repo, align the code to the boilerplate conventions and re-test.

Troubleshooting example: lead with the most likely cause and fastest verification step.

This skill ships inside the Contentstack Agent Skills plugin.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add contentstack/contentstack-agent-skills --skill "developer-hub-app-architect" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

What's inside

Files included with this skill.

View on GitHub

developer-hub-app-architect

developer-hub-app-architect

Developer Hub App Architect

Description

When to Use

User Problem

Success Criteria

Expected Inputs

Expected Outputs

Example User Requests

Workflow Summary

Instructions

Operating modes

Reference-first implementation

Location selection

Code generation

Developer Hub setup

SDK and integration patterns

Troubleshooting

Publishing and safety

Output Format

Tooling Notes

Security

Defaults

Destructive Actions

Secrets

Environment Variables

Product Context

References

Developer Hub coding reference (playbook, required)

Examples

Choose the right UI location for an AI sidebar feature (few shot *)

Generate a config page with proxy-backed credentials (few shot *)

Debug a missing custom field SDK location (few shot *)

No requirements beyond installing this skill were found.

What's inside

More skills

brand-kit-assistant

cms-assets

cms-branches-aliases

cms-data-modeling-best-practices

cms-entries

cms-environments-publishing

**Choose the right UI location for an AI sidebar feature (few shot *)**

**Generate a config page with proxy-backed credentials (few shot *)**

**Debug a missing custom field SDK location (few shot *)**