Developer Portal Integration¶

This guide describes how developers discover, browse, and deploy SkillMeat artifacts directly within Backstage's developer portal surface.

Overview¶

SkillMeat's Backstage plugin surfaces artifact discovery and deployment capabilities in two key developer workflows:

Entity Pages — View artifact deployment status, versions, and health directly on your service catalog entries
Scaffolder Templates — Provision new projects with pre-loaded AI context and automation workflows

This guide covers the developer experience of using these surfaces. For platform engineer setup, see Catalog Integration Guide.

Prerequisites¶

Before using SkillMeat in Backstage, ensure:

The SkillMeat Backstage plugin is installed and registered in your Backstage app
Your organization's artifact catalog is connected via the SkillMeat catalog provider
You have access to the Backstage catalog and scaffolder
Your organization has deployed SkillMeat artifacts to share (skills, commands, agents, context packs, etc.)

Accessing the Artifact Portal¶

Entity Page Integration¶

SkillMeat appears as a tab on your service's entity page within Backstage's catalog.

Navigation:

Go to Catalog in your Backstage sidebar
Search for and open your service or project entity
Click the SkillMeat tab (if present; requires platform engineer setup)

You'll see three cards summarizing your deployment's artifact state:

Card	Shows
Context Card	Deployment context, bundle version, and sync status
BOM Card	Bill of materials — list of deployed artifacts with signature status
Drift Card	File-level drift detection highlighting changes since last sync

Intelligence Tab (Optional)¶

If your organization enables telemetry analytics, an Intelligence tab appears combining context cards with workflow effectiveness metrics and agentic performance signals.

Browsing Artifacts¶

Overview¶

The SkillMeat plugin integrates with Backstage's catalog discovery. Artifacts appear as discoverable entities within your catalog, alongside services, libraries, and other IDP assets.

Artifact Types You May Encounter:

Skills — Reusable Claude code capabilities (canvas design, analysis, etc.)
Commands — CLI automation (deployment, validation, etc.)
Agents — Specialized subagents with pre-configured knowledge
Workflows — Multi-step automation orchestrations
Context Packs — Pre-built AI context for specific domains (compliance, fintech, etc.)
Bundles — Curated collections of related artifacts

Discovering Artifacts in the Catalog¶

Artifact Visibility

Artifacts must be registered with the SkillMeat catalog provider by your platform team. See Catalog Integration Guide for provider setup.

Navigate to Catalog → search bar at top
Search by:
Artifact name (e.g., "canvas design", "python refactor")
Type filter — narrow to Skills, Commands, Agents, etc.
Owner or team — find artifacts maintained by specific teams
Tags — filter by domain (e.g., compliance, fintech, performance)
Click an artifact to view its detail page
You'll see:
Description — What the artifact does
Versions — Available versions and release history
README — Full documentation and usage examples
Dependencies — Other artifacts this one requires
Ownership — Team or person responsible

Viewing Artifact Details¶

Each artifact detail page contains:

Header Section: - Artifact name, type badge, and owner - Star/favorite button (to save for quick access) - Version selector dropdown

Tabs:

Tab	Contains
Overview	Artifact description, tags, and key metadata
Readme	Full documentation and usage instructions
Versions	Release history with changelog entries and available versions
Dependencies	Required and recommended artifacts
Deployments	Which projects currently use this artifact

Actions: - Deploy button — Deploy this artifact to your project (see Deploying Artifacts below) - View Source — Link to GitHub repository or source - Copy Identifier — Quick copy of artifact reference for use in scripts

Deploying Artifacts¶

Self-Service Deployment¶

Developers can deploy artifacts directly from the catalog to projects they own.

Step 1: Locate the Artifact¶

Navigate to Catalog and search for the artifact you need
Click the artifact to open its detail page

Step 2: Initiate Deployment¶

Click the blue Deploy button on the artifact detail page.

A deployment modal opens with options:

Option	Description
Target Project	Select which project to deploy to (dropdown; shows your accessible projects)
Deployment Method	Local (write directly to `.claude/`) or Pull Request (create a PR for team review)
Branch Name	(PR method only) Name of the feature branch (e.g., `chore/add-canvas-skill`)
PR Title	(PR method only) Title for the pull request on GitHub
Description	(PR method only) Optional markdown body for the PR
Reviewers	(PR method only) Comma-separated GitHub usernames to request review

Step 3: Confirm Deployment¶

Deployment Impact

Deploying to a project writes artifact files to .claude/ in that project. Local deployments take effect immediately; PR deployments require code review and merge.

Review your selections and click Deploy or Create Pull Request.

Local Deploy Output:

✓ Deployed canvas-design to my-service-project
  Files: skill.md, README.md, templates/ 
  Location: ./.claude/skills/canvas-design/

PR Deploy Output:

✓ Pull request created
  URL: https://github.com/my-org/my-service-project/pull/42
  Branch: chore/add-canvas-skill
  Files: 1 artifact, 3 files changed

