# Plugin Architecture

> Architecture principles, skill patterns, and design guidance for building goal-based Claude Code marketplace components

- Skill: `majiayu000/plugin-architecture` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/plugin-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/plugin-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/plugin-architecture

---


# Plugin Architecture Skill

**REFERENCE MODE**: This skill provides reference material. Load specific references on-demand based on current task. Do not load all references at once.

Pure reference skill providing architecture principles, skill patterns, and design guidance for building goal-based Claude Code marketplace components.

## What This Skill Provides

**Architecture Foundation**: Core principles for building marketplace components that follow Claude Skills best practices and goal-based organization.

**Skill Patterns**: 10 implementation patterns for building different types of skills (automation, analysis, validation, etc.).

**Design Guidance**: Workflow-focused skill design, thin orchestrator commands, and proper resource organization.

## Pattern Type

**Pattern 10: Reference Library** - Pure reference skill with no execution logic. Load references on-demand based on current task.

## When to Use This Skill

Activate when:
- **Creating new marketplace components** - Agents, commands, skills, or bundles
- **Refactoring existing components** - Migrating to goal-based architecture
- **Reviewing component design** - Ensuring architecture compliance
- **Learning marketplace architecture** - Understanding principles and patterns

## Core Concepts

### Goal-Based Organization

**Principle**: Organize by WHAT users want to accomplish (goals), not by WHAT component operates on (types).

**User Goals**:
- **CREATE** - Create new marketplace components
- **DIAGNOSE** - Find and understand issues
- **FIX** - Fix identified issues
- **MAINTAIN** - Keep marketplace healthy
- **LEARN** - Understand architecture and patterns

### Progressive Disclosure

**Principle**: Minimize initial context load, load details on-demand.

**Levels**:
1. **Frontmatter** - Minimal metadata (~3 lines)
2. **SKILL.md** - Full instructions (~400-800 lines)
3. **References** - Detailed content (thousands of lines, loaded when needed)

### Relative Path Pattern

**Principle**: All resource paths use relative paths from the skill directory for portability across installations.

**Examples**:
```
Read references/core-principles.md
bash scripts/analyzer.py
Load template: assets/template.html
```

When a skill is loaded, Claude knows its installation directory and resolves relative paths from there.

## Available References

Load references progressively based on current task. **Never load all references at once.**

### 1. Core Principles (NEW - Essential Foundation)
**File**: `references/core-principles.md`

**Load When**:
- Starting any marketplace component development
- Learning Claude Skills fundamentals
- Understanding relative path pattern
- Reviewing progressive disclosure strategy

**Contents**:
- Skills as prompt modifiers
- Relative path pattern for portability
- Progressive disclosure strategy
- Resource organization (scripts/, references/, assets/)
- Tool permissions scoping
- Imperative language guidelines
- Scripts for deterministic logic
- Anti-patterns to avoid

**Load Command**:
```
Read references/core-principles.md
```

### 2. Skill Patterns (NEW - Implementation Patterns)
**File**: `references/skill-patterns.md`

**Load When**:
- Designing a new skill
- Choosing implementation pattern
- Understanding skill composition
- Learning pattern combinations

**Contents**:
- Pattern 1: Script Automation
- Pattern 2: Read-Process-Write
- Pattern 3: Search-Analyze-Report
- Pattern 4: Command Chain Execution
- Pattern 5: Wizard-Style Workflow
- Pattern 6: Template-Based Generation
- Pattern 7: Iterative Refinement
- Pattern 8: Context Aggregation
- Pattern 9: Validation Pipeline
- Pattern 10: Reference Library
- Decision guide for choosing patterns
- Pattern combination strategies

**Load Command**:
```
Read references/skill-patterns.md
```

### 3. Goal-Based Organization (NEW - Architecture Paradigm)
**File**: `references/goal-based-organization.md`

**Load When**:
- Understanding goal-based vs component-centric
- Migrating from component-centric architecture
- Designing goal-based commands
- Learning context optimization strategies

**Contents**:
- Goal-centric vs component-centric comparison
- User goals: CREATE, DIAGNOSE, FIX, MAINTAIN, LEARN
- Benefits of goal-based structure
- Migration from component-centric
- Progressive disclosure in action
- Context reduction strategies

**Load Command**:
```
Read references/goal-based-organization.md
```

### 4. Architecture Rules (Core Requirements)
**File**: `references/architecture-rules.md`

**Load When**:
- Validating component compliance
- Understanding self-containment requirements
- Learning reference pattern rules
- Implementing progressive disclosure

