zhongwei/gh-jnlei-claude-tools-plugins-skills-skill-developer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:28:15 +08:00
commit 13e0eb6ac7
11 changed files with 2504 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
skills/skill-developer/ADVANCED.md Normal file
View File

@@ -0,0 +1,197 @@
# Advanced Topics & Future Enhancements
Ideas and concepts for future improvements to the skill system.
---
## Dynamic Rule Updates
**Current State:** Requires Claude Code restart to pick up changes to skill-rules.json
**Future Enhancement:** Hot-reload configuration without restart
**Implementation Ideas:**
- Watch skill-rules.json for changes
- Reload on file modification
- Invalidate cached compiled regexes
- Notify user of reload
**Benefits:**
- Faster iteration during skill development
- No need to restart Claude Code
- Better developer experience
---
## Skill Dependencies
**Current State:** Skills are independent
**Future Enhancement:** Specify skill dependencies and load order
**Configuration Idea:**
```json
{
"my-advanced-skill": {
"dependsOn": ["prerequisite-skill", "base-skill"],
"type": "domain",
...
}
}
```
**Use Cases:**
- Advanced skill builds on base skill knowledge
- Ensure foundational skills loaded first
- Chain skills for complex workflows
**Benefits:**
- Better skill composition
- Clearer skill relationships
- Progressive disclosure
---
## Conditional Enforcement
**Current State:** Enforcement level is static
**Future Enhancement:** Enforce based on context or environment
**Configuration Idea:**
```json
{
"enforcement": {
"default": "suggest",
"when": {
"production": "block",
"development": "suggest",
"ci": "block"
}
}
}
```
**Use Cases:**
- Stricter enforcement in production
- Relaxed rules during development
- CI/CD pipeline requirements
**Benefits:**
- Environment-appropriate enforcement
- Flexible rule application
- Context-aware guardrails
---
## Skill Analytics
**Current State:** No usage tracking
**Future Enhancement:** Track skill usage patterns and effectiveness
**Metrics to Collect:**
- Skill trigger frequency
- False positive rate
- False negative rate
- Time to skill usage after suggestion
- User override rate (skip markers, env vars)
- Performance metrics (execution time)
**Dashbord Ideas:**
- Most/least used skills
- Skills with highest false positive rate
- Performance bottlenecks
- Skill effectiveness scores
**Benefits:**
- Data-driven skill improvement
- Identify problems early
- Optimize patterns based on real usage
---
## Skill Versioning
**Current State:** No version tracking
**Future Enhancement:** Version skills and track compatibility
**Configuration Idea:**
```json
{
"my-skill": {
"version": "2.1.0",
"minClaudeVersion": "1.5.0",
"changelog": "Added support for new workflow patterns",
...
}
}
```
**Benefits:**
- Track skill evolution
- Ensure compatibility
- Document changes
- Support migration paths
---
## Multi-Language Support
**Current State:** English only
**Future Enhancement:** Support multiple languages for skill content
**Implementation Ideas:**
- Language-specific SKILL.md variants
- Automatic language detection
- Fallback to English
**Use Cases:**
- International teams
- Localized documentation
- Multi-language projects
---
## Skill Testing Framework
**Current State:** Manual testing with npx tsx commands
**Future Enhancement:** Automated skill testing
**Features:**
- Test cases for trigger patterns
- Assertion framework
- CI/CD integration
- Coverage reports
**Example Test:**
```typescript
describe('database-verification', () => {
it('triggers on Prisma imports', () => {
const result = testSkill({
prompt: "add user tracking",
file: "services/user.ts",
content: "import { PrismaService } from './prisma'"
});
expect(result.triggered).toBe(true);
expect(result.skill).toBe('database-verification');
});
});
```
**Benefits:**
- Prevent regressions
- Validate patterns before deployment
- Confidence in changes
---
## Related Files
- [SKILL.md](SKILL.md) - Main skill guide
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Current debugging guide
- [HOOK_MECHANISMS.md](HOOK_MECHANISMS.md) - How hooks work today

306
skills/skill-developer/HOOK_MECHANISMS.md Normal file
View File