Using Scaffolder Templates¶

Scaffolder templates provide a guided project provisioning workflow that can inject SkillMeat artifacts automatically.

Triggering a Template¶

Navigate to Create in the Backstage sidebar
Browse or search for scaffolder templates
Look for templates tagged with skillmeat or ai-context
Click a template to begin the scaffolding wizard

Template Steps¶

Templates typically include:

Step 1: Project Details - Project name and description - Owner (team or individual) - Repository URL (for Git-based projects)

Step 2: AI Context Selection (SkillMeat-enabled templates) - Available context packs and skill bundles - Checkboxes to select which artifacts to inject - Organization policies and required artifacts (pre-selected)

Step 3: Advanced Options - Git branch naming - Custom configuration - Integration options (CI/CD, compliance, monitoring)

Artifact Injection During Scaffolding¶

Once you complete the template wizard, the scaffolder:

Creates your project repository on GitHub
Runs the SkillMeat scaffolder backend action to inject selected artifacts
Writes artifacts to .claude/ in the new repository
Configures deployment settings if applicable
Optionally creates initial PR with context loaded

Example Output:

✓ Project created: my-fintech-service
  Repository: https://github.com/my-org/my-fintech-service

✓ AI Context injected:
  - compliance-context-pack/
  - python-refactor-skill/
  - regulatory-validator-command/

✓ Initial PR created with artifacts
  URL: https://github.com/my-org/my-fintech-service/pull/1

Integration with CI/CD¶

Artifact Status in Deployments Tab¶

If your SkillMeat integration tracks deployments, you can monitor:

Deployment history — Which artifacts were deployed when
PR status — Open, merged, or closed deployment PRs
Sync status — Whether deployed artifacts are up-to-date with source
Drift detection — Files that have changed locally vs. the deployed version

This information appears in a Deployments tab on your entity page (requires telemetry integration).

Using Artifacts in Workflows¶

Deployed artifacts are immediately available to Claude Code within the project:

# After deploying, artifacts are in .claude/
ls -la ./.claude/skills/
ls -la ./.claude/commands/

# Reference in Claude sessions
# Skills and commands activate automatically in Claude Code

Artifacts become active context for any Claude AI session operating on the project.

Search and Discovery¶

Catalog Search¶

Use Backstage's search to find artifacts:

Search Syntax:

# By artifact type
type:skill
type:command
type:agent
type:workflow
type:context-pack

# By tag
tag:compliance
tag:fintech
tag:performance

# By owner
owner:platform-team
owner:alice

# Combined
type:skill tag:analysis owner:platform-team

Filtering in Artifact Views¶

In the catalog grid view, use filter controls to:

Type — Show only specific artifact types
Tag — Filter by domain or category
Owner — Find artifacts by team ownership
Status — Show only available (vs. deprecated or archived) artifacts
Scope — Show user scope (global) or local scope (project-specific) artifacts

Viewing Deployment Context¶

Context Card¶

The Context Card on your entity's SkillMeat tab shows:

Project ID — Unique SkillMeat deployment identifier
Deployment Bundle — Active bundle version
Sync Status — Whether deployed artifacts match upstream sources
Last Sync — Timestamp of last sync operation
Artifact Count — Number of deployed artifacts

Bill of Materials (BOM) Card¶

The BOM Card lists:

Artifacts deployed — Name, type, version for each artifact
Signature status — Whether each artifact is signed (security compliance)
Artifact versions — Which version of each artifact is deployed
Metadata — Tags, owner, scope for each artifact

Example BOM view:

Deployed Artifacts: 5

✓ canvas-design (v2.1.0)          Signed
✓ python-refactor (v1.3.0)         Unsigned
✓ compliance-context-pack (v3.0.0) Signed
✓ my-custom-skill (local)          Unsigned
✓ validation-workflow (v1.0.0)      Partial

Drift Card¶

The Drift Card shows:

Drift status — Whether any deployed files have changed locally
Changed files — Line-by-line breakdown of modifications
Drift severity — Critical (modified logic), Minor (docs/comments), None

Example:

Drift Detected: 3 files

✗ .claude/skills/canvas-design/SKILL.md (Minor)
  Lines 5-8 modified

✗ .claude/commands/deploy/cli.py (Critical)
  Function signature changed on line 42

⚠ .claude/context-pack/compliance/README.md (Minor)
  Comments updated

Accessibility¶

All SkillMeat portal surfaces support full keyboard navigation:

Tab — Move between controls
Enter/Space — Activate buttons, toggle checkboxes, select options
Arrow keys — Navigate dropdown options, table rows
Escape — Close modals and dropdowns

SkillMeat cards and deployment modals include:

Semantic HTML with <button>, <table>, <form> landmarks
ARIA labels for icon-only buttons and status indicators
Table headers with proper association to data cells
Form field labels and validation error announcements

Screen Reader Testing