**Contents**:
- Rule 1: Skills must be self-contained
- Rule 2: Components must use skills (not direct file access)
- Rule 3: Reference categorization (internal, external, skill)
- Rule 4: Progressive disclosure requirement
- Rule 5: Goal-based organization requirement
- relative path pattern requirements
- Validation criteria

**Load Command**:
```
Read references/architecture-rules.md
```

### 5. Skill Design (Workflow-Focused)
**File**: `references/skill-design.md`

**Load When**:
- Designing skill workflows
- Creating multi-workflow skills
- Understanding workflow parameters
- Learning skill composition patterns

**Contents**:
- Workflow-focused design principles
- Multi-workflow vs single-workflow skills
- Workflow parameter design
- Conditional workflow selection
- Workflow composition patterns
- Quality standards for workflows

**Load Command**:
```
Read references/skill-design.md
```

### 6. Command Design (Thin Orchestrators)
**File**: `references/command-design.md`

**Load When**:
- Creating new commands
- Designing parameter parsing
- Routing to skill workflows
- Learning user interaction patterns

**Contents**:
- Thin orchestrator pattern
- Parameter parsing strategies
- Routing to skill workflows
- Goal-based command structure
- User interaction patterns
- Command quality standards

**Load Command**:
```
Read references/command-design.md
```

### 7. Token Optimization (Context Management)
**File**: `references/token-optimization.md`

**Load When**:
- Optimizing context usage
- Designing batch processing
- Implementing large-scale workflows
- Reducing token consumption

**Contents**:
- Pre-loading shared content
- Batched processing strategies
- Streamlined output formats
- Context budgeting
- Progressive disclosure for token reduction
- Pattern 7 (Iterative Refinement) for large codebases

**Load Command**:
```
Read references/token-optimization.md
```

### 8. Reference Patterns (relative paths Usage)
**File**: `references/reference-patterns.md`

**Load When**:
- Understanding allowed reference types
- Implementing relative path pattern
- Validating reference compliance
- Testing portability

**Contents**:
- Pattern 1: relative paths/references/ for documentation
- Pattern 2: relative paths/scripts/ for automation
- Pattern 3: relative paths/assets/ for templates
- Pattern 4: External URLs (allowed)
- Pattern 5: Skill dependencies (Skill:)
- Portability testing guidance
- Prohibited patterns

**Load Command**:
```
Read references/reference-patterns.md
```

### 9. Frontmatter Standards (Component Metadata)
**File**: `references/frontmatter-standards.md`

**Load When**:
- Creating component YAML frontmatter
- Validating frontmatter fields
- Understanding required vs optional fields

**Contents**:
- Required frontmatter fields
- Optional frontmatter fields
- Field format specifications
- Validation rules
- Examples for agents, commands, skills

**Load Command**:
```
Read references/frontmatter-standards.md
```

### 10. Script Standards (Executable Automation)
**File**: `references/script-standards.md`

**Load When**:
- Documenting scripts in SKILL.md
- Understanding script quality requirements
- Common issues and fixes

**Contents**:
- Script location (`{skill-dir}/scripts/`)
- Documentation requirements in SKILL.md
- Script quality checklist
- Common issues and fixes

**Related Skill**:
For Python implementation patterns, testing standards, and output contracts:
```
Skill: pm-plugin-development:plugin-script-architecture
```

**Load Command**:
```
Read references/script-standards.md
```

### 11. Execution Directive (Skill Execution Patterns)
**File**: `references/execution-directive.md`

**Load When**:
- Creating execution skills (Pattern 1-9)
- Ensuring Claude executes rather than explains
- Adding MANDATORY/CRITICAL markers
- Designing command handoff patterns
- Distinguishing EXECUTE vs READ vs REFERENCE modes

**Contents**:
- Execution Mode directive standard
- MANDATORY/CRITICAL marker usage
- Execution vs Reference clarity patterns
- Workflow decision tree patterns
- Command handoff pattern
- Imperative language guidelines
- Code-first pattern
- Validation checklist pattern
- Anti-patterns to avoid

**Load Command**:
```
Read references/execution-directive.md
```

### 12. Minimal Wrapper Pattern (Context Isolation Strategy)
**File**: `references/minimal-wrapper-pattern.md`

**Load When**:
- Designing agents or commands as thin orchestrators
- Solving context handling challenges
- Understanding agent-to-skill delegation
- Migrating from fat agents (> 150 lines)
- Implementing context isolation strategy
- Learning line budget guidelines for wrappers

