Skip to content

feat(cli): prs inspect <skill> --layers debugging command #203

@mrwogu

Description

@mrwogu

Context

When skills are composed across multiple registry layers (e.g., Comarch's 4-layer architecture: company → product → BU → project), debugging which layer contributed which property becomes difficult. There is no way to see the composition breakdown without manually tracing imports and extends.

Parent issue: #199 (Phase 2)
Spec: docs/superpowers/specs/2026-03-30-skill-overlay-extends-design.md §13
Review: docs/superpowers/specs/2026-03-30-skill-overlay-extends-review.md §10

Proposal

Add a new CLI command prs inspect <skill-name> --layers that shows each layer's contribution to a composed skill.

Example output

$ prs inspect clm512-expert --layers

Skill: clm512-expert
Layers: 3

Layer 1 — @clm5core/skills/clm512-expert (base)
  description: "CLM 5.12+ development expert"
  content: ✓ (247 lines)
  references: [spring-patterns.md]
  allowedTools: [Read, Bash]

Layer 2 — @bu/skills/clm512-expert (@extend)
  description: "CLM 5.12+ Expert z kontekstem BU CRM Retail" (replaces Layer 1)
  references: [architecture.md, modules.md, patterns.md, integrations.md] (appended)

Layer 3 — project/.promptscript/project.prs (@extend)
  allowedTools: [Read, Bash, Write] (replaces Layer 2)

Composed result:
  description: "CLM 5.12+ Expert z kontekstem BU CRM Retail"
  content: 247 lines
  references: 5 files (spring-patterns.md, architecture.md, modules.md, patterns.md, integrations.md)
  allowedTools: [Read, Bash, Write]

Design considerations

  • Read-only command — no resolver changes needed, only inspection of the resolution pipeline
  • Should work with --format json for programmatic consumption
  • Must handle skill composition (@use phases) and extensions (@extend) independently
  • Should show merge strategy applied per property (replace / append / shallow-merge)

Acceptance criteria

  • prs inspect <skill-name> --layers shows per-layer property contributions
  • Each layer shows source path and composition mechanism (@extend, @use)
  • Merge strategy is indicated for overridden properties
  • --format json outputs structured JSON
  • Works with multi-registry configurations
  • Handles missing/unresolvable skills gracefully with actionable error messages
  • Unit and integration tests
  • CLI help text and documentation

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions