cuioss 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:
- Frontmatter - Minimal metadata (~3 lines)
- SKILL.md - Full instructions (~400-800 lines)
- 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:general-development-rules - Core development principles
- plan-marshall:diagnostic-patterns - 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.