**Contents**:
- Problem: Context pollution with pure skill-based architecture
- Solution: Thin wrappers (< 150 lines) that delegate to skills
- Why agent→skill works but agent→agent doesn't
- Implementation patterns for commands and agents
- Line budget guidelines (150 line maximum)
- Skill invocation patterns (commands, agents, chained)
- Anti-patterns (fat wrappers, duplicate logic, agent-to-agent)
- Correct patterns (thin orchestration, single source of truth)
- Integration with goal-based organization
- Migration guide from fat agents to minimal wrappers
- Quality checklist for wrapper compliance
- Real-world before/after examples

**Load Command**:
```
Read references/minimal-wrapper-pattern.md
```

### 13. User-Facing Output (Display Standards)
**File**: `references/user-facing-output.md`

**Load When**:
- Designing skill/command output
- Filtering internal operations from user display
- Creating status messages and progress indicators
- Implementing phase transitions
- Reviewing output for anti-patterns

**Contents**:
- Core concept: Show status, not process
- Structured status output pattern
- Phase transition message format
- Configuration display pattern
- Progress tables pattern
- Issue detection output pattern
- Final metrics display pattern
- Anti-patterns: What NOT to display (step numbers, skill loading, tool execution, diffs)
- Output filtering rules (MUST/MUST NOT/MAY display)
- Output by component type (commands, skills, agents)
- Implementation checklist

**Load Command**:
```
Read references/user-facing-output.md
```

### 14. AskUserQuestion Patterns (User Interaction)
**File**: `references/askuserquestion-patterns.md`

**Load When**:
- Designing interactive workflows with user input
- Using AskUserQuestion tool in skills/commands
- Handling free-text input via "Other" option
- Avoiding common interaction anti-patterns

**Contents**:
- Tool characteristics and schema
- Pattern 1: Selection with free-text alternative
- Pattern 2: Confirmation with customization
- Pattern 3: Type selection
- Pattern 4: Multi-select features
- Anti-patterns (redundant options, follow-up questions, expecting customization)
- Best practices for question design
- Known limitations (fixed "Type something." label)
- Workarounds for UI constraints

**Load Command**:
```
Read references/askuserquestion-patterns.md
```

## Examples

### Example 1: Goal-Based Skill
**File**: `references/examples/goal-based-skill-example.md`

**Load When**:
- Learning goal-based skill structure
- Understanding workflow organization
- Seeing progressive disclosure in practice

**Shows**:
- plugin-diagnose skill structure
- 5 workflows for different diagnostic goals
- Progressive disclosure demonstration
- relative paths usage throughout
- Script contracts (JSON output)
- Reference loading patterns

**Load Command**:
```
Read references/examples/goal-based-skill-example.md
```

### Example 2: Thin Orchestrator Command
**File**: `references/examples/workflow-command-example.md`

**Load When**:
- Learning command design patterns
- Understanding parameter parsing
- Seeing skill invocation in practice

**Shows**:
- diagnose command structure
- Parameter parsing logic
- Scope determination
- Skill invocation with workflow selection
- User interaction patterns

**Load Command**:
```
Read references/examples/workflow-command-example.md
```

### Example 3: Pattern Usage
**File**: `references/examples/pattern-usage-examples.md`

**Load When**:
- Applying skill patterns to real scenarios
- Understanding pattern combinations
- Learning when to use which pattern

**Shows**:
- Each of 10 patterns applied to marketplace scenarios
- Pattern combinations (e.g., Pattern 5 + Pattern 6)
- When to use which pattern
- Anti-pattern examples

**Load Command**:
```
Read references/examples/pattern-usage-examples.md
```

## Usage Workflow

### Step 1: Identify Your Goal

Determine what you're trying to accomplish:
- **Creating component** → Load core-principles.md, skill-patterns.md
- **Understanding architecture** → Load goal-based-organization.md, architecture-rules.md
- **Designing skill** → Load skill-design.md, skill-patterns.md
- **Designing command** → Load command-design.md
- **Optimizing context** → Load token-optimization.md
- **Validating compliance** → Load architecture-rules.md, reference-patterns.md

### Step 2: Load Relevant References

**Never load all references** - Load only what's needed for current task.

**Example**:
```
# Creating a new skill
Read references/core-principles.md
Read references/skill-patterns.md
Read references/skill-design.md
```

### Step 3: Apply Principles

