Hc scaffold service
Skill nnovaeshc/hc-scaffold-service/skills/hc-scaffold-service
Creates a new service, component, or other resource from any registered Backstage software template through conversation, without opening the Backstage UI - walks the template's own schema and infers values from context, catalog precedent, and conversation, so it keeps working as new templates are added to the catalog. INVOKE FOR the /hc-scaffold-service command, or requests to scaffold, create, or spin up a new service, component, API, microservice, or Lambda from a Backstage template (e.g. "create a service for payment callbacks", "scaffold a Lambda API", "new service from template") - even if the user never says the word "Backstage". SKIP for code changes inside an existing app/repo (e.g. "create a React component in this app"), general questions about Backstage or its catalog, or ops tasks against services that already exist (docker compose, deploys, restarts).From its SKILL.md
npx -y skills add nnovaeshc/hc-scaffold-service --skill hc-scaffold-serviceAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
17.9 KB, as published. Nobody here has run it
hc-scaffold-service
Create a new service or component from a Backstage software template through conversation, without opening the Backstage UI or learning the scaffolder API.
When to Use
- The user wants to create a new service, component, or resource using Backstage
- The user mentions scaffolding, templates, or creating from a template
- The user explicitly invokes
/hc-scaffold-service
Workflow
Copy this checklist and check off each step as you complete it. Follow it in order. Stop immediately on any failure.
Scaffold Progress:
- [ ] 1. Preflight: verify MCP access (before asking anything)
- [ ] 2. Understand intent
- [ ] 3. Select template
- [ ] 4. Fetch full template schema
- [ ] 5. Check for secrets
- [ ] 6. Check destination scope
- [ ] 7. Classify parameters
- [ ] 8. Collision check
- [ ] 9. Ask only the gaps (validate every answer)
- [ ] 10. Review before submission
- [ ] 11. Confirm ownership and submission
- [ ] 12. Submit (pre-submit constraint gate)
- [ ] 13. Report task URL immediately
1. Preflight: Verify MCP Access (BEFORE asking anything)
Check 1 - Capabilities present:
- Call
tools/liston the Backstage MCP server - Verify BOTH capabilities exist:
- Catalog query capability (tool name contains "catalog" and "query-catalog-entities")
- Scaffolder execute capability (tool name contains "scaffolder" and "execute-template")
- Match by capability, not exact string - tool names may be prefixed (e.g.,
backstage.catalog.query-catalog-entities)
If missing capabilities:
The Backstage MCP server does not provide the required capabilities.
Missing: [list what's missing: "catalog query" or "scaffolder execution" or both]
Check your MCP server configuration. The skill needs both catalog query
and scaffolder execution capabilities to function.
STOP. Do not ask any questions. Do not proceed.
Check 2 - Live access:
- Query catalog for
kind: Templatewithfieldsandlimit(this is the template list you need anyway) - If denied or transport error:
The Backstage MCP server refused the request.
[Include the actual error message]
Verify your Backstage authentication and that the MCP server has
permission to access both catalog and scaffolder APIs.
STOP. Do not ask any questions. Do not proceed.
- If zero templates returned:
The Backstage catalog contains no templates.
The catalog query succeeded but returned zero Template entities.
Verify templates are registered in your Backstage instance.
STOP. Do not ask any questions. Do not proceed.
Scaffolder permission cannot be checked without side effects. It will surface at submission if denied.
Three distinct failure modes: config (missing tools), auth (denied call), empty catalog. Never collapse into generic "Backstage unavailable".
2. Understand Intent
Read the user's stated intent and the ambient repository context:
- What are they trying to build?
- What template might match?
- What values can be inferred from the working directory, git remote, or recent conversation?
- Did they name a specific destination? A personal account, a named org/company other than the default, or language like "not through work" - note it. Most requests name no destination and carry no assumption; only an explicit one matters here.
3. Select Template
Present matching templates from the catalog query (you already have the list from preflight Check 2).
If the user named a specific template, verify it exists. If it does not exist in the catalog, report that and stop - never invent a template name from memory.
If step 2 noted an explicit destination: pick the best catalog match without asking, then immediately fetch the schema (step 4) and finish destination scope (step 6) before any user-facing question. Template confirmation waits until destination is resolved (in-scope, user chose the allowed destination, or hand-off).
Otherwise: confirm the template choice explicitly before continuing.
4. Fetch Full Template Schema
Call get-catalog-entity with the chosen template's entity reference to fetch the raw spec.parameters.
Before classifying fields, read reference.md. It contains the schema walk algorithm, precedence rules, and Backstage ui:field dialect.
5. Check for Secrets
Scan the full parameters tree for any field declaring secrets:
ui:field: Secretformat: passwordx-backstage-secret: true
If found, refuse and redirect:
This template requires secrets to be entered directly.
For security, secrets cannot be provided through this interface since they would
pass through the LLM context. Use the Backstage web UI for this template:
https://backstage.platform.healthcare.com/create/templates/[templateRef]
STOP. Do not proceed with this template.
6. Check Destination Scope
Only relevant if step 2 noted an explicit destination. Skip this step entirely otherwise.
Scan the parameters tree for destination-scoping constraints: a field constrained to one legal value
via enum where the field is account/owner/org-shaped, or a RepoUrlPicker's allowedHosts /
allowedOwners. See reference.md for how to recognize these.
If the user's stated destination is not among what the constraint allows:
This template can only create [resource] under [what the schema allows, quoted]. It cannot
target [what the user asked for].
Create it there anyway, or handle this outside Backstage instead (e.g. gh CLI, GitHub MCP, AWS CLI)?
STOP. Do not proceed into template classification until the user answers. If they choose outside Backstage, hand off to the ordinary tool for that job and end the skill's involvement here.
If the destination matches what the schema allows, or the user named no destination, proceed normally - the value is Determined by the constraint per step 7, taken silently, shown in review.
7. Classify Parameters
Walk spec.parameters pages in order. For each field:
Read the schema:
- JSON Schema type (string, number, boolean, array, object)
enum,enumNames,default,format,required- Constraint keywords:
pattern,minLength/maxLength, numeric bounds, item counts,const(seereference.md) ui:field,ui:optionsdependencies,$ref,items(seereference.md)
Classify by precedence (first match wins):
- Determined: constraint pins one value, or has a
default, or composable fromui:options - Inferable: sibling field, catalog precedent, or stated intent implies it
- Must-ask: no other source
For catalog precedent: Query existing entities sharing the same owner and type. If they consistently use a specific value for this field, propose it and name the precedent. Example: "Your other services use production for environment - use that here?" Never encode business rules (no team-to-account maps, no hardcoded environment names).
Recognized ui:field widgets (see reference.md for behavioral details):
OwnerPicker→ resolve togroup:<name>from catalog GroupsRepoUrlPicker→ compose location from host/owner/repo partsEntityPicker→ select existing catalog entity- Unrecognized → fall back to declared JSON Schema type, no special behavior
8. Collision Check
Before asking anything, verify the proposed component name:
- Catalog check: query for existing entity with that name
- GitHub check: if template uses
RepoUrlPicker, check if repo already exists
If collision found, modify the name (append suffix or prompt for alternative) and re-check.
9. Ask Only the Gaps
For each must-ask field, ask one question at a time, each with a recommendation.
Do not script dialogue. Phrasing is your judgment. The form's question text is the floor.
Validate every answer against the schema. Check each value the moment it is given, against the constraint keywords from step 7. See reference.md for the keyword checks and repair rules.
If a value violates a declared constraint, name the field, quote the constraint as the schema declares it, say what specifically is wrong, and propose one compliant candidate:
`<field>` must <constraint as declared in the schema>.
"<what was given>" <what specifically violates it>.
Use `<proposed candidate>`? (or give another value)
Never accept the violating value, and never rewrite it silently. If no repair follows mechanically from the constraint, say what is required and ask again.
Only enforce constraints the schema declares. Never reject a value for looking unconventional.
Handle time pressure: if the user says "skip the questions" or "just do it", you still MUST present the review and require explicit confirmation. Never skip the review or confirmation gates.
Interaction floor: when you have nothing to go on, ask what the Backstage web form asks. When you have precedent or constraints, reduce the question count.
10. Review Before Submission
Present a provenance-tagged review table. See examples.md for the shape.
Tag every value by source:
- "You stated"
- "Default" (from schema)
- "Constraint" (pinned by schema)
- "Catalog precedent" (name the precedent: "same as X service")
- "Derived from options"
List any conditionally hidden fields that will NOT be submitted due to dependencies.
Every value in the review has already passed validation. Never present a value you know violates a constraint.
11. Confirm Ownership and Submission
Two explicit confirmations required, regardless of confidence:
- Ownership: "This will be owned by
group:<name>. Confirm?" - Submission: "Submit this to Backstage scaffolder?" (Yes/No)
If No: return to step 9 to adjust values.
Never submit without explicit confirmation.
12. Submit
Constraint gate first. Re-validate every value in the payload against the constraints from step 7 - engineer-stated, default, catalog precedent, and anything you derived from context alike. Derived values are as fat-fingerable as typed ones.
If any value fails: STOP. Do not call execute-template. Report which field and which constraint, then return to step 9. This is the last chance - the call returns a taskId, not a verdict, and a failed task must not be resubmitted.
Call execute-template with:
templateRef: the chosen template's entity referencevalues: object with all determined/asked field values
Exclude conditionally hidden fields per the dependencies rules in reference.md.
Response: the call returns { taskId } only. This is NOT success - it means the task started.
13. Report Task URL Immediately
Task submitted: https://backstage.platform.healthcare.com/scaffolder/tasks/[taskId]
Ask whether to follow along: "Watch progress, or check later?"
If "check later": hand back the URL and how to ask for status.
If "watch": poll get-scaffolder-task-logs with the after cursor for incremental logs. Report step completions, not raw log dumps.
On task success: report declared output.links per the matrix in reference.md (repository, pull request, catalog entry).
On task failure: report the failing step with log excerpt. Do NOT auto-resubmit - earlier steps have side effects.
On access denied at submission: report which call was refused and stop. Never retry with different credentials.
Constraints (NEVER / ALWAYS)
| Rule | Reason |
|---|---|
| NEVER ask the user anything before both preflight checks pass | Preflight failures are config/auth problems, not questions to negotiate |
| NEVER invent template names from memory | The catalog is authoritative; if a template is not listed, it does not exist |
| NEVER skip the review or confirmation gates | Explicit confirmation is required regardless of confidence |
| NEVER submit without the user's explicit "yes" to submission | This is not negotiable |
| NEVER resubmit after a task failure | Earlier steps have side effects; retrying is destructive |
| NEVER encode business rules | No team-to-account maps, no env names, no AWS accounts in the skill - use catalog precedent instead |
| NEVER fetch the whole catalog | Every query MUST have fields and limit |
| NEVER proceed with secrets-declaring templates | Refuse and redirect to Backstage UI |
| NEVER submit a value that violates a declared schema constraint | Submission is one-shot and cannot be retried; the scaffolder has side effects |
| NEVER enforce a constraint the schema does not declare | Invented rules block legal values on templates the skill has never seen |
NEVER ask the user anything after noting an explicit destination until get-catalog-entity has run and destination scope (step 6) is checked | Template-confirm questions hide out-of-scope destinations behind an earlier gate |
| NEVER silently substitute a constraint-pinned destination for one the user explicitly named outside it | The user asked for a destination Backstage cannot produce; silently rerouting hides that from them |
| ALWAYS match tools by capability, not exact name | Gateway prefixing and configuration flags change tool names |
ALWAYS read reference.md after fetching the template entity and before classifying parameters | The dialect details live there |
| ALWAYS exclude conditionally hidden fields from submission | Check dependencies rules |
| ALWAYS report provenance in the review | The user must see where every value came from |
Rationalization Table (Built from Baseline Failures)
This table shows why defaults fail and what rule prevents each failure:
| Without this rule... | The model does... | Which causes... | Guarded by... |
|---|---|---|---|
| Preflight verification | Asks template questions before checking MCP access | User wastes time on a conversation that cannot submit | Preflight checks BEFORE any questions |
| Fail-fast on config | Treats missing tools as "Backstage down" | Generic error instead of actionable config fix | Three distinct stop messages |
| Capability matching | Hardcodes catalog.query-catalog-entities | Fails when gateway prefixes tool names | Match by capability (substring/keyword) |
| Template existence check | Invents template names from training data | Submits to a template that does not exist | Query catalog; if not found, stop |
| Secrets refusal | Asks user to provide secrets in chat | Secrets pass through LLM context | Scan for secrets fields; refuse before asking |
| Collision check | Asks all questions then submits | Task fails because name already taken | Check catalog and GitHub before asking |
| Constraint validation | Submits whatever was typed, assuming the scaffolder will validate | Task fails mid-run after side effects, and no retry is allowed | Validate at answer time and again before submit |
| Destination scope check | Silently creates under the org-pinned account/owner, or asks to confirm the template before fetching schema / checking scope | Surprise ownership, or the destination-scope stop never runs | When an explicit destination was noted: fetch entity and check scope before any question; ask instead of substituting |
| Explicit confirmation | Submits immediately after gathering values | User has no chance to review or abort | Two-gate confirmation (ownership + submission) |
| No auto-resubmit | Retries task after failure | Re-runs side effects, creates duplicates | On failure, report and stop |
| Precedent over hardcoding | Encodes "team X owns account Y" | Breaks when teams or accounts change | Query catalog for precedent; never hardcode business logic |
| Context budget | Fetches full catalog on every query | Exhausts context with thousands of entities | Require fields and limit on every catalog query |
Failure Modes
See examples.md for exact stop-message wording.
Config failure: missing capabilities → name what's missing, point at MCP config, stop.
Auth failure: denied call → report the error, stop.
Empty catalog: zero templates → report, stop.
Secrets template: redirect to Backstage UI, stop.
Constraint violation: name the field and the constraint, propose a compliant candidate, do not submit.
Destination outside scope: name what the template can produce, offer to proceed there or hand off to default tooling, do not submit for the unsupported destination.
Task failure: report failing step, do not resubmit.
Access denied at submit: report which call was refused, stop.
Notes
- The Backstage web form is the floor, not the target. Reduce question count by inferring and deriving.
reference.mdandexamples.mdare read on demand per explicit instruction above. They use synthetic field names only.- Requires Sonnet or better.
model: sonnetpins the model for the invoking turn only; the session model resumes on the next prompt. The pin is advisory - an orgavailableModelsallowlist can exclude it silently, and no runtime model check exists. - Background polling is out of scope - the MCP gateway requires per-user auth that a detached poller cannot obtain.
- Backstage attributes actions to a shared
mcp-gatewayservice principal, not the individual engineer. This is accepted.