SkillMeat artifact portal supports major screen readers (NVDA, JAWS, VoiceOver). Report accessibility issues to your platform team.

Troubleshooting¶

SkillMeat Tab Not Visible¶

Problem: The SkillMeat tab doesn't appear on your entity page.

Solutions: - Confirm your entity has the skillmeat.io/deployment-set-id or skillmeat.io/project-id annotation (added by catalog provider) - Verify the SkillMeat plugin is registered in your Backstage app-config.yaml - Check your browser console for JavaScript errors (F12 → Console tab) - Refresh the page (Ctrl+Shift+R)

Artifacts Not Showing in Catalog¶

Problem: You search the catalog but SkillMeat artifacts don't appear.

Solutions: - Verify the SkillMeat catalog provider is configured (see Catalog Integration Guide) - Check that artifacts are actually registered with SkillMeat - Try searching by artifact name directly instead of filters - Ask your platform team to verify the provider sync completed: skillmeat catalog refresh

Problem: Clicking Deploy shows an error or the modal won't open.

Solutions: - Check that the SkillMeat API is reachable from your Backstage instance - Verify the skillmeat.baseUrl in app-config.yaml is correct - Check browser console (F12 → Console) for network errors - Confirm you have permission to write to the target project - If using PR deploy, verify your Git credentials are configured

Deployment Hangs or Times Out¶

Problem: Clicking Deploy seems to hang, or you see a timeout error.

Solutions: - Network connectivity — verify Backstage can reach SkillMeat API and GitHub - Large artifacts — artifacts over 10MB may take longer; wait a bit longer - Token issues — for PR deploy, confirm your GitHub PAT is valid and has repo scope - Check platform team logs for backend errors: docker logs skillmeat-api (if containerized)

Permission Denied on PR Deploy¶

Problem: Deploy via PR fails with "Permission denied" or "Unauthorized".

Solutions: - Missing token: Ensure you've configured GitHub authentication in Backstage - Insufficient scopes: Your GitHub PAT needs the repo scope (not just public_repo) - Repository access: Confirm you have write access to the target repository - Archived repository: Some orgs archive inactive repos — verify the repo is not archived

Best Practices¶

Choosing Deployment Method¶

Method	When to Use	When NOT to Use
Local Deploy	Testing new artifacts locally; small experimental changes	Production environments; team-shared projects; regulated domains
PR Deploy	Team environments; requiring code review; compliance-regulated projects	Rapid prototyping; learning/exploration

Artifact Selection¶

Start small — Deploy one artifact at a time to understand its impact
Read documentation — Check the artifact's README before deploying
Review dependencies — Some artifacts require others (check Dependencies tab)
Check versions — Prefer stable versions (v1.0.0) over beta tags (v1.0.0-beta)

Managing Deployed Artifacts¶

Monitor drift — Check the Drift card regularly; merged changes may diverge from upstream
Update regularly — New versions include bug fixes and improvements
Remove unused artifacts — Undeploy artifacts your project no longer uses
Document customizations — If you modify an artifact locally, record why (in drift comments)

Next Steps¶

Sync & Version Rollback Guide — Learn how to update or roll back deployed artifacts
Deploying Artifacts Guide — Detailed local and PR deployment workflows
Browsing Artifacts Guide — Advanced artifact discovery and search patterns
Governance & Permissions — How your organization controls artifact adoption

Support & Feedback¶

For issues or questions about the SkillMeat developer portal:

Technical issues: File an issue in your organization's SkillMeat tracking
Feature requests: Contact your platform engineering team
Documentation feedback: Submit corrections via your feedback channel

Developer Portal Integration¶

Overview¶

Prerequisites¶

Accessing the Artifact Portal¶

Entity Page Integration¶

Intelligence Tab (Optional)¶

Browsing Artifacts¶

Overview¶

Discovering Artifacts in the Catalog¶

Viewing Artifact Details¶

Deploying Artifacts¶

Self-Service Deployment¶

Step 1: Locate the Artifact¶

Step 2: Initiate Deployment¶

Step 3: Confirm Deployment¶

Using Scaffolder Templates¶

Triggering a Template¶

Template Steps¶

Artifact Injection During Scaffolding¶

Integration with CI/CD¶

Artifact Status in Deployments Tab¶

Using Artifacts in Workflows¶

Search and Discovery¶

Catalog Search¶

Filtering in Artifact Views¶

Viewing Deployment Context¶

Context Card¶

Bill of Materials (BOM) Card¶

Drift Card¶

Accessibility¶

Keyboard Navigation¶

Screen Reader Support¶

Troubleshooting¶

SkillMeat Tab Not Visible¶

Artifacts Not Showing in Catalog¶

Deploy Modal Fails to Open¶

Deployment Hangs or Times Out¶

Permission Denied on PR Deploy¶

Best Practices¶

Choosing Deployment Method¶

Artifact Selection¶

Managing Deployed Artifacts¶

Next Steps¶

Support & Feedback¶