home / skills / zpankz / mcp-skillset / component-architect

component-architect skill

safe

This skill validates and enforces official Claude Code component standards before creation, audits existing components, and orchestrates remediation across

npx playbooks add skill zpankz/mcp-skillset --skill component-architect

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

3.8 KB

---
name: component-architect
description: |
  Enforces official Claude Code component standards. Use when creating skills,
  agents, commands, or hooks. Validates existing components and offers remediation.
  Implements the "one skill = one specialized agent" architecture pattern.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch
model: sonnet
context: fork
agent: component-architect-agent
user-invocable: true
hooks:
  PreToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "$HOME/.claude/skills/component-architect/scripts/validate-component.sh"
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "$HOME/.claude/skills/component-architect/scripts/log-component.sh"
---

# Component Architect

## Core Responsibilities

1. **Pre-Creation Validation**: Check official docs before generating any component
2. **Existing Component Audit**: Scan ~/.claude for non-compliant components
3. **Remediation Orchestration**: Spawn subagents to fix non-compliant files
4. **Architecture Enforcement**: Apply "one skill = one specialized agent" pattern

## Official Frontmatter Reference

| Component | Required | Optional |
|-----------|----------|----------|
| SKILL.md | name, description | allowed-tools, model, context, agent, hooks, user-invocable |
| Agent .md | name, description | tools, disallowedTools, model, permissionMode, skills, hooks |
| Command .md | (none) | description, allowed-tools, model, argument-hint |
| plugin.json | name, description | author |
| hooks.json | hooks object | description |

## Validation Commands

### Validate All Components
```bash
/component-architect validate
```

### Validate Specific Type
```bash
/component-architect validate --type skills
/component-architect validate --type agents
/component-architect validate --type hooks
```

### Apply Architecture Pattern
```bash
/component-architect apply-pattern --skill skill-name
```

## Architecture Pattern: One Skill = One Agent

For every active skill:
1. Set `context: fork` in SKILL.md
2. Create designated agent with matching name pattern
3. Configure agent with:
   - Intelligent `model` selection based on task complexity
   - Appropriate `permissionMode` for the workflow
   - Complementary `skills` that enhance the primary skill
   - Scoped `hooks` for lifecycle management
   - Restricted `tools` appropriate to the domain

### Model Selection Matrix

| Complexity | Model | Indicators |
|------------|-------|------------|
| High | opus | Architecture, debugging, multi-domain reasoning |
| Medium | sonnet | Implementation, refactoring, moderate analysis |
| Low | haiku | Searches, simple transforms, quick lookups |
| Inherited | inherit | When parent context model is appropriate |

### Permission Mode Selection Matrix

| Scenario | Mode | Use When |
|----------|------|----------|
| Complex multi-step | plan | High complexity requiring human feedback before implementation |
| Edge case handling | acceptEdits | Potential edge cases need user confirmation on edits |
| Routine execution | bypassPermissions | Clear requirements, preplanned, or promise completion |
| Standard workflow | default | Normal permission checking with prompts |
| Deny risky ops | dontAsk | Auto-deny prompts (explicitly allowed tools still work) |

## Remediation Workflow

1. Scan component directories for non-compliant files
2. Generate remediation plan per file
3. Spawn parallel subagents for batch updates
4. Verify all changes post-remediation

## Integration References

- [scripts/validate-component.sh](scripts/validate-component.sh) - PreToolUse validation
- [scripts/log-component.sh](scripts/log-component.sh) - PostToolUse logging
- [scripts/audit-components.py](scripts/audit-components.py) - Full audit script
- [references/official-spec.md](references/official-spec.md) - Cached official docs

Overview

This skill enforces official Claude Code component standards and the one-skill-one-agent architecture. It validates new and existing components, generates remediation plans, and orchestrates automated fixes through parallel subagents. Use it to keep a codebase compliant and to standardize agent/skill structure.

How this skill works

The tool scans local component directories for frontmatter and manifest deviations, compares them against the cached official spec, and produces a per-file remediation plan. It can spawn specialized subagents to apply fixes in parallel, then re-verify changes. The skill also helps create and configure a dedicated agent for each active skill using a model and permission selection matrix.

When to use it

Before creating a new skill, agent, command, or hook to validate design decisions.
When auditing an existing ~/.claude or components directory for compliance gaps.
To automatically remediate non-compliant component files at scale.
When applying the one-skill = one-agent architecture to an existing skillset.
During CI or pre-deploy checks to prevent non-standard components from shipping.

Best practices

Always validate against the official spec cache before generating components.
Treat each skill as a single, specialized agent with scoped tools and hooks.
Choose models based on task complexity: high for architecture, low for simple transforms.
Set permissionMode according to workflow risk and human feedback needs.
Run a full audit after batch remediation to ensure no regressions remain.

Example use cases

Validate a new skill manifest and auto-generate a matching agent with correct model and permissions.
Scan and fix dozens of legacy components by spawning parallel subagents to update frontmatter and manifests.
Enforce tool restrictions and lifecycle hooks for a high-risk domain before deployment.
Apply the one-skill-one-agent pattern to a mono-repo, creating structured agents for each active feature.
Integrate validation into a CI pipeline to block non-compliant changes from merging.

FAQ

How does the skill choose a model for an agent?

It uses a complexity-based matrix: high complexity maps to the strongest model, medium to an implementation-focused model, and low to a lightweight model. Parent context can be inherited when appropriate.

Can remediation run in parallel?

Yes. The skill spawns parallel subagents to apply batch updates and then verifies all changes post-remediation.