skill-architect

Designs and refactors skill structures using SOLID principles and progressive disclosure patterns.

1|Updated Aug 6, 2026
One-click install
npx skills add https://github.com/YoLaub/JohnAI --skill skill-architect-yolaub
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: skill-architect
Source: https://github.com/YoLaub/JohnAI/tree/main/.claude/skills/skill-architect
Command: npx skills add https://github.com/YoLaub/JohnAI --skill skill-architect-yolaub

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Skills often grow into bloated, poorly structured SKILL.md files that mix stable methodology with accumulating knowledge, trigger unreliably, and accumulate dead references. This Skill provides a proven method to design new skills or refactor existing ones with clean separation of concerns. ## Core Features & Use Cases - Skill Creation (Phases 1-4): Frame a single user intent, choose an architecture pattern (Template Method, Facade, Pipeline, Strategy), write the frontmatter description as a public interface, and review with a lint checklist. - Skill Refactoring (Phase 0): Diagnose mixed responsibilities, growth-inducing instructions, and dead references in an existing skill, then restructure content verbatim with zero information loss. - SOLID Transposed to Skills: Apply single-responsibility by change velocity, progressive disclosure (thin SKILL.md facade plus on-demand references), and append-only knowledge files with dated sections. - Use Case: Your SKILL.md has grown to 300 lines mixing workflow and accumulated pitfalls. Run the refactor path to split knowledge into dated reference files while keeping the core workflow under 70 lines. ## Quick Start Ask the AI to refactor this skill because the SKILL.md is too large and mixes workflow with accumulated knowledge.

Frequently Asked Questions about skill-architect

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I refactor a SKILL.md that is too large?▼

Run the Phase 0 diagnostic: list the directory contents, identify blocks with different change velocities, find instructions that force the file to grow, and hunt dead references. Then move accumulated knowledge verbatim into dated reference files while keeping the stable workflow in SKILL.md under roughly 70 lines.

How do I choose between Template Method, Facade, Pipeline, and Strategy patterns for a skill?▼

Ask whether the skill's phases are independent entry points or steps of one intent. Sequential steps of a single intent use Template Method; independent entry points use Facade with one file per phase; agent orchestration uses Pipeline; interchangeable variants use Strategy.

When should I split one skill into multiple skills?▼

Split only when the skill covers multiple unrelated user intents, since each skill boundary is a probabilistic routing decision. Prefer fragmenting into files first, because indirection between files costs nothing while indirection between skills risks failed triggering.

What is the difference between skill-architect and skill-optimizer?▼

skill-architect works on structure: responsibilities, file splitting, patterns, and future growth wiring. skill-optimizer iterates on the content of a SKILL.md through measured micro-edits. Use architect for organization, optimizer for wording.

Why does my skill fail to trigger reliably?▼

Unreliable triggering usually comes from a vague frontmatter description or overlapping triggers with a neighboring skill. The description must contain literal user phrasings and explicit disambiguation with adjacent skills, since it acts as the public routing interface.