CUI Marketplace Architecture Skill

Standards for marketplace component architecture ensuring self-contained skills, proper skill usage in agents/commands, clean reference patterns, and bundle organization principles.

Workflow

Step 1: Load Architecture Standards

CRITICAL: Load all architecture standards based on validation context.

1. Always load core architecture rules:

   Read: standards/architecture-rules.md
   Read: standards/reference-patterns.md

   These provide fundamental marketplace architecture principles always needed.

2. Conditional loading based on context:

   • If validating skills for self-containment:

     Read: standards/self-containment-validation.md

   • If validating agents/commands for skill usage:

     Read: standards/skill-usage-patterns.md

   • If calculating compliance scores:

     Read: standards/scoring-criteria.md

Step 2: Apply Architecture Rules

When to Execute: During component creation or validation

What to Validate:

1. Skill Self-Containment:

   • All standards content in skill's standards/ directory
   • No external file references (../../../../)
   • No absolute paths (~/git/cui-llm-rules/)
   • Only external URLs and skill references allowed

2. Agent/Command Skill Usage:

   • Agents using standards must invoke Skills
   • Skill tool in tools list if invoking skills
   • No direct standards file references
   • Proper skill invocation pattern in workflow

3. Reference Pattern Compliance:

   • Categorize all references (internal/external/skill)
   • Validate allowed patterns only
   • Report prohibited patterns with fixes

4. Bundle Architecture Compliance:

   • All bundle skills self-contained
   • All bundle agents use skills properly
   • Bundle follows cohesion principles
   • Components properly organized

Step 3: Calculate Compliance Scores

When to Execute: After validation

Scoring Logic:

1. Skill Self-Containment Score (0-100):

   • Base: 100 points
   • Deduct 20 points per external file reference
   • Deduct 10 points per documentation-only external ref
   • Minimum: 0

2. Agent Skill Usage Score (0-100):

   • Only if agent uses standards
   • Base: 100 points
   • Deduct 30 points if missing Skill in tools
   • Deduct 30 points if no Skill: invocations
   • Deduct 20 points per direct file reference

3. Bundle Architecture Score:

   • Weighted average: Skills 60%, Agents 30%, Commands 10%

Step 4: Generate Fix Recommendations

When to Execute: After detecting violations

Fix Strategies:

1. Internalize External Content:

   • Copy external files to skill/standards/
   • Convert .adoc to .md if needed
   • Update references to internal paths

2. Convert to Skill Usage:

   • Add Skill to agent tools list
   • Replace direct refs with Skill: invocations
   • Remove obsolete Read: statements

3. Remove Documentation Links:

   • If reference only in ## References section
   • If not actually loaded in workflow
   • Replace with external URL if available

Common Validation Patterns

Pattern 1: Validate Skill Self-Containment

# Scan for external references
grep -E "(\.\.){3,}|~/git/cui-llm-rules" skill/SKILL.md

# Should return nothing for compliant skill

Pattern 2: Check Agent Skill Usage

# If agent uses standards
grep -i "standard\|pattern" agent.md

# Then verify uses Skill
grep "Skill:" agent.md
grep "tools:.*Skill" agent.md

Pattern 3: Categorize References

In ## References section:
✅ https://external-url.com (allowed)
✅ Skill: cui-other-skill (allowed)
✅ standards/internal.md (allowed)
❌ ../../../../standards/external.adoc (prohibited)

Quality Verification

All marketplace components must pass:

• Skills are self-contained (no external refs)
• Agents use Skills (not direct refs)
• Only allowed reference patterns used
• Bundle architecture follows design principles
• All standards content internalized

References

• Claude Code Plugin System: https://docs.claude.com/en/docs/claude-code/plugins
• Architecture rules: standards/architecture-rules.md
• Reference patterns: standards/reference-patterns.md
• Self-containment validation: standards/self-containment-validation.md
• Skill usage patterns: standards/skill-usage-patterns.md
• Scoring criteria: standards/scoring-criteria.md