| name | skill-architect |
| description | Build, validate, and improve Claude Code skills. Design-first workflow with YAML frontmatter validation, progressive disclosure, and quality assessment. Use when creating new skills, improving existing ones, auditing skill quality, or troubleshooting skill triggering issues.
|
| version | 1.0.0 |
| keywords | skill, meta, builder, validation, quality, architecture |
skill-architect
Build, validate, and improve Claude Code skills using a design-first methodology.
how to use
/skill-architect — apply skill architecture principles to the current conversation./skill-architect build <name> — create a new skill from scratch following the full build workflow./skill-architect review <path> — review an existing skill and produce a scored quality report./skill-architect validate <path> — run the validator and report structural/frontmatter/content issues.
when to apply
- Creating a new Claude Code skill from scratch.
- Improving or refactoring an existing skill.
- Auditing skill quality across a skill library.
- Troubleshooting why a skill is not triggering correctly.
- Reviewing a skill before publishing or sharing.
- Converting a one-off workflow into a reusable skill.
when NOT to apply
- General coding tasks — use
coding-workflow instead.
- "Improve my skills" meaning career or personal development.
- Prompt engineering for chat conversations (skills are file-based, not chat-based).
- Writing one-off documentation or READMEs.
- Configuring MCP servers (that is infrastructure, not skill authoring).
- Iterative skill improvement with eval benchmarks — use
skill-creator instead;
it provides subagent testing, programmatic grading, eval-viewer, and
description optimization with eval queries.
rule priorities
| Priority | Category | Impact |
|---|
| 1 | Design-first thinking | Critical |
| 2 | YAML frontmatter | Critical |
| 3 | Folder structure | Critical |
| 4 | Instruction quality | High |
| 5 | Progressive disclosure | High |
| 6 | Composability | Medium |
| 7 | Testing | Medium |
| 8 | Iteration | Low |
Full per-category rules: references/skill-system-patterns.md.
critical constraints
Design-first (priority 1)
- MUST define 3+ trigger prompts before writing.
- MUST identify the skill category (document/asset, workflow automation, MCP enhancement).
- MUST check existing skills for overlap.
- MUST define explicit scope boundaries — what the skill does NOT cover.
- NEVER start writing SKILL.md without completing the design phase.
YAML frontmatter (priority 2)
- MUST start with
--- on line 1.
- MUST include
name in kebab-case matching the folder name exactly.
- MUST include
description under 1024 characters with no angle brackets.
- MUST NOT use forbidden terms in
name: claude, anthropic, plugin, extension.
- The description's first sentence determines triggering.
- Use
> folded scalar for multi-line descriptions.
Full field spec: references/yaml-reference.md.
Folder structure (priority 3)
skill-name/
├── SKILL.md # Required
├── scripts/ # Optional — stdlib only
└── references/ # Optional — supplementary docs
- Folder name MUST be kebab-case and MUST match the
name field.
- MUST NOT have both
README.md and SKILL.md.
- Scripts MUST use Python stdlib only — no pip dependencies.
- Keep SKILL.md under 5000 words; spill into
references/.
core workflow
Build (creating a new skill)
- Design — define triggers, category, scope, and name.
- Structure — create folder layout.
- Content — write scripts → references → SKILL.md.
- Validate — run
scripts/validate_skill.py (13 checks must pass).
- Test — Tier 1 triggering, Tier 2 functional.
- Refine — register, iterate on real usage.
Full procedure with templates: references/architecture-workflow.md.
Review (auditing an existing skill)
- Read SKILL.md, references/, scripts/.
- Validate with
validate_skill.py --verbose.
- Score 8 dimensions (0-5 each, 40 max).
- Output validator results, scorecard, top 3 issues, fixes.
Full scoring rubric and review procedure: references/evaluation-and-validation.md.
skill categories
| Category | Description | Examples |
|---|
| Document/Asset | Static references, lookup tables, specs | api-design-patterns |
| Workflow Automation | Multi-step processes, checklists, pipelines | coding-workflow, git-workflows |
| MCP Enhancement | MCP server wrappers with domain rules | aster-trading |
Per-category patterns: references/skill-system-patterns.md.
validation gates
Structural validation — all 13 checks must pass before shipping:
python3 ~/.claude/skills/skill-architect/scripts/validate_skill.py <skill-path>
Testing tiers — full methodology in references/testing-guide.md:
| Tier | What | How |
|---|
| 0 | Structural validity | validate_skill.py |
| 1 | Triggering accuracy | 3+ positive / 3+ negative prompts |
| 2 | Functional correctness | Happy path + error path + boundary |
| 3 | Performance delta | With-skill vs without |
safety constraints
- Do not create misleading skills.
- Do not include malware, exploit code, credential harvesting, or data exfiltration patterns.
- Do not bundle secrets, credentials, tokens, private context, personal identifiers, or local user paths in skill files.
- Preserve existing
name and frontmatter identity when improving an installed skill unless the user explicitly asks for a rename.
- Treat bundled scripts as code: keep them scoped, inspectable, testable, and stdlib-only.
output expectations
When creating or modifying a skill, report:
- Skill folder and files created or changed.
- Trigger behavior (positive + negative scope).
- Safety constraints included.
- Validator results (which of 13 checks passed/failed).
- Tests performed and results.
- Known limitations and recommended next iteration.
minimal frontmatter example
---
name: example-skill
description: >
One-sentence trigger statement. Use when <specific user intent A> or
<specific user intent B>.
version: 1.0.0
keywords: domain, capability, target
---
Full templates and patterns: references/yaml-reference.md,
references/workflow-patterns.md.
Reference map
| Need | Read |
|---|
| Full build + review workflow with templates | references/architecture-workflow.md |
| 8 rule categories detailed, skill category patterns | references/skill-system-patterns.md |
| Testing tiers, scoring rubric, validator details | references/evaluation-and-validation.md |
| Anti-patterns and diagnostics | references/troubleshooting.md |
| End-to-end skill construction walkthroughs | references/examples.md |
| YAML frontmatter field specification | references/yaml-reference.md |
| 5 reusable workflow patterns | references/workflow-patterns.md |
| 3-tier testing methodology | references/testing-guide.md |
| Pre/during/post development checklists | references/checklist.md |
| Automated validator (13 checks) | scripts/validate_skill.py |
