# Backstage App

> Apply Backstage adopter-app composition and configuration conventions. Use when editing app packages, backend packages, backstage.json, or app-config files.

- Skill: `paulasilvatech/backstage-app` (Agent Skill)
- Install (CLI): `npx skillmds@latest add paulasilvatech/backstage-app`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paulasilvatech/backstage-app/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: paulasilvatech (https://skillmd.com/u/paulasilvatech)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/paulasilvatech/backstage-app

---


<!-- Generated from harness/github-copilot/plugins/backstage-expert/instructions/backstage-app.instructions.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->

# Backstage Application Conventions

These instructions apply to Backstage adopter application composition and configuration. They
are authoritative for app-owned frontend, backend, version metadata, and config layering in the
matched files; repository-specific architecture and stricter security policy win on conflict.

## Application Boundaries

- Keep app wiring in `packages/app` and backend wiring in `packages/backend`.
- Read `backstage.json` and package versions before using an API example.
- Prefer the new frontend and backend systems for new work; preserve explicit legacy or dual
  compatibility when the repository requires it.
- Register plugins and modules through supported extension points instead of importing internals.

## Configuration

- Keep environment-neutral defaults in `app-config.yaml` and environment overrides in the
  repository's existing config layers.
- Resolve secrets from environment variables or an approved secret provider.
- Validate stitched configuration with `backstage-cli config:check` through the repository's
  existing script or package-manager command.
- Keep frontend-visible config free of secrets.

## Conventions

| Rule | Rationale |
| --- | --- |
| Align all `@backstage/*` package versions with the repository policy. | Mixed releases cause runtime and type incompatibilities. |
| Separate app composition from plugin implementation. | Package boundaries keep plugins reusable and testable. |
| Make environment selection explicit. | Hidden config layers cause deployment-only failures. |

## Do / Do Not

| Do | Do not |
| --- | --- |
| Inspect existing scripts and config schema before editing. | Paste version-sensitive examples blindly. |
| Keep sign-in and delegated provider access separate. | Treat a provider token as Backstage user identity. |
| Run targeted app or backend validation. | Run release or deployment commands as routine checks. |

## Checklist Before Opening a PR

- [ ] The target Backstage version and application mode are recorded.
- [ ] New, legacy, or dual frontend mode is explicit where relevant.
- [ ] Config layers and schemas validate without exposing secrets.
- [ ] Package-local tests and typechecking pass.
- [ ] The change contains no unrelated edits or placeholders.

## References

- [Backstage getting started](https://backstage.io/docs/getting-started/)
- [Backstage configuration](https://backstage.io/docs/conf/)