From ceaf6dbf3c93380974cc87808d857f657e9c4b2c Mon Sep 17 00:00:00 2001 From: Lorenz Hilpert Date: Wed, 19 Nov 2025 14:06:54 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20add=20mandatory=20skill?= =?UTF-8?q?=20usage=20guidelines=20for=20reliable=20proactive=20invocation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add critical section to CLAUDE.md covering: - Skill vs Agent vs Direct Tools decision matrix - Mandatory skill invocation rules with trigger conditions - Proactive usage framework with right/wrong examples - Skill chaining and coordination patterns - Context management for skills (load β†’ apply β†’ unload) - Failure handling for skill conflicts - Decision tree for tool selection --- CLAUDE.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 0ee32b27c..08eddebaf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,6 +22,115 @@ This file contains meta-instructions for how Claude should work with the ISA-Fro - Use bullet points and structured formatting for clarity - Only provide detailed explanations when complexity requires it +## πŸ”΄ CRITICAL: Mandatory Skill Usage + +**Skills are project-specific tools that MUST be used proactively for their domains.** + +### Skill vs Agent vs Direct Tools + +| Tool Type | Purpose | When to Use | Context Management | +|-----------|---------|-------------|-------------------| +| **Skills** | Domain-specific workflows (Angular, testing, architecture) | Writing/reviewing code in skill's domain | Load skill β†’ follow instructions β†’ unload | +| **Agents** | Research & knowledge gathering | Finding docs, searching code, analysis | Use agent β†’ extract findings β†’ discard output | +| **Direct Tools** | Single file operations | Reading specific known files | Use tool β†’ process β†’ done | + +### Mandatory Skill Invocation Rules + +**ALWAYS invoke skills when:** + +| Trigger | Required Skill | Why | +|---------|---------------|-----| +| Writing Angular templates | `angular-template` | Modern syntax (@if, @for, @defer) | +| Writing HTML with interactivity | `html-template` | E2E attributes (data-what, data-which) + ARIA | +| Applying Tailwind classes | `tailwind` | Design system consistency | +| Writing Angular code | `logging` | Mandatory logging via @isa/core/logging | +| Creating new library | `library-scaffolder` | Proper Nx setup + Vitest config | +| Regenerating API clients | `swagger-sync-manager` | All 10 clients + validation | +| Migrating to standalone | `standalone-component-migrator` | Complete migration workflow | +| Migrating tests to Vitest | `test-migration-specialist` | Jestβ†’Vitest conversion | +| Fixing `any` types | `type-safety-engineer` | Add Zod schemas + type guards | +| Checking architecture | `architecture-enforcer` | Import boundaries + circular deps | +| Resolving circular deps | `circular-dependency-resolver` | Graph analysis + fix strategies | +| API changes analysis | `api-change-analyzer` | Breaking change detection | +| Git workflow | `git-workflow` | Branch naming + conventional commits | + +### Proactive Skill Usage Framework + +**"Proactive" means:** +1. **Detect task domain automatically** - Don't wait for user to say "use skill X" +2. **Invoke before starting work** - Load skill first, then execute +3. **Apply throughout task** - Keep skill active for entire domain work +4. **Validate with skill** - Use skill to review your own output + +**Example - WRONG:** +``` +User: "Add a new Angular component with a form" +Assistant: [Writes component without skills] +User: "Did you use the Angular template skill?" +Assistant: "Oh sorry, let me reload with the skill" +``` + +**Example - RIGHT:** +``` +User: "Add a new Angular component with a form" +Assistant: [Invokes angular-template skill] +Assistant: [Invokes html-template skill] +Assistant: [Invokes logging skill] +Assistant: [Writes component following all skill guidelines] +``` + +### Skill Chaining & Coordination + +**Multiple skills often apply to same task:** + +| Task | Required Skill Chain | Order | +|------|---------------------|-------| +| New Angular component | `angular-template` β†’ `html-template` β†’ `logging` β†’ `tailwind` | Template syntax β†’ HTML attributes β†’ Logging β†’ Styling | +| New library | `library-scaffolder` β†’ `architecture-enforcer` | Scaffold β†’ Validate structure | +| API sync | `api-change-analyzer` β†’ `swagger-sync-manager` | Analyze changes β†’ Regenerate clients | +| Component migration | `standalone-component-migrator` β†’ `test-migration-specialist` | Migrate component β†’ Migrate tests | + +**Skill chaining rules:** +- Load ALL applicable skills at task start (via Skill tool) +- Skills don't nest - they provide instructions you follow +- Skills stay active for entire task scope +- Validate final output against ALL loaded skills + +### Skill Context Management + +**Skills expand instructions into your context:** + +- βœ… **DO**: Load skill β†’ internalize rules β†’ follow throughout task +- ❌ **DON'T**: Re-read skill instructions multiple times +- ❌ **DON'T**: Quote skill instructions back to user +- ❌ **DON'T**: Keep skill "open" after task completion + +**After task completion:** +1. Verify work against skill requirements +2. Summarize what was applied (1 sentence) +3. Move on (skill context auto-clears next task) + +### Skill Failure Handling + +| Issue | Action | +|-------|--------| +| Skill not found | Verify skill name; ask user to check available skills | +| Skill conflicts with user request | Note conflict; ask user for preference | +| Multiple skills give conflicting rules | Follow most specific skill for current file type | +| Skill instructions unclear | Use best judgment; document assumption in code comment | + +### Skills vs Agents - Decision Tree + +``` +Is this a code writing/reviewing task? +β”œβ”€ YES β†’ Check if skill exists for domain +β”‚ β”œβ”€ Skill exists β†’ Use Skill +β”‚ └─ No skill β†’ Use direct tools +└─ NO β†’ Is this research/finding information? + β”œβ”€ YES β†’ Use Agent (docs-researcher/Explore) + └─ NO β†’ Use direct tools (Read/Edit/Bash) +``` + ## Researching and Investigating the Codebase **πŸ”΄ MANDATORY: You MUST use subagents for research. Direct file reading/searching.**