@@ -0,0 +1,306 @@
# Hook Mechanisms - Deep Dive
Technical deep dive into how the UserPromptSubmit and PreToolUse hooks work.
## Table of Contents
- [UserPromptSubmit Hook Flow](#userpromptsubmit-hook-flow)
- [PreToolUse Hook Flow](#pretooluse-hook-flow)
- [Exit Code Behavior (CRITICAL)](#exit-code-behavior-critical)
- [Session State Management](#session-state-management)
- [Performance Considerations](#performance-considerations)
---
## UserPromptSubmit Hook Flow
### Execution Sequence
```
User submits prompt
↓
.claude/settings.json registers hook
↓
skill-activation-prompt.sh executes
↓
npx tsx skill-activation-prompt.ts
↓
Hook reads stdin (JSON with prompt)
↓
Loads skill-rules.json
↓
Matches keywords + intent patterns
↓
Groups matches by priority (critical → high → medium → low)
↓
Outputs formatted message to stdout
↓
stdout becomes context for Claude (injected before prompt)
↓
Claude sees: [skill suggestion] + user's prompt
```
### Key Points
- **Exit code**: Always 0 (allow)
- **stdout**: → Claude's context (injected as system message)
- **Timing**: Runs BEFORE Claude processes prompt
- **Behavior**: Non-blocking, advisory only
- **Purpose**: Make Claude aware of relevant skills
### Input Format
```json
{
"session_id": "abc-123",
"transcript_path": "/path/to/transcript.json",
"cwd": "/root/git/your-project",
"permission_mode": "normal",
"hook_event_name": "UserPromptSubmit",
"prompt": "how does the layout system work?"
}
```
### Output Format (to stdout)
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 SKILL ACTIVATION CHECK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📚 RECOMMENDED SKILLS:
→ project-catalog-developer
ACTION: Use Skill tool BEFORE responding
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
Claude sees this output as additional context before processing the user's prompt.
---
## PreToolUse Hook Flow
### Execution Sequence
```
Claude calls Edit/Write tool
↓
.claude/settings.json registers hook (matcher: Edit|Write)
↓
skill-verification-guard.sh executes
↓
npx tsx skill-verification-guard.ts
↓
Hook reads stdin (JSON with tool_name, tool_input)
↓
Loads skill-rules.json
↓
Checks file path patterns (glob matching)
↓
Reads file for content patterns (if file exists)
↓
Checks session state (was skill already used?)
↓
Checks skip conditions (file markers, env vars)
↓
IF MATCHED AND NOT SKIPPED:
Update session state (mark skill as enforced)
Output block message to stderr
Exit with code 2 (BLOCK)
ELSE:
Exit with code 0 (ALLOW)
↓
IF BLOCKED:
stderr → Claude sees message
Edit/Write tool does NOT execute
Claude must use skill and retry
IF ALLOWED:
Tool executes normally
```
### Key Points
- **Exit code 2**: BLOCK (stderr → Claude)
- **Exit code 0**: ALLOW
- **Timing**: Runs BEFORE tool execution
- **Session tracking**: Prevents repeated blocks in same session
- **Fail open**: On errors, allows operation (don't break workflow)
- **Purpose**: Enforce critical guardrails
### Input Format
```json
{
"session_id": "abc-123",
"transcript_path": "/path/to/transcript.json",
"cwd": "/root/git/your-project",
"permission_mode": "normal",
"hook_event_name": "PreToolUse",
"tool_name": "Edit",
"tool_input": {
"file_path": "/root/git/your-project/form/src/services/user.ts",
"old_string": "...",
"new_string": "..."
}
}
```
### Output Format (to stderr when blocked)
```
⚠️ BLOCKED - Database Operation Detected
📋 REQUIRED ACTION:
1. Use Skill tool: 'database-verification'
2. Verify ALL table and column names against schema
3. Check database structure with DESCRIBE commands
4. Then retry this edit
Reason: Prevent column name errors in Prisma queries
File: form/src/services/user.ts
💡 TIP: Add '// @skip-validation' comment to skip future checks
```
Claude receives this message and understands it needs to use the skill before retrying the edit.
---
## Exit Code Behavior (CRITICAL)
### Exit Code Reference Table
| Exit Code | stdout | stderr | Tool Execution | Claude Sees |
|-----------|--------|--------|----------------|-------------|
| 0 (UserPromptSubmit) | → Context | → User only | N/A | stdout content |
| 0 (PreToolUse) | → User only | → User only | **Proceeds** | Nothing |
| 2 (PreToolUse) | → User only | → **CLAUDE** | **BLOCKED** | stderr content |
| Other | → User only | → User only | Blocked | Nothing |
### Why Exit Code 2 Matters
This is THE critical mechanism for enforcement:
1. **Only way** to send message to Claude from PreToolUse
2. stderr content is "fed back to Claude automatically"
3. Claude sees the block message and understands what to do
4. Tool execution is prevented
5. Critical for enforcement of guardrails
### Example Conversation Flow
```
User: "Add a new user service with Prisma"
Claude: "I'll create the user service..."
[Attempts to Edit form/src/services/user.ts]
PreToolUse Hook: [Exit code 2]
stderr: "⚠️ BLOCKED - Use database-verification"
Claude sees error, responds:
"I need to verify the database schema first."
[Uses Skill tool: database-verification]
[Verifies column names]
[Retries Edit - now allowed (session tracking)]
```
---
## Session State Management
### Purpose
Prevent repeated nagging in the same session - once Claude uses a skill, don't block again.
### State File Location
`.claude/hooks/state/skills-used-{session_id}.json`
### State File Structure
```json
{
"skills_used": [
"database-verification",
"error-tracking"
],
"files_verified": []
}
```
### How It Works
1. **First edit** of file with Prisma:
- Hook blocks with exit code 2
- Updates session state: adds "database-verification" to skills_used
- Claude sees message, uses skill
2. **Second edit** (same session):
- Hook checks session state
- Finds "database-verification" in skills_used
- Exits with code 0 (allow)
- No message to Claude
3. **Different session**:
- New session ID = new state file
- Hook blocks again
### Limitation
The hook cannot detect when the skill is *actually* invoked - it just blocks once per session per skill. This means:
- If Claude doesn't use the skill but makes a different edit, it won't block again
- Trust that Claude follows the instruction
- Future enhancement: detect actual Skill tool usage
---
## Performance Considerations
### Target Metrics
- **UserPromptSubmit**: < 100ms
- **PreToolUse**: < 200ms
### Performance Bottlenecks
1. **Loading skill-rules.json** (every execution)
- Future: Cache in memory
- Future: Watch for changes, reload only when needed
2. **Reading file content** (PreToolUse)
- Only when contentPatterns configured
- Only if file exists
- Can be slow for large files
3. **Glob matching** (PreToolUse)
- Regex compilation for each pattern
- Future: Compile once, cache
4. **Regex matching** (Both hooks)
- Intent patterns (UserPromptSubmit)
- Content patterns (PreToolUse)
- Future: Lazy compile, cache compiled regexes
### Optimization Strategies
**Reduce patterns:**
- Use more specific patterns (fewer to check)
- Combine similar patterns where possible
**File path patterns:**
- More specific = fewer files to check
- Example: `form/src/services/**` better than `form/**`
**Content patterns:**
- Only add when truly necessary
- Simpler regex = faster matching
---
**Related Files:**
- [SKILL.md](SKILL.md) - Main skill guide
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Debug hook issues
- [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) - Configuration reference

193
skills/skill-developer/HOW-SKILL-WORKS.md Normal file
View File

@@ -0,0 +1,193 @@
# How Skills work
Skills leverage Claude's VM environment to provide capabilities beyond what's possible with prompts alone. Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials, organized like an onboarding guide you'd create for a new team member.
This filesystem-based architecture enables **progressive disclosure**: Claude loads information in stages as needed, rather than consuming context upfront.
### Three types of Skill content, three levels of loading
Skills can contain three types of content, each loaded at different times:
### Level 1: Metadata (always loaded)
**Content type: Instructions**. The Skill's YAML frontmatter provides discovery information:
```yaml theme={null}
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
```
Claude loads this metadata at startup and includes it in the system prompt. This lightweight approach means you can install many Skills without context penalty; Claude only knows each Skill exists and when to use it.
### Level 2: Instructions (loaded when triggered)
**Content type: Instructions**. The main body of SKILL.md contains procedural knowledge: workflows, best practices, and guidance:
````markdown theme={null}
# PDF Processing
## Quick start
Use pdfplumber to extract text from PDFs:
```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
For advanced form filling, see [FORMS.md](FORMS.md).
````
When you request something that matches a Skill's description, Claude reads SKILL.md from the filesystem via bash. Only then does this content enter the context window.
### Level 3: Resources and code (loaded as needed)
**Content types: Instructions, code, and resources**. Skills can bundle additional materials:
```
pdf-skill/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed API reference)
└── scripts/
└── fill_form.py (utility script)
```
**Instructions**: Additional markdown files (FORMS.md, REFERENCE.md) containing specialized guidance and workflows
**Code**: Executable scripts (fill\_form.py, validate.py) that Claude runs via bash; scripts provide deterministic operations without consuming context
**Resources**: Reference materials like database schemas, API documentation, templates, or examples
Claude accesses these files only when referenced. The filesystem model means each content type has different strengths: instructions for flexible guidance, code for reliability, resources for factual lookup.
| Level | When Loaded | Token Cost | Content |
| ------------------------- | ----------------------- | ---------------------- | --------------------------------------------------------------------- |
| **Level 1: Metadata** | Always (at startup) | \~100 tokens per Skill | `name` and `description` from YAML frontmatter |
| **Level 2: Instructions** | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
| **Level 3+: Resources** | As needed | Effectively unlimited | Bundled files executed via bash without loading contents into context |
Progressive disclosure ensures only relevant content occupies the context window at any given time.
### The Skills architecture
Skills run in a code execution environment where Claude has filesystem access, bash commands, and code execution capabilities. Think of it like this: Skills exist as directories on a virtual machine, and Claude interacts with them using the same bash commands you'd use to navigate files on your computer.
<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-architecture.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=44c5eab950e209f613a5a47f712550dc" alt="Agent Skills Architecture - showing how Skills integrate with the agent's configuration and virtual machine" data-og-width="2048" width="2048" data-og-height="1153" height="1153" data-path="images/agent-skills-architecture.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-architecture.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=fc06568b957c9c3617ea341548799568 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-architecture.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=5569fe72706deda67658467053251837 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-architecture.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=83c04e9248de7082971d623f835c2184 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-architecture.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=d8e1900f8992d435088a565e098fd32a 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-architecture.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=b03b4a5df2a08f4be86889e6158975ee 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-architecture.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=b9cab267c168f6a480ba946b6558115c 2500w" />
**How Claude accesses Skill content:**
When a Skill is triggered, Claude uses bash to read SKILL.md from the filesystem, bringing its instructions into the context window. If those instructions reference other files (like FORMS.md or a database schema), Claude reads those files too using additional bash commands. When instructions mention executable scripts, Claude runs them via bash and receives only the output (the script code itself never enters context).
**What this architecture enables:**
**On-demand file access**: Claude reads only the files needed for each specific task. A Skill can include dozens of reference files, but if your task only needs the sales schema, Claude loads just that one file. The rest remain on the filesystem consuming zero tokens.
**Efficient script execution**: When Claude runs `validate_form.py`, the script's code never loads into the context window. Only the script's output (like "Validation passed" or specific error messages) consumes tokens. This makes scripts far more efficient than having Claude generate equivalent code on the fly.
**No practical limit on bundled content**: Because files don't consume context until accessed, Skills can include comprehensive API documentation, large datasets, extensive examples, or any reference materials you need. There's no context penalty for bundled content that isn't used.
This filesystem-based model is what makes progressive disclosure work. Claude navigates your Skill like you'd reference specific sections of an onboarding guide, accessing exactly what each task requires.
### Example: Loading a PDF processing skill
Here's how Claude loads and uses a PDF processing skill:
1. **Startup**: System prompt includes: `PDF Processing - Extract text and tables from PDF files, fill forms, merge documents`
2. **User request**: "Extract the text from this PDF and summarize it"
3. **Claude invokes**: `bash: read pdf-skill/SKILL.md` → Instructions loaded into context
4. **Claude determines**: Form filling is not needed, so FORMS.md is not read
5. **Claude executes**: Uses instructions from SKILL.md to complete the task
<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-context-window.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0127e014bfc3dd3c86567aad8609111b" alt="Skills loading into context window - showing the progressive loading of skill metadata and content" data-og-width="2048" width="2048" data-og-height="1154" height="1154" data-path="images/agent-skills-context-window.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-context-window.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=a17315d47b7c5a85b389026b70676e98 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-context-window.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=267349b063954588d4fae2650cb90cd8 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-context-window.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0864972aba7bcb10bad86caf82cb415f 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-context-window.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=631d661cbadcbdb62fd0935b91bd09f8 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-context-window.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=c1f80d0e37c517eb335db83615483ae0 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-context-window.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=4b6d0f1baf011ff9b49de501d8d83cc7 2500w" />
The diagram shows:
1. Default state with system prompt and skill metadata pre-loaded
2. Claude triggers the skill by reading SKILL.md via bash
3. Claude optionally reads additional bundled files like FORMS.md as needed
4. Claude proceeds with the task
This dynamic loading ensures only relevant skill content occupies the context window.
## Skill structure
Every Skill requires a `SKILL.md` file with YAML frontmatter:
```yaml theme={null}
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---
# Your Skill Name
## Instructions
[Clear, step-by-step guidance for Claude to follow]
## Examples
[Concrete examples of using this Skill]
```
**Required fields**: `name` and `description`
**Field requirements**:
`name`:
* Maximum 64 characters
* Must contain only lowercase letters, numbers, and hyphens
* Cannot contain XML tags
* Cannot contain reserved words: "anthropic", "claude"
`description`:
* Must be non-empty
* Maximum 1024 characters
* Cannot contain XML tags
The `description` should include both what the Skill does and when Claude should use it. For complete authoring guidance, see the [best practices guide](/en/docs/agents-and-tools/agent-skills/best-practices).
## Limitations and constraints
Understanding these limitations helps you plan your Skills deployment effectively.
### Cross-surface availability
**Custom Skills do not sync across surfaces**. Skills uploaded to one surface are not automatically available on others:
* Skills uploaded to Claude.ai must be separately uploaded to the API
* Skills uploaded via the API are not available on Claude.ai
* Claude Code Skills are filesystem-based and separate from both Claude.ai and API
You'll need to manage and upload Skills separately for each surface where you want to use them.
### Sharing scope
Skills have different sharing models depending on where you use them:
* **Claude.ai**: Individual user only; each team member must upload separately
* **Claude API**: Workspace-wide; all workspace members can access uploaded Skills
* **Claude Code**: Personal (`~/.claude/skills/`) or project-based (`.claude/skills/`); can also be shared via Claude Code Plugins
Claude.ai does not currently support centralized admin management or org-wide distribution of custom Skills.
### Runtime environment constraints
The exact runtime environment available to your skill depends on the product surface where you use it.
* **Claude.ai**:
* **Varying network access**: Depending on user/admin settings, Skills may have full, partial, or no network access. For more details, see the [Create and Edit Files](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude#h_6b7e833898) support article.
* **Claude API**:
* **No network access**: Skills cannot make external API calls or access the internet
* **No runtime package installation**: Only pre-installed packages are available. You cannot install new packages during execution.
* **Pre-configured dependencies only**: Check the [code execution tool documentation](/en/docs/agents-and-tools/tool-use/code-execution-tool) for the list of available packages
* **Claude Code**:
* **Full network access**: Skills have the same network access as any other program on the user's computer
* **Global package installation discouraged**: Skills should only install packages locally in order to avoid interfering with the user's computer
Plan your Skills to work within these constraints.

152
skills/skill-developer/PATTERNS_LIBRARY.md Normal file
View File

@@ -0,0 +1,152 @@
# Common Patterns Library
Ready-to-use regex and glob patterns for skill triggers.
---
## Intent Patterns (Regex)
### Feature/Endpoint Creation
```regex
(add|create|implement|build).*?(feature|endpoint|route|service|controller|api)
```
### Component Creation
```regex
(create|add|make|build).*?(component|UI|page|modal|dialog|form)
```
### Database Work
```regex
(add|create|modify|update).*?(user|table|column|field|schema|migration)
(database|prisma).*?(change|update|query)
```
### Error Handling
```regex
(fix|handle|catch|debug).*?(error|exception|bug)
(add|implement).*?(try|catch|error.*?handling)
```
### Explanation Requests
```regex
(how does|how do|explain|what is|describe|tell me about).*?
```
### Workflow Operations
```regex
(create|add|modify|update).*?(workflow|step|branch|condition)
(debug|troubleshoot|fix).*?workflow
```
### Testing
```regex
(write|create|add).*?(test|spec|unit.*?test)
```
---
## File Path Patterns (Glob)
### Frontend
```glob
packages/ui/src/**/*.tsx # All React components
packages/ui/src/**/*.ts # All TypeScript files
packages/ui/src/components/** # Only components directory
```
### API Service
```glob
packages/api/src/routes/*.ts #
email/src/**/*.ts # Email service
users/src/**/*.ts # Users service
projects/src/**/*.ts # Projects service
```
### Database
```glob
**/schema.prisma # Prisma schema (anywhere)
**/migrations/**/*.sql # Migration files
database/src/**/*.ts # Database scripts
```
### Workflows
```glob
form/src/workflow/**/*.ts # Workflow engine
form/src/workflow-definitions/**/*.json # Workflow definitions
```
### Test Exclusions
```glob
**/*.test.ts # TypeScript tests
**/*.test.tsx # React component tests
**/*.spec.ts # Spec files
```
---
## Content Patterns (Regex)
### Prisma/Database
```regex
import.*[Pp]risma # Prisma imports
PrismaService # PrismaService usage
prisma\. # prisma.something
\.findMany\( # Prisma query methods
\.create\(
\.update\(
\.delete\(
```
### Controllers/Routes
```regex
export class.*Controller # Controller classes
router\. # Express router
app\.(get|post|put|delete|patch) # Express app routes
```
### Error Handling
```regex
try\s*\{ # Try blocks
catch\s*\( # Catch blocks
throw new # Throw statements
```
### React/Components
```regex
export.*React\.FC # React functional components
export default function.* # Default function exports
useState|useEffect # React hooks
```
---
**Usage Example:**
```json
{
"my-skill": {
"promptTriggers": {
"intentPatterns": [
"(create|add|build).*?(component|UI|page)"
]
},
"fileTriggers": {
"pathPatterns": [
"frontend/src/**/*.tsx"
],
"contentPatterns": [
"export.*React\\.FC",
"useState|useEffect"
]
}
}
}
```
---
**Related Files:**
- [SKILL.md](SKILL.md) - Main skill guide
- [TRIGGER_TYPES.md](TRIGGER_TYPES.md) - Detailed trigger documentation
- [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) - Complete schema

435
skills/skill-developer/SKILL.md Normal file
View File

@@ -0,0 +1,435 @@
---
name: skill-developer
description: Create and manage Claude Code skills following Anthropic best practices. Use when creating new skills, modifying skill-rules.json, understanding trigger patterns, working with hooks, debugging skill activation, or implementing progressive disclosure. Covers skill structure, YAML frontmatter, trigger types (keywords, intent patterns, file paths, content patterns), enforcement levels (block, suggest, warn), hook mechanisms (UserPromptSubmit, PreToolUse), session tracking, and the 500-line rule.
---
# Skill Developer Guide
## Purpose
Comprehensive guide for creating and managing skills in Claude Code with auto-activation system, following Anthropic's official best practices including the 500-line rule and progressive disclosure pattern.
## When to Use This Skill
Automatically activates when you mention:
- Creating or adding skills
- Modifying skill triggers or rules
- Understanding how skill activation works
- Debugging skill activation issues
- Working with skill-rules.json
- Hook system mechanics
- Claude Code best practices
- Progressive disclosure
- YAML frontmatter
- 500-line rule
---
## System Overview
### Two-Hook Architecture
**1. UserPromptSubmit Hook** (Proactive Suggestions)
- **File**: `.claude/hooks/skill-activation-prompt.ts`
- **Trigger**: BEFORE Claude sees user's prompt
- **Purpose**: Suggest relevant skills based on keywords + intent patterns
- **Method**: Injects formatted reminder as context (stdout → Claude's input)
- **Use Cases**: Topic-based skills, implicit work detection
**2. Stop Hook - Error Handling Reminder** (Gentle Reminders)
- **File**: `.claude/hooks/error-handling-reminder.ts`
- **Trigger**: AFTER Claude finishes responding
- **Purpose**: Gentle reminder to self-assess error handling in code written
- **Method**: Analyzes edited files for risky patterns, displays reminder if needed
- **Use Cases**: Error handling awareness without blocking friction
**Philosophy Change (2025-10-27):** We moved away from blocking PreToolUse for Sentry/error handling. Instead, use gentle post-response reminders that don't block workflow but maintain code quality awareness.
### Configuration File
**Location**: `.claude/skills/skill-rules.json`
Defines:
- All skills and their trigger conditions
- Enforcement levels (block, suggest, warn)
- File path patterns (glob)
- Content detection patterns (regex)
- Skip conditions (session tracking, file markers, env vars)
---
## Skill Types
### 1. Guardrail Skills
**Purpose:** Enforce critical best practices that prevent errors
**Characteristics:**
- Type: `"guardrail"`
- Enforcement: `"block"`
- Priority: `"critical"` or `"high"`
- Block file edits until skill used
- Prevent common mistakes (column names, critical errors)
- Session-aware (don't repeat nag in same session)
**Examples:**
- `database-verification` - Verify table/column names before Prisma queries
- `frontend-dev-guidelines` - Enforce React/TypeScript patterns
**When to Use:**
- Mistakes that cause runtime errors
- Data integrity concerns
- Critical compatibility issues
### 2. Domain Skills
**Purpose:** Provide comprehensive guidance for specific areas
**Characteristics:**
- Type: `"domain"`
- Enforcement: `"suggest"`
- Priority: `"high"` or `"medium"`
- Advisory, not mandatory
- Topic or domain-specific
- Comprehensive documentation
**Examples:**
- `backend-dev-guidelines` - Node.js/Express/TypeScript patterns
- `frontend-dev-guidelines` - React/TypeScript best practices
- `error-tracking` - Sentry integration guidance
**When to Use:**
- Complex systems requiring deep knowledge
- Best practices documentation
- Architectural patterns
- How-to guides
---
## Quick Start: Creating a New Skill
### Step 1: Create Skill File
**Location:** `.claude/skills/{skill-name}/SKILL.md`
**Template:**
```markdown
---
name: my-new-skill
description: Brief description including keywords that trigger this skill. Mention topics, file types, and use cases. Be explicit about trigger terms.
---
# My New Skill
## Purpose
What this skill helps with
## When to Use
Specific scenarios and conditions
## Key Information
The actual guidance, documentation, patterns, examples
```
**Best Practices:**
- ✅ **Name**: Lowercase, hyphens, gerund form (verb + -ing) preferred
- ✅ **Description**: Include ALL trigger keywords/phrases (max 1024 chars)
- ✅ **Examples**: Real code examples
- ✅ **Structure**: Clear headings, lists, code blocks
### Step 2: Content refine
By leveraging [How skill works](./HOW-SKILL-WORKS.md) and skill contents loading orders, refine the skill structure to keep each file small but highly correlated to a specific field and reference in main `SKILL.md` to reduce context and token usage.
**Best Practices:**
- ✅ **Content**: Each markdown file content should be less than 500 lines and very focused on a specific purpose or task.
- ✅ **Reference**: Extra reference markdown files should be reference back to main `SKILL.md` to avoid untented ignorance.
- ✅ **SKILL.md**: `SKILL.md` should be short and focus on high level and common information and have references to other field-specific references documentations.
### Step 3: Add to skill-rules.json
See [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) for complete schema.
**Basic Template:**
```json
{
"my-new-skill": {
"type": "domain",
"enforcement": "suggest",
"priority": "medium",
"promptTriggers": {
"keywords": ["keyword1", "keyword2"],
"intentPatterns": ["(create|add).*?something"]
}
}
}
```
### Step 4: Test Triggers
**Test UserPromptSubmit:**
```bash
echo '{"session_id":"test","prompt":"your test prompt"}' | \
npx tsx .claude/hooks/skill-activation-prompt.ts
```
**Test PreToolUse:**
```bash
cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{"session_id":"test","tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
EOF
```
### Step 5: Refine Patterns
Based on testing:
- Add missing keywords
- Refine intent patterns to reduce false positives
- Adjust file path patterns
- Test content patterns against actual files
### Step 6: Follow Anthropic Best Practices
✅ Keep SKILL.md under 500 lines
✅ Use progressive disclosure with reference files
✅ Add table of contents to reference files > 100 lines
✅ Write detailed description with trigger keywords
✅ Test with 3+ real scenarios before documenting
✅ Iterate based on actual usage
---
## Enforcement Levels
### BLOCK (Critical Guardrails)
- Physically prevents Edit/Write tool execution
- Exit code 2 from hook, stderr → Claude
- Claude sees message and must use skill to proceed
- **Use For**: Critical mistakes, data integrity, security issues
**Example:** Database column name verification
### SUGGEST (Recommended)
- Reminder injected before Claude sees prompt
- Claude is aware of relevant skills
- Not enforced, just advisory
- **Use For**: Domain guidance, best practices, how-to guides
**Example:** Frontend development guidelines
### WARN (Optional)
- Low priority suggestions
- Advisory only, minimal enforcement
- **Use For**: Nice-to-have suggestions, informational reminders
**Rarely used** - most skills are either BLOCK or SUGGEST.
---
## Skip Conditions & User Control
### 1. Session Tracking
**Purpose:** Don't nag repeatedly in same session
**How it works:**
- First edit → Hook blocks, updates session state
- Second edit (same session) → Hook allows
- Different session → Blocks again
**State File:** `.claude/hooks/state/skills-used-{session_id}.json`
### 2. File Markers
**Purpose:** Permanent skip for verified files
**Marker:** `// @skip-validation`
**Usage:**
```typescript
// @skip-validation
import { PrismaService } from './prisma';
// This file has been manually verified
```
**NOTE:** Use sparingly - defeats the purpose if overused
### 3. Environment Variables
**Purpose:** Emergency disable, temporary override
**Global disable:**
```bash
export SKIP_SKILL_GUARDRAILS=true # Disables ALL PreToolUse blocks
```
**Skill-specific:**
```bash
export SKIP_DB_VERIFICATION=true
export SKIP_ERROR_REMINDER=true
```
---
## Testing Checklist
When creating a new skill, verify:
- [ ] Skill file created in `.claude/skills/{name}/SKILL.md`
- [ ] Proper frontmatter with name and description
- [ ] Entry added to `skill-rules.json`
- [ ] Keywords tested with real prompts
- [ ] Intent patterns tested with variations
- [ ] File path patterns tested with actual files
- [ ] Content patterns tested against file contents
- [ ] Block message is clear and actionable (if guardrail)
- [ ] Skip conditions configured appropriately
- [ ] Priority level matches importance
- [ ] No false positives in testing
- [ ] No false negatives in testing
- [ ] Performance is acceptable (<100ms or <200ms)
- [ ] JSON syntax validated: `jq . skill-rules.json`
- [ ] **SKILL.md under 500 lines** ⭐
- [ ] Reference files created if needed
- [ ] Table of contents added to files > 100 lines
---
## Reference Files
For detailed information on specific topics, see:
### [TRIGGER_TYPES.md](TRIGGER_TYPES.md)
Complete guide to all trigger types:
- Keyword triggers (explicit topic matching)
- Intent patterns (implicit action detection)
- File path triggers (glob patterns)
- Content patterns (regex in files)
- Best practices and examples for each
- Common pitfalls and testing strategies
### [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md)
Complete skill-rules.json schema:
- Full TypeScript interface definitions
- Field-by-field explanations
- Complete guardrail skill example
- Complete domain skill example
- Validation guide and common errors
### [HOOK_MECHANISMS.md](HOOK_MECHANISMS.md)
Deep dive into hook internals:
- UserPromptSubmit flow (detailed)
- PreToolUse flow (detailed)
- Exit code behavior table (CRITICAL)
- Session state management
- Performance considerations
### [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
Comprehensive debugging guide:
- Skill not triggering (UserPromptSubmit)
- PreToolUse not blocking
- False positives (too many triggers)
- Hook not executing at all
- Performance issues
### [PATTERNS_LIBRARY.md](PATTERNS_LIBRARY.md)
Ready-to-use pattern collection:
- Intent pattern library (regex)
- File path pattern library (glob)
- Content pattern library (regex)
- Organized by use case
- Copy-paste ready
### [ADVANCED.md](ADVANCED.md)
Future enhancements and ideas:
- Dynamic rule updates
- Skill dependencies
- Conditional enforcement
- Skill analytics
- Skill versioning
---
## Quick Reference Summary
### Create New Skill (5 Steps)
1. Create `.claude/skills/{name}/SKILL.md` with frontmatter
2. Add entry to `.claude/skills/skill-rules.json`
3. Test with `npx tsx` commands
4. Refine patterns based on testing
5. Keep SKILL.md under 500 lines
### Trigger Types
- **Keywords**: Explicit topic mentions
- **Intent**: Implicit action detection
- **File Paths**: Location-based activation
- **Content**: Technology-specific detection
See [TRIGGER_TYPES.md](TRIGGER_TYPES.md) for complete details.
### Enforcement
- **BLOCK**: Exit code 2, critical only
- **SUGGEST**: Inject context, most common
- **WARN**: Advisory, rarely used
### Skip Conditions
- **Session tracking**: Automatic (prevents repeated nags)
- **File markers**: `// @skip-validation` (permanent skip)
- **Env vars**: `SKIP_SKILL_GUARDRAILS` (emergency disable)
### Anthropic Best Practices
✅ **500-line rule**: Keep SKILL.md under 500 lines
✅ **Progressive disclosure**: Use reference files for details
✅ **Table of contents**: Add to reference files > 100 lines
✅ **One level deep**: Don't nest references deeply
✅ **Rich descriptions**: Include all trigger keywords (max 1024 chars)
✅ **Test first**: Build 3+ evaluations before extensive documentation
✅ **Gerund naming**: Prefer verb + -ing (e.g., "processing-pdfs")
### Troubleshoot
Test hooks manually:
```bash
# UserPromptSubmit
echo '{"prompt":"test"}' | npx tsx .claude/hooks/skill-activation-prompt.ts
# PreToolUse
cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{"tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
EOF
```
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for complete debugging guide.
---
## Related Files
**Configuration:**
- `.claude/skills/skill-rules.json` - Master configuration
- `.claude/hooks/state/` - Session tracking
- `.claude/settings.json` - Hook registration
**Hooks:**
- `.claude/hooks/skill-activation-prompt.ts` - UserPromptSubmit
- `.claude/hooks/error-handling-reminder.ts` - Stop event (gentle reminders)
**All Skills:**
- `.claude/skills/*/SKILL.md` - Skill content files
---
**Skill Status**: COMPLETE - Restructured following Anthropic best practices ✅
**Line Count**: < 500 (following 500-line rule) ✅
**Progressive Disclosure**: Reference files for detailed information ✅
**Next**: Create more skills, refine patterns based on usage

315
skills/skill-developer/SKILL_RULES_REFERENCE.md Normal file
View File

@@ -0,0 +1,315 @@
# skill-rules.json - Complete Reference
Complete schema and configuration reference for `.claude/skills/skill-rules.json`.
## Table of Contents
- [File Location](#file-location)
- [Complete TypeScript Schema](#complete-typescript-schema)
- [Field Guide](#field-guide)
- [Example: Guardrail Skill](#example-guardrail-skill)
- [Example: Domain Skill](#example-domain-skill)
- [Validation](#validation)
---
## File Location
**Path:** `.claude/skills/skill-rules.json`
This JSON file defines all skills and their trigger conditions for the auto-activation system.
---
## Complete TypeScript Schema
```typescript
interface SkillRules {
version: string;
skills: Record<string, SkillRule>;
}
interface SkillRule {
type: 'guardrail' | 'domain';
enforcement: 'block' | 'suggest' | 'warn';
priority: 'critical' | 'high' | 'medium' | 'low';
promptTriggers?: {
keywords?: string[];
intentPatterns?: string[]; // Regex strings
};
fileTriggers?: {
pathPatterns: string[]; // Glob patterns
pathExclusions?: string[]; // Glob patterns
contentPatterns?: string[]; // Regex strings
createOnly?: boolean; // Only trigger on file creation
};
blockMessage?: string; // For guardrails, {file_path} placeholder
skipConditions?: {
sessionSkillUsed?: boolean; // Skip if used in session
fileMarkers?: string[]; // e.g., ["@skip-validation"]
envOverride?: string; // e.g., "SKIP_DB_VERIFICATION"
};
}
```
---
## Field Guide
### Top Level
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `version` | string | Yes | Schema version (currently "1.0") |
| `skills` | object | Yes | Map of skill name → SkillRule |
### SkillRule Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | Yes | "guardrail" (enforced) or "domain" (advisory) |
| `enforcement` | string | Yes | "block" (PreToolUse), "suggest" (UserPromptSubmit), or "warn" |
| `priority` | string | Yes | "critical", "high", "medium", or "low" |
| `promptTriggers` | object | Optional | Triggers for UserPromptSubmit hook |
| `fileTriggers` | object | Optional | Triggers for PreToolUse hook |
| `blockMessage` | string | Optional* | Required if enforcement="block". Use `{file_path}` placeholder |
| `skipConditions` | object | Optional | Escape hatches and session tracking |
*Required for guardrails
### promptTriggers Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `keywords` | string[] | Optional | Exact substring matches (case-insensitive) |
| `intentPatterns` | string[] | Optional | Regex patterns for intent detection |
### fileTriggers Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pathPatterns` | string[] | Yes* | Glob patterns for file paths |
| `pathExclusions` | string[] | Optional | Glob patterns to exclude (e.g., test files) |
| `contentPatterns` | string[] | Optional | Regex patterns to match file content |
| `createOnly` | boolean | Optional | Only trigger when creating new files |
*Required if fileTriggers is present
### skipConditions Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sessionSkillUsed` | boolean | Optional | Skip if skill already used this session |
| `fileMarkers` | string[] | Optional | Skip if file contains comment marker |
| `envOverride` | string | Optional | Environment variable name to disable skill |
---
## Example: Guardrail Skill
Complete example of a blocking guardrail skill with all features:
```json
{
"database-verification": {
"type": "guardrail",
"enforcement": "block",
"priority": "critical",
"promptTriggers": {
"keywords": [
"prisma",
"database",
"table",
"column",
"schema",
"query",
"migration"
],
"intentPatterns": [
"(add|create|implement).*?(user|login|auth|tracking|feature)",
"(modify|update|change).*?(table|column|schema|field)",
"database.*?(change|update|modify|migration)"
]
},
"fileTriggers": {
"pathPatterns": [
"**/schema.prisma",
"**/migrations/**/*.sql",
"database/src/**/*.ts",
"form/src/**/*.ts",
"email/src/**/*.ts",
"users/src/**/*.ts",
"projects/src/**/*.ts",
"utilities/src/**/*.ts"
],
"pathExclusions": [
"**/*.test.ts",
"**/*.spec.ts"
],
"contentPatterns": [
"import.*[Pp]risma",
"PrismaService",
"prisma\\.",
"\\.findMany\\(",
"\\.findUnique\\(",
"\\.findFirst\\(",
"\\.create\\(",
"\\.createMany\\(",
"\\.update\\(",
"\\.updateMany\\(",
"\\.upsert\\(",
"\\.delete\\(",
"\\.deleteMany\\("
]
},
"blockMessage": "⚠️ BLOCKED - Database Operation Detected\n\n📋 REQUIRED ACTION:\n1. Use Skill tool: 'database-verification'\n2. Verify ALL table and column names against schema\n3. Check database structure with DESCRIBE commands\n4. Then retry this edit\n\nReason: Prevent column name errors in Prisma queries\nFile: {file_path}\n\n💡 TIP: Add '// @skip-validation' comment to skip future checks",
"skipConditions": {
"sessionSkillUsed": true,
"fileMarkers": [
"@skip-validation"
],
"envOverride": "SKIP_DB_VERIFICATION"
}
}
}
```
### Key Points for Guardrails
1. **type**: Must be "guardrail"
2. **enforcement**: Must be "block"
3. **priority**: Usually "critical" or "high"
4. **blockMessage**: Required, clear actionable steps
5. **skipConditions**: Session tracking prevents repeated nagging
6. **fileTriggers**: Usually has both path and content patterns
7. **contentPatterns**: Catch actual usage of technology
---
## Example: Domain Skill
Complete example of a suggestion-based domain skill:
```json
{
"project-catalog-developer": {
"type": "domain",
"enforcement": "suggest",
"priority": "high",
"promptTriggers": {
"keywords": [
"layout",
"layout system",
"grid",
"grid layout",
"toolbar",
"column",
"cell editor",
"cell renderer",
"submission",
"submissions",
"blog dashboard",
"datagrid",
"data grid",
"CustomToolbar",
"GridLayoutDialog",
"useGridLayout",
"auto-save",
"column order",
"column width",
"filter",
"sort"
],
"intentPatterns": [
"(how does|how do|explain|what is|describe).*?(layout|grid|toolbar|column|submission|catalog)",
"(add|create|modify|change).*?(toolbar|column|cell|editor|renderer)",
"blog dashboard.*?"
]
},
"fileTriggers": {
"pathPatterns": [
"frontend/src/features/submissions/**/*.tsx",
"frontend/src/features/submissions/**/*.ts"
],
"pathExclusions": [
"**/*.test.tsx",
"**/*.test.ts"
]
}
}
}
```
### Key Points for Domain Skills
1. **type**: Must be "domain"
2. **enforcement**: Usually "suggest"
3. **priority**: "high" or "medium"
4. **blockMessage**: Not needed (doesn't block)
5. **skipConditions**: Optional (less critical)
6. **promptTriggers**: Usually has extensive keywords
7. **fileTriggers**: May have only path patterns (content less important)
---
## Validation
### Check JSON Syntax
```bash
cat .claude/skills/skill-rules.json | jq .
```
If valid, jq will pretty-print the JSON. If invalid, it will show the error.
### Common JSON Errors
**Trailing comma:**
```json
{
"keywords": ["one", "two",] // ❌ Trailing comma
}
```
**Missing quotes:**
```json
{
type: "guardrail" // ❌ Missing quotes on key
}
```
**Single quotes (invalid JSON):**
```json
{
'type': 'guardrail' // ❌ Must use double quotes
}
```
### Validation Checklist
- [ ] JSON syntax valid (use `jq`)
- [ ] All skill names match SKILL.md filenames
- [ ] Guardrails have `blockMessage`
- [ ] Block messages use `{file_path}` placeholder
- [ ] Intent patterns are valid regex (test on regex101.com)
- [ ] File path patterns use correct glob syntax
- [ ] Content patterns escape special characters
- [ ] Priority matches enforcement level
- [ ] No duplicate skill names
---
**Related Files:**
- [SKILL.md](SKILL.md) - Main skill guide
- [TRIGGER_TYPES.md](TRIGGER_TYPES.md) - Complete trigger documentation
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Debugging configuration issues

305
skills/skill-developer/TRIGGER_TYPES.md Normal file
View File

@@ -0,0 +1,305 @@
# Trigger Types - Complete Guide
Complete reference for configuring skill triggers in Claude Code's skill auto-activation system.
## Table of Contents
- [Keyword Triggers (Explicit)](#keyword-triggers-explicit)
- [Intent Pattern Triggers (Implicit)](#intent-pattern-triggers-implicit)
- [File Path Triggers](#file-path-triggers)
- [Content Pattern Triggers](#content-pattern-triggers)
- [Best Practices Summary](#best-practices-summary)
---
## Keyword Triggers (Explicit)
### How It Works
Case-insensitive substring matching in user's prompt.
### Use For
Topic-based activation where user explicitly mentions the subject.
### Configuration
```json
"promptTriggers": {
"keywords": ["layout", "grid", "toolbar", "submission"]
}
```
### Example
- User prompt: "how does the **layout** system work?"
- Matches: "layout" keyword
- Activates: `project-catalog-developer`
### Best Practices
- Use specific, unambiguous terms
- Include common variations ("layout", "layout system", "grid layout")
- Avoid overly generic words ("system", "work", "create")
- Test with real prompts
---
## Intent Pattern Triggers (Implicit)
### How It Works
Regex pattern matching to detect user's intent even when they don't mention the topic explicitly.
### Use For
Action-based activation where user describes what they want to do rather than the specific topic.
### Configuration
```json
"promptTriggers": {
"intentPatterns": [
"(create|add|implement).*?(feature|endpoint)",
"(how does|explain).*?(layout|workflow)"
]
}
```
### Examples
**Database Work:**
- User prompt: "add user tracking feature"
- Matches: `(add).*?(feature)`
- Activates: `database-verification`, `error-tracking`
**Component Creation:**
- User prompt: "create a dashboard widget"
- Matches: `(create).*?(component)` (if component in pattern)
- Activates: `frontend-dev-guidelines`
### Best Practices
- Capture common action verbs: `(create|add|modify|build|implement)`
- Include domain-specific nouns: `(feature|endpoint|component|workflow)`
- Use non-greedy matching: `.*?` instead of `.*`
- Test patterns thoroughly with regex tester (https://regex101.com/)
- Don't make patterns too broad (causes false positives)
- Don't make patterns too specific (causes false negatives)
### Common Pattern Examples
```regex
# Database Work
(add|create|implement).*?(user|login|auth|feature)
# Explanations
(how does|explain|what is|describe).*?
# Frontend Work
(create|add|make|build).*?(component|UI|page|modal|dialog)
# Error Handling
(fix|handle|catch|debug).*?(error|exception|bug)
# Workflow Operations
(create|add|modify).*?(workflow|step|branch|condition)
```
---
## File Path Triggers
### How It Works
Glob pattern matching against the file path being edited.
### Use For
Domain/area-specific activation based on file location in the project.
### Configuration
```json
"fileTriggers": {
"pathPatterns": [
"frontend/src/**/*.tsx",
"form/src/**/*.ts"
],
"pathExclusions": [
"**/*.test.ts",
"**/*.spec.ts"
]
}
```
### Glob Pattern Syntax
- `**` = Any number of directories (including zero)
- `*` = Any characters within a directory name
- Examples:
- `frontend/src/**/*.tsx` = All .tsx files in frontend/src and subdirs
- `**/schema.prisma` = schema.prisma anywhere in project
- `form/src/**/*.ts` = All .ts files in form/src subdirs
### Example
- File being edited: `frontend/src/components/Dashboard.tsx`
- Matches: `frontend/src/**/*.tsx`
- Activates: `frontend-dev-guidelines`
### Best Practices
- Be specific to avoid false positives
- Use exclusions for test files: `**/*.test.ts`
- Consider subdirectory structure
- Test patterns with actual file paths
- Use narrower patterns when possible: `form/src/services/**` not `form/**`
### Common Path Patterns
```glob
# Frontend
frontend/src/**/*.tsx # All React components
frontend/src/**/*.ts # All TypeScript files
frontend/src/components/** # Only components directory
# Backend Services
form/src/**/*.ts # Form service
email/src/**/*.ts # Email service
users/src/**/*.ts # Users service
# Database
**/schema.prisma # Prisma schema (anywhere)
**/migrations/**/*.sql # Migration files
database/src/**/*.ts # Database scripts
# Workflows
form/src/workflow/**/*.ts # Workflow engine
form/src/workflow-definitions/**/*.json # Workflow definitions
# Test Exclusions
**/*.test.ts # TypeScript tests
**/*.test.tsx # React component tests
**/*.spec.ts # Spec files
```
---
## Content Pattern Triggers
### How It Works
Regex pattern matching against the file's actual content (what's inside the file).
### Use For
Technology-specific activation based on what the code imports or uses (Prisma, controllers, specific libraries).
### Configuration
```json
"fileTriggers": {
"contentPatterns": [
"import.*[Pp]risma",
"PrismaService",
"\\.findMany\\(",
"\\.create\\("
]
}
```
### Examples
**Prisma Detection:**
- File contains: `import { PrismaService } from '@project/database'`
- Matches: `import.*[Pp]risma`
- Activates: `database-verification`
**Controller Detection:**
- File contains: `export class UserController {`
- Matches: `export class.*Controller`
- Activates: `error-tracking`
### Best Practices
- Match imports: `import.*[Pp]risma` (case-insensitive with [Pp])
- Escape special regex chars: `\\.findMany\\(` not `.findMany(`
- Patterns use case-insensitive flag
- Test against real file content
- Make patterns specific enough to avoid false matches
### Common Content Patterns
```regex
# Prisma/Database
import.*[Pp]risma # Prisma imports
PrismaService # PrismaService usage
prisma\. # prisma.something
\.findMany\( # Prisma query methods
\.create\(
\.update\(
\.delete\(
# Controllers/Routes
export class.*Controller # Controller classes
router\. # Express router
app\.(get|post|put|delete|patch) # Express app routes
# Error Handling
try\s*\{ # Try blocks
catch\s*\( # Catch blocks
throw new # Throw statements
# React/Components
export.*React\.FC # React functional components
export default function.* # Default function exports
useState|useEffect # React hooks
```
---
## Best Practices Summary
### DO:
✅ Use specific, unambiguous keywords
✅ Test all patterns with real examples
✅ Include common variations
✅ Use non-greedy regex: `.*?`
✅ Escape special characters in content patterns
✅ Add exclusions for test files
✅ Make file path patterns narrow and specific
### DON'T:
❌ Use overly generic keywords ("system", "work")
❌ Make intent patterns too broad (false positives)
❌ Make patterns too specific (false negatives)
❌ Forget to test with regex tester (https://regex101.com/)
❌ Use greedy regex: `.*` instead of `.*?`
❌ Match too broadly in file paths
### Testing Your Triggers
**Test keyword/intent triggers:**
```bash
echo '{"session_id":"test","prompt":"your test prompt"}' | \
npx tsx .claude/hooks/skill-activation-prompt.ts
```
**Test file path/content triggers:**
```bash
cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{
"session_id": "test",
"tool_name": "Edit",
"tool_input": {"file_path": "/path/to/test/file.ts"}
}
EOF
```
---
**Related Files:**
- [SKILL.md](SKILL.md) - Main skill guide
- [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) - Complete skill-rules.json schema
- [PATTERNS_LIBRARY.md](PATTERNS_LIBRARY.md) - Ready-to-use pattern library

514
skills/skill-developer/TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,514 @@
# Troubleshooting - Skill Activation Issues
Complete debugging guide for skill activation problems.
## Table of Contents
- [Skill Not Triggering](#skill-not-triggering)
- [UserPromptSubmit Not Suggesting](#userpromptsubmit-not-suggesting)
- [PreToolUse Not Blocking](#pretooluse-not-blocking)
- [False Positives](#false-positives)
- [Hook Not Executing](#hook-not-executing)
- [Performance Issues](#performance-issues)
---
## Skill Not Triggering
### UserPromptSubmit Not Suggesting
**Symptoms:** Ask a question, but no skill suggestion appears in output.
**Common Causes:**
#### 1. Keywords Don't Match
**Check:**
- Look at `promptTriggers.keywords` in skill-rules.json
- Are the keywords actually in your prompt?
- Remember: case-insensitive substring matching
**Example:**
```json
"keywords": ["layout", "grid"]
```
- "how does the layout work?" → ✅ Matches "layout"
- "how does the grid system work?" → ✅ Matches "grid"
- "how do layouts work?" → ✅ Matches "layout"
- "how does it work?" → ❌ No match
**Fix:** Add more keyword variations to skill-rules.json
#### 2. Intent Patterns Too Specific
**Check:**
- Look at `promptTriggers.intentPatterns`
- Test regex at https://regex101.com/
- May need broader patterns
**Example:**
```json
"intentPatterns": [
"(create|add).*?(database.*?table)" // Too specific
]
```
- "create a database table" → ✅ Matches
- "add new table" → ❌ Doesn't match (missing "database")
**Fix:** Broaden the pattern:
```json
"intentPatterns": [
"(create|add).*?(table|database)" // Better
]
```
#### 3. Typo in Skill Name
**Check:**
- Skill name in SKILL.md frontmatter
- Skill name in skill-rules.json
- Must match exactly
**Example:**
```yaml
# SKILL.md
name: project-catalog-developer
```
```json
// skill-rules.json
"project-catalogue-developer": { // ❌ Typo: catalogue vs catalog
...
}
```
**Fix:** Make names match exactly
#### 4. JSON Syntax Error
**Check:**
```bash
cat .claude/skills/skill-rules.json | jq .
```
If invalid JSON, jq will show the error.
**Common errors:**
- Trailing commas
- Missing quotes
- Single quotes instead of double
- Unescaped characters in strings
**Fix:** Correct JSON syntax, validate with jq
#### Debug Command
Test the hook manually:
```bash
echo '{"session_id":"debug","prompt":"your test prompt here"}' | \
npx tsx .claude/hooks/skill-activation-prompt.ts
```
Expected: Your skill should appear in the output.
---
### PreToolUse Not Blocking
**Symptoms:** Edit a file that should trigger a guardrail, but no block occurs.
**Common Causes:**
#### 1. File Path Doesn't Match Patterns
**Check:**
- File path being edited
- `fileTriggers.pathPatterns` in skill-rules.json
- Glob pattern syntax
**Example:**
```json
"pathPatterns": [
"frontend/src/**/*.tsx"
]
```
- Editing: `frontend/src/components/Dashboard.tsx` → ✅ Matches
- Editing: `frontend/tests/Dashboard.test.tsx` → ✅ Matches (add exclusion!)
- Editing: `backend/src/app.ts` → ❌ Doesn't match
**Fix:** Adjust glob patterns or add the missing path
#### 2. Excluded by pathExclusions
**Check:**
- Are you editing a test file?
- Look at `fileTriggers.pathExclusions`
**Example:**
```json
"pathExclusions": [
"**/*.test.ts",
"**/*.spec.ts"
]
```
- Editing: `services/user.test.ts` → ❌ Excluded
- Editing: `services/user.ts` → ✅ Not excluded
**Fix:** If test exclusion too broad, narrow it or remove
#### 3. Content Pattern Not Found
**Check:**
- Does the file actually contain the pattern?
- Look at `fileTriggers.contentPatterns`
- Is the regex correct?
**Example:**
```json
"contentPatterns": [
"import.*[Pp]risma"
]
```
- File has: `import { PrismaService } from './prisma'` → ✅ Matches
- File has: `import { Database } from './db'` → ❌ Doesn't match
**Debug:**
```bash
# Check if pattern exists in file
grep -i "prisma" path/to/file.ts
```
**Fix:** Adjust content patterns or add missing imports
#### 4. Session Already Used Skill
**Check session state:**
```bash
ls .claude/hooks/state/
cat .claude/hooks/state/skills-used-{session-id}.json
```
**Example:**
```json
{
"skills_used": ["database-verification"],
"files_verified": []
}
```
If the skill is in `skills_used`, it won't block again in this session.
**Fix:** Delete the state file to reset:
```bash
rm .claude/hooks/state/skills-used-{session-id}.json
```
#### 5. File Marker Present
**Check file for skip marker:**
```bash
grep "@skip-validation" path/to/file.ts
```
If found, the file is permanently skipped.
**Fix:** Remove the marker if verification is needed again
#### 6. Environment Variable Override
**Check:**
```bash
echo $SKIP_DB_VERIFICATION
echo $SKIP_SKILL_GUARDRAILS
```
If set, the skill is disabled.
**Fix:** Unset the environment variable:
```bash
unset SKIP_DB_VERIFICATION
```
#### Debug Command
Test the hook manually:
```bash
cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts 2>&1
{
"session_id": "debug",
"tool_name": "Edit",
"tool_input": {"file_path": "/root/git/your-project/form/src/services/user.ts"}
}
EOF
echo "Exit code: $?"
```
Expected:
- Exit code 2 + stderr message if should block
- Exit code 0 + no output if should allow
---
## False Positives
**Symptoms:** Skill triggers when it shouldn't.
**Common Causes & Solutions:**
### 1. Keywords Too Generic
**Problem:**
```json
"keywords": ["user", "system", "create"] // Too broad
```
- Triggers on: "user manual", "file system", "create directory"
**Solution:** Make keywords more specific
```json
"keywords": [
"user authentication",
"user tracking",
"create feature"
]
```
### 2. Intent Patterns Too Broad
**Problem:**
```json
"intentPatterns": [
"(create)" // Matches everything with "create"
]
```
- Triggers on: "create file", "create folder", "create account"
**Solution:** Add context to patterns
```json
"intentPatterns": [
"(create|add).*?(database|table|feature)" // More specific
]
```
**Advanced:** Use negative lookaheads to exclude
```regex
(create)(?!.*test).*?(feature) // Don't match if "test" appears
```
### 3. File Paths Too Generic
**Problem:**
```json
"pathPatterns": [
"form/**" // Matches everything in form/
]
```
- Triggers on: test files, config files, everything
**Solution:** Use narrower patterns
```json
"pathPatterns": [
"form/src/services/**/*.ts", // Only service files
"form/src/controllers/**/*.ts"
]
```
### 4. Content Patterns Catching Unrelated Code
**Problem:**
```json
"contentPatterns": [
"Prisma" // Matches in comments, strings, etc.
]
```
- Triggers on: `// Don't use Prisma here`
- Triggers on: `const note = "Prisma is cool"`
**Solution:** Make patterns more specific
```json
"contentPatterns": [
"import.*[Pp]risma", // Only imports
"PrismaService\\.", // Only actual usage
"prisma\\.(findMany|create)" // Specific methods
]
```
### 5. Adjust Enforcement Level
**Last resort:** If false positives are frequent:
```json
{
"enforcement": "block" // Change to "suggest"
}
```
This makes it advisory instead of blocking.
---
## Hook Not Executing
**Symptoms:** Hook doesn't run at all - no suggestion, no block.
**Common Causes:**
### 1. Hook Not Registered
**Check `.claude/settings.json`:**
```bash
cat .claude/settings.json | jq '.hooks.UserPromptSubmit'
cat .claude/settings.json | jq '.hooks.PreToolUse'
```
Expected: Hook entries present
**Fix:** Add missing hook registration:
```json
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
}
]
}
]
}
}
```
### 2. Bash Wrapper Not Executable
**Check:**
```bash
ls -l .claude/hooks/*.sh
```
Expected: `-rwxr-xr-x` (executable)
**Fix:**
```bash
chmod +x .claude/hooks/*.sh
```
### 3. Incorrect Shebang
**Check:**
```bash
head -1 .claude/hooks/skill-activation-prompt.sh
```
Expected: `#!/bin/bash`
**Fix:** Add correct shebang to first line
### 4. npx/tsx Not Available
**Check:**
```bash
npx tsx --version
```
Expected: Version number
**Fix:** Install dependencies:
```bash
cd .claude/hooks
npm install
```
### 5. TypeScript Compilation Error
**Check:**
```bash
cd .claude/hooks
npx tsc --noEmit skill-activation-prompt.ts
```
Expected: No output (no errors)
**Fix:** Correct TypeScript syntax errors
---
## Performance Issues
**Symptoms:** Hooks are slow, noticeable delay before prompt/edit.
**Common Causes:**
### 1. Too Many Patterns
**Check:**
- Count patterns in skill-rules.json
- Each pattern = regex compilation + matching
**Solution:** Reduce patterns
- Combine similar patterns
- Remove redundant patterns
- Use more specific patterns (faster matching)
### 2. Complex Regex
**Problem:**
```regex
(create|add|modify|update|implement|build).*?(feature|endpoint|route|service|controller|component|UI|page)
```
- Long alternations = slow
**Solution:** Simplify
```regex
(create|add).*?(feature|endpoint) // Fewer alternatives
```
### 3. Too Many Files Checked
**Problem:**
```json
"pathPatterns": [
"**/*.ts" // Checks ALL TypeScript files
]
```
**Solution:** Be more specific
```json
"pathPatterns": [
"form/src/services/**/*.ts", // Only specific directory
"form/src/controllers/**/*.ts"
]
```
### 4. Large Files
Content pattern matching reads entire file - slow for large files.
**Solution:**
- Only use content patterns when necessary
- Consider file size limits (future enhancement)
### Measure Performance
```bash
# UserPromptSubmit
time echo '{"prompt":"test"}' | npx tsx .claude/hooks/skill-activation-prompt.ts
# PreToolUse
time cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{"tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
EOF
```
**Target metrics:**
- UserPromptSubmit: < 100ms
- PreToolUse: < 200ms
---
**Related Files:**
- [SKILL.md](SKILL.md) - Main skill guide
- [HOOK_MECHANISMS.md](HOOK_MECHANISMS.md) - How hooks work
- [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) - Configuration reference