Contentful Custom App Enhancement
Use this skill to turn a bug report, support note, or feature request into a
small, reviewable improvement for an existing Contentful custom app.
Default to the user's app repository and workflow. Do not assume a specific
repository convention, publication process, or review policy unless the user
provides one.
When a comparable public Contentful Marketplace app or example in Contentful's
public apps repository (https://github.com/contentful/apps) exists, use it as
a best practice reference for App Framework patterns and UX polish without
inheriting its release or distribution workflow.
Inputs
Accept:
- bug reports,
- customer or editor feedback,
- support tickets or issue links,
- screenshots or screen recordings,
- direct requests to change a known custom app,
- partial notes about an App Framework behavior.
If the source material is incomplete, continue with local code and provided
context when the risk is low. Ask a targeted question when the missing answer
could change the user-facing behavior, data writes, authentication, or
deployment path.
Workflow
1. Build the Request Context
Identify:
- original request and affected users,
- current app behavior versus expected behavior,
- Contentful location and workflow affected,
- space, environment, content type, field, locale, and role assumptions,
- external service or credential dependencies,
- evidence available locally and evidence still missing.
Separate confirmed facts from assumptions.
2. Inspect the Existing App
Before editing:
- check repository status and avoid overwriting user changes,
- inspect
package.json, scripts, lockfile, and framework conventions,
- locate the relevant app locations and SDK usage,
- review existing tests and nearby components,
- identify app definition, installation parameters, and deployment notes if they
exist,
- confirm whether the app uses App SDK, React Apps Toolkit, Forma 36,
contentful-management, App Actions, Functions, or an external backend.
For a reusable checklist, use
Enhancement checklist.
3. Decide Whether the Change Is Small Enough
Proceed with implementation when the change can plausibly be:
- scoped to one app,
- explained in one short PR,
- validated locally or in a sandbox,
- reviewed without broad product redesign,
- implemented without risky migrations or secret-handling changes.
Pause and clarify when the request requires:
- production data changes,
- a new external auth model,
- major content model redesign,
- multi-app coordination,
- new backend infrastructure,
- unavailable Function or plan capabilities,
- ambiguous editor behavior.
4. Plan the Smallest Useful Change
Write a short plan before editing:
- files or app locations likely to change,
- data read/write behavior,
- UI and validation updates,
- tests or manual verification to run,
- risks and rollback path.
Prefer improving the existing flow over replacing it.
5. Implement in the App's Existing Style
- Reuse current framework, routing, hooks, components, and package manager.
- Keep TypeScript precise and avoid broad
any types.
- Use Forma 36 for Contentful web app UI unless the app already uses another
deliberate design system.
- Preserve editor trust: show loading, empty, error, permission, and destructive
action states when relevant.
- Keep configuration UI explicit about what values are stored at installation
versus instance scope.
- Treat non-secret parameters as readable by space members.
- When runtime locations need installation parameters, prefer
sdk.parameters.installation. Do not add or preserve CMA app-installation
reads in sidebar, field editor, entry editor, page, dialog, home, mount
effects, render paths, or click handlers just to retrieve app configuration.
- Do not expose tokens or private credentials in client code.
- Keep changes narrow; avoid unrelated formatting, dependency churn, or
refactors.
6. Validate the Improvement
Run the closest available validation:
- targeted unit or component tests,
- typecheck,
- lint or formatter check,
- production build,
- local dev server smoke test,
- Contentful web app manual flow in a non-production space,
- grep or ripgrep for
appInstallation.getForOrganization,
appInstallation.get, and getForOrganization when installation-parameter
access is touched, confirming runtime config reads use
sdk.parameters.installation or documenting why a CMA app-installation call
remains,
- App Action, Function, or backend endpoint test when the change touches
server-side behavior.
When validation requires credentials or access the agent does not have, explain
exactly what remains for the user to verify.
7. Prepare Reviewable Output
If the user wants a commit or PR:
- create a focused branch using the user's repo convention when known,
- keep commits small and conventional,
- do not stage unrelated local files,
- include request context, implementation summary, validation, and open
questions in the PR draft.
If the user only asked for the fix, end with:
- context,
- assessment,
- implementation summary,
- validation,
- remaining risks or follow-up.
Guardrails
- Do not force a code change when the better answer is product clarification.
- Do not overfit one vague report without saying what is uncertain.
- Do not widen the scope into a rewrite unless the user asks.
- Do not assume app users have publication or distribution requirements unless
they say so.
- Do not claim Contentful plan features, SDK behavior, or API limits from memory
when current official docs should be checked.
Related Skills
contentful-custom-app-from-scratch - design and build a new custom app.
contentful-api - concrete REST and GraphQL API examples.
contentful-migration - content model migration scripts.
contentful-guide - Contentful concepts and API routing.
1---
2name: contentful-custom-app-enhancement
3description: >-
4 Improve, debug, and extend an existing Contentful App Framework custom app in
5 a customer's own repository. Use when users provide a bug report, feature
6 request, support note, customer feedback, or direct change request for an
7 existing custom app, including app configuration, sidebar, field editor,
8 dialog, page, home, App Action, Function, installation parameters, local
9 validation, or PR preparation. Also triggers on "fix my Contentful app",
10 "improve a custom app", "enhance App Framework app", "debug custom app",
11 "update sidebar app", and "custom app feature request". Not for creating a
12 brand new app from scratch (contentful-custom-app-from-scratch), generic API
13 examples (contentful-api), migrations (contentful-migration), or website
14 integration (contentful-nextjs).
15license: MIT
16metadata:
17 source: https://skillmd.com/skills/contentful/contentful-custom-app-enhancement
18 author: contentful
19 version: "2.0.0"
20allowed-tools: mcp__contentful-mcp__* mcp__plugin_contentful_contentful-mcp__*
21---
22
23# Contentful Custom App Enhancement
24
25Use this skill to turn a bug report, support note, or feature request into a
26small, reviewable improvement for an existing Contentful custom app.
27
28Default to the user's app repository and workflow. Do not assume a specific
29repository convention, publication process, or review policy unless the user
30provides one.
31
32When a comparable public Contentful Marketplace app or example in Contentful's
33public apps repository (`https://github.com/contentful/apps`) exists, use it as
34a best practice reference for App Framework patterns and UX polish without
35inheriting its release or distribution workflow.
36
37## Inputs
38
39Accept:
40
41- bug reports,
42- customer or editor feedback,
43- support tickets or issue links,
44- screenshots or screen recordings,
45- direct requests to change a known custom app,
46- partial notes about an App Framework behavior.
47
48If the source material is incomplete, continue with local code and provided
49context when the risk is low. Ask a targeted question when the missing answer
50could change the user-facing behavior, data writes, authentication, or
51deployment path.
52
53## Workflow
54
55### 1. Build the Request Context
56
57Identify:
58
59- original request and affected users,
60- current app behavior versus expected behavior,
61- Contentful location and workflow affected,
62- space, environment, content type, field, locale, and role assumptions,
63- external service or credential dependencies,
64- evidence available locally and evidence still missing.
65
66Separate confirmed facts from assumptions.
67
68### 2. Inspect the Existing App
69
70Before editing:
71
72- check repository status and avoid overwriting user changes,
73- inspect `package.json`, scripts, lockfile, and framework conventions,
74- locate the relevant app locations and SDK usage,
75- review existing tests and nearby components,
76- identify app definition, installation parameters, and deployment notes if they
77 exist,
78- confirm whether the app uses App SDK, React Apps Toolkit, Forma 36,
79 contentful-management, App Actions, Functions, or an external backend.
80
81For a reusable checklist, use
82[Enhancement checklist](references/enhancement-checklist.md).
83
84### 3. Decide Whether the Change Is Small Enough
85
86Proceed with implementation when the change can plausibly be:
87
88- scoped to one app,
89- explained in one short PR,
90- validated locally or in a sandbox,
91- reviewed without broad product redesign,
92- implemented without risky migrations or secret-handling changes.
93
94Pause and clarify when the request requires:
95
96- production data changes,
97- a new external auth model,
98- major content model redesign,
99- multi-app coordination,
100- new backend infrastructure,
101- unavailable Function or plan capabilities,
102- ambiguous editor behavior.
103
104### 4. Plan the Smallest Useful Change
105
106Write a short plan before editing:
107
108- files or app locations likely to change,
109- data read/write behavior,
110- UI and validation updates,
111- tests or manual verification to run,
112- risks and rollback path.
113
114Prefer improving the existing flow over replacing it.
115
116### 5. Implement in the App's Existing Style
117
118- Reuse current framework, routing, hooks, components, and package manager.
119- Keep TypeScript precise and avoid broad `any` types.
120- Use Forma 36 for Contentful web app UI unless the app already uses another
121 deliberate design system.
122- Preserve editor trust: show loading, empty, error, permission, and destructive
123 action states when relevant.
124- Keep configuration UI explicit about what values are stored at installation
125 versus instance scope.
126- Treat non-secret parameters as readable by space members.
127- When runtime locations need installation parameters, prefer
128 `sdk.parameters.installation`. Do not add or preserve CMA app-installation
129 reads in sidebar, field editor, entry editor, page, dialog, home, mount
130 effects, render paths, or click handlers just to retrieve app configuration.
131- Do not expose tokens or private credentials in client code.
132- Keep changes narrow; avoid unrelated formatting, dependency churn, or
133 refactors.
134
135### 6. Validate the Improvement
136
137Run the closest available validation:
138
139- targeted unit or component tests,
140- typecheck,
141- lint or formatter check,
142- production build,
143- local dev server smoke test,
144- Contentful web app manual flow in a non-production space,
145- grep or ripgrep for `appInstallation.getForOrganization`,
146 `appInstallation.get`, and `getForOrganization` when installation-parameter
147 access is touched, confirming runtime config reads use
148 `sdk.parameters.installation` or documenting why a CMA app-installation call
149 remains,
150- App Action, Function, or backend endpoint test when the change touches
151 server-side behavior.
152
153When validation requires credentials or access the agent does not have, explain
154exactly what remains for the user to verify.
155
156### 7. Prepare Reviewable Output
157
158If the user wants a commit or PR:
159
160- create a focused branch using the user's repo convention when known,
161- keep commits small and conventional,
162- do not stage unrelated local files,
163- include request context, implementation summary, validation, and open
164 questions in the PR draft.
165
166If the user only asked for the fix, end with:
167
168- context,
169- assessment,
170- implementation summary,
171- validation,
172- remaining risks or follow-up.
173
174## Guardrails
175
176- Do not force a code change when the better answer is product clarification.
177- Do not overfit one vague report without saying what is uncertain.
178- Do not widen the scope into a rewrite unless the user asks.
179- Do not assume app users have publication or distribution requirements unless
180 they say so.
181- Do not claim Contentful plan features, SDK behavior, or API limits from memory
182 when current official docs should be checked.
183
184## Related Skills
185
186- `contentful-custom-app-from-scratch` - design and build a new custom app.
187- `contentful-api` - concrete REST and GraphQL API examples.
188- `contentful-migration` - content model migration scripts.
189- `contentful-guide` - Contentful concepts and API routing.