Follow the guidance in loaded references:
- Use relative paths for all resource paths
- Implement progressive disclosure
- Choose appropriate skill pattern
- Follow architecture rules
- Optimize token usage

### Step 4: Validate Compliance

Ensure component follows architecture requirements:
- Self-contained (no external file references)
- Uses relative path pattern
- Implements progressive disclosure
- Follows chosen skill pattern
- Meets quality standards

## Integration with Other Skills

### Plugin-Create Skill
When creating components, this skill provides:
- Architecture principles for templates
- Frontmatter standards
- Validation rules

### Plugin-Diagnose Skill
When analyzing components, this skill provides:
- Quality standards for validation
- Architecture rules for compliance checking
- Reference patterns for validation

### Plugin-Fix Skill
When fixing components, this skill provides:
- Architecture rules for fix guidance
- Reference patterns for corrections
- Compliance criteria

## Quick Reference Guide

### When to Load What

**Starting any work**:
```
Read references/core-principles.md
```

**Creating skill**:
```
Read references/skill-patterns.md
Read references/skill-design.md
```

**Creating command**:
```
Read references/command-design.md
```

**Understanding architecture**:
```
Read references/goal-based-organization.md
Read references/architecture-rules.md
```

**Optimizing performance**:
```
Read references/token-optimization.md
```

**Validating compliance**:
```
Read references/architecture-rules.md
Read references/reference-patterns.md
```

**Ensuring execution (not explanation)**:
```
Read references/execution-directive.md
```

**Creating scripts**:
```
Read references/script-standards.md
```

**Designing thin wrappers**:
```
Read references/minimal-wrapper-pattern.md
```

**Designing user output**:
```
Read references/user-facing-output.md
```

**Designing user interactions**:
```
Read references/askuserquestion-patterns.md
```

**Learning by example**:
```
Read references/examples/goal-based-skill-example.md
Read references/examples/workflow-command-example.md
```

## Key Principles Summary

### 1. Goal-Based Organization
Organize by user goals (CREATE, DIAGNOSE, FIX, MAINTAIN, LEARN), not component types.

### 2. Progressive Disclosure
Minimize upfront information, load details on-demand.

### 3. relative paths Pattern
Always use `relative paths` for resource paths - never hardcode paths.

### 4. Self-Containment
Skills contain all content within their directory structure.

### 5. Pattern-Driven Design
Choose from 10 patterns based on skill purpose and complexity.

### 6. Workflow-Focused
Skills provide workflows, not monolithic operations.

### 7. Thin Orchestrators
Commands parse parameters and route to skill workflows.

### 8. Token Optimization
Pre-load shared content, use batching, streamline output.

### 9. Quality Standards
Follow architecture rules, validate compliance.

### 10. Composition
Build complex capabilities from simple, focused skills.

## Quality Verification

Components using this skill should demonstrate:
- [ ] Self-contained (no external file references)
- [ ] relative path pattern used throughout
- [ ] Progressive disclosure implemented
- [ ] Appropriate skill pattern chosen
- [ ] Goal-based organization followed
- [ ] Architecture rules compliance
- [ ] Token optimization applied
- [ ] Quality standards met

## References

### Source Materials
- Claude Skills Deep Dive: https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/
- Claude Code Plugin Documentation: https://docs.claude.com/en/docs/claude-code/plugins

### Related Skills
- plan-marshall:ref-development-standards - Core development principles
- plan-marshall:ref-development-standards - Tool usage patterns
- pm-plugin-development:plugin-script-architecture - Python implementation, testing, output contracts

### Internal References (Load On-Demand)
All references are in `references/` directory:
- core-principles.md
- skill-patterns.md
- goal-based-organization.md
- architecture-rules.md
- skill-design.md
- command-design.md
- token-optimization.md
- reference-patterns.md
- frontmatter-standards.md
- script-standards.md
- execution-directive.md
- minimal-wrapper-pattern.md
- user-facing-output.md
- askuserquestion-patterns.md
- examples/goal-based-skill-example.md
- examples/workflow-command-example.md
- examples/pattern-usage-examples.md

---

## Non-Prompting Requirements

This skill is designed to run without user prompts. Required permissions:

**File Operations:**
- `Read(relative paths/references/**)` - Read reference documentation

**Ensuring Non-Prompting:**
- All file reads use `relative paths/references/` which resolves to skill's mounted path
- Pure reference skill with no writes or executions
- Only the Read tool is used (no prompting scenarios)

---

*This is a Pattern 10 (Reference Library) skill - pure documentation with no execution logic. All content is loaded progressively based on current needs.*