[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-9b98ae91-ae05-4a11-8d39-da7ba3055900":3,"$fVP_9iZ7BCfH0waU_-txicnrP5kkjxftwx3d46MDVchc":42},{"id":4,"title":5,"description":6,"categoryId":7,"moduleId":8,"tags":9,"prompt":10,"icon":11,"source":12,"sourceUrl":13,"authorId":14,"authorName":15,"isPublic":16,"stars":17,"runs":18,"createdAt":19,"updatedAt":19,"module":20,"category":27,"packages":33},"9b98ae91-ae05-4a11-8d39-da7ba3055900","skill-developer","综合指南：在Claude Code中创建和管理技能，并使用自动激活系统，遵循Anthropic的官方最佳实践，包括500行规则和渐进式披露模式。","cat_coding_backend","mod_coding","sickn33,coding","---\nname: skill-developer\ndescription: \"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.\"\nrisk: unknown\nsource: community\ndate_added: \"2026-02-27\"\n---\n\n# Skill Developer Guide\n\n## Purpose\n\nComprehensive 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.\n\n## When to Use This Skill\n\nAutomatically activates when you mention:\n- Creating or adding skills\n- Modifying skill triggers or rules\n- Understanding how skill activation works\n- Debugging skill activation issues\n- Working with skill-rules.json\n- Hook system mechanics\n- Claude Code best practices\n- Progressive disclosure\n- YAML frontmatter\n- 500-line rule\n\n---\n\n## System Overview\n\n### Two-Hook Architecture\n\n**1. UserPromptSubmit Hook** (Proactive Suggestions)\n- **File**: `.claude\u002Fhooks\u002Fskill-activation-prompt.ts`\n- **Trigger**: BEFORE Claude sees user's prompt\n- **Purpose**: Suggest relevant skills based on keywords + intent patterns\n- **Method**: Injects formatted reminder as context (stdout → Claude's input)\n- **Use Cases**: Topic-based skills, implicit work detection\n\n**2. Stop Hook - Error Handling Reminder** (Gentle Reminders)\n- **File**: `.claude\u002Fhooks\u002Ferror-handling-reminder.ts`\n- **Trigger**: AFTER Claude finishes responding\n- **Purpose**: Gentle reminder to self-assess error handling in code written\n- **Method**: Analyzes edited files for risky patterns, displays reminder if needed\n- **Use Cases**: Error handling awareness without blocking friction\n\n**Philosophy Change (2025-10-27):** We moved away from blocking PreToolUse for Sentry\u002Ferror handling. Instead, use gentle post-response reminders that don't block workflow but maintain code quality awareness.\n\n### Configuration File\n\n**Location**: `.claude\u002Fskills\u002Fskill-rules.json`\n\nDefines:\n- All skills and their trigger conditions\n- Enforcement levels (block, suggest, warn)\n- File path patterns (glob)\n- Content detection patterns (regex)\n- Skip conditions (session tracking, file markers, env vars)\n\n---\n\n## Skill Types\n\n### 1. Guardrail Skills\n\n**Purpose:** Enforce critical best practices that prevent errors\n\n**Characteristics:**\n- Type: `\"guardrail\"`\n- Enforcement: `\"block\"`\n- Priority: `\"critical\"` or `\"high\"`\n- Block file edits until skill used\n- Prevent common mistakes (column names, critical errors)\n- Session-aware (don't repeat nag in same session)\n\n**Examples:**\n- `database-verification` - Verify table\u002Fcolumn names before Prisma queries\n- `frontend-dev-guidelines` - Enforce React\u002FTypeScript patterns\n\n**When to Use:**\n- Mistakes that cause runtime errors\n- Data integrity concerns\n- Critical compatibility issues\n\n### 2. Domain Skills\n\n**Purpose:** Provide comprehensive guidance for specific areas\n\n**Characteristics:**\n- Type: `\"domain\"`\n- Enforcement: `\"suggest\"`\n- Priority: `\"high\"` or `\"medium\"`\n- Advisory, not mandatory\n- Topic or domain-specific\n- Comprehensive documentation\n\n**Examples:**\n- `backend-dev-guidelines` - Node.js\u002FExpress\u002FTypeScript patterns\n- `frontend-dev-guidelines` - React\u002FTypeScript best practices\n- `error-tracking` - Sentry integration guidance\n\n**When to Use:**\n- Complex systems requiring deep knowledge\n- Best practices documentation\n- Architectural patterns\n- How-to guides\n\n---\n\n## Quick Start: Creating a New Skill\n\n### Step 1: Create Skill File\n\n**Location:** `.claude\u002Fskills\u002F{skill-name}\u002FSKILL.md`\n\n**Template:**\n```markdown\n---\nname: my-new-skill\ndescription: Brief description including keywords that trigger this skill. Mention topics, file types, and use cases. Be explicit about trigger terms.\n---\n\n# My New Skill\n\n## Purpose\nWhat this skill helps with\n\n## When to Use\nSpecific scenarios and conditions\n\n## Key Information\nThe actual guidance, documentation, patterns, examples\n```\n\n**Best Practices:**\n- ✅ **Name**: Lowercase, hyphens, gerund form (verb + -ing) preferred\n- ✅ **Description**: Include ALL trigger keywords\u002Fphrases (max 1024 chars)\n- ✅ **Content**: Under 500 lines - use reference files for details\n- ✅ **Examples**: Real code examples\n- ✅ **Structure**: Clear headings, lists, code blocks\n\n### Step 2: Add to skill-rules.json\n\nSee [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) for complete schema.\n\n**Basic Template:**\n```json\n{\n  \"my-new-skill\": {\n    \"type\": \"domain\",\n    \"enforcement\": \"suggest\",\n    \"priority\": \"medium\",\n    \"promptTriggers\": {\n      \"keywords\": [\"keyword1\", \"keyword2\"],\n      \"intentPatterns\": [\"(create|add).*?something\"]\n    }\n  }\n}\n```\n\n### Step 3: Test Triggers\n\n**Test UserPromptSubmit:**\n```bash\necho '{\"session_id\":\"test\",\"prompt\":\"your test prompt\"}' | \\\n  npx tsx .claude\u002Fhooks\u002Fskill-activation-prompt.ts\n```\n\n**Test PreToolUse:**\n```bash\ncat \u003C\u003C'EOF' | npx tsx .claude\u002Fhooks\u002Fskill-verification-guard.ts\n{\"session_id\":\"test\",\"tool_name\":\"Edit\",\"tool_input\":{\"file_path\":\"test.ts\"}}\nEOF\n```\n\n### Step 4: Refine Patterns\n\nBased on testing:\n- Add missing keywords\n- Refine intent patterns to reduce false positives\n- Adjust file path patterns\n- Test content patterns against actual files\n\n### Step 5: Follow Anthropic Best Practices\n\n✅ Keep SKILL.md under 500 lines\n✅ Use progressive disclosure with reference files\n✅ Add table of contents to reference files > 100 lines\n✅ Write detailed description with trigger keywords\n✅ Test with 3+ real scenarios before documenting\n✅ Iterate based on actual usage\n\n---\n\n## Enforcement Levels\n\n### BLOCK (Critical Guardrails)\n\n- Physically prevents Edit\u002FWrite tool execution\n- Exit code 2 from hook, stderr → Claude\n- Claude sees message and must use skill to proceed\n- **Use For**: Critical mistakes, data integrity, security issues\n\n**Example:** Database column name verification\n\n### SUGGEST (Recommended)\n\n- Reminder injected before Claude sees prompt\n- Claude is aware of relevant skills\n- Not enforced, just advisory\n- **Use For**: Domain guidance, best practices, how-to guides\n\n**Example:** Frontend development guidelines\n\n### WARN (Optional)\n\n- Low priority suggestions\n- Advisory only, minimal enforcement\n- **Use For**: Nice-to-have suggestions, informational reminders\n\n**Rarely used** - most skills are either BLOCK or SUGGEST.\n\n---\n\n## Skip Conditions & User Control\n\n### 1. Session Tracking\n\n**Purpose:** Don't nag repeatedly in same session\n\n**How it works:**\n- First edit → Hook blocks, updates session state\n- Second edit (same session) → Hook allows\n- Different session → Blocks again\n\n**State File:** `.claude\u002Fhooks\u002Fstate\u002Fskills-used-{session_id}.json`\n\n### 2. File Markers\n\n**Purpose:** Permanent skip for verified files\n\n**Marker:** `\u002F\u002F @skip-validation`\n\n**Usage:**\n```typescript\n\u002F\u002F @skip-validation\nimport { PrismaService } from '.\u002Fprisma';\n\u002F\u002F This file has been manually verified\n```\n\n**NOTE:** Use sparingly - defeats the purpose if overused\n\n### 3. Environment Variables\n\n**Purpose:** Emergency disable, temporary override\n\n**Global disable:**\n```bash\nexport SKIP_SKILL_GUARDRAILS=true  # Disables ALL PreToolUse blocks\n```\n\n**Skill-specific:**\n```bash\nexport SKIP_DB_VERIFICATION=true\nexport SKIP_ERROR_REMINDER=true\n```\n\n---\n\n## Testing Checklist\n\nWhen creating a new skill, verify:\n\n- [ ] Skill file created in `.claude\u002Fskills\u002F{name}\u002FSKILL.md`\n- [ ] Proper frontmatter with name and description\n- [ ] Entry added to `skill-rules.json`\n- [ ] Keywords tested with real prompts\n- [ ] Intent patterns tested with variations\n- [ ] File path patterns tested with actual files\n- [ ] Content patterns tested against file contents\n- [ ] Block message is clear and actionable (if guardrail)\n- [ ] Skip conditions configured appropriately\n- [ ] Priority level matches importance\n- [ ] No false positives in testing\n- [ ] No false negatives in testing\n- [ ] Performance is acceptable (\u003C100ms or \u003C200ms)\n- [ ] JSON syntax validated: `jq . skill-rules.json`\n- [ ] **SKILL.md under 500 lines** ⭐\n- [ ] Reference files created if needed\n- [ ] Table of contents added to files > 100 lines\n\n---\n\n## Reference Files\n\nFor detailed information on specific topics, see:\n\n### [TRIGGER_TYPES.md](TRIGGER_TYPES.md)\nComplete guide to all trigger types:\n- Keyword triggers (explicit topic matching)\n- Intent patterns (implicit action detection)\n- File path triggers (glob patterns)\n- Content patterns (regex in files)\n- Best practices and examples for each\n- Common pitfalls and testing strategies\n\n### [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md)\nComplete skill-rules.json schema:\n- Full TypeScript interface definitions\n- Field-by-field explanations\n- Complete guardrail skill example\n- Complete domain skill example\n- Validation guide and common errors\n\n### [HOOK_MECHANISMS.md](HOOK_MECHANISMS.md)\nDeep dive into hook internals:\n- UserPromptSubmit flow (detailed)\n- PreToolUse flow (detailed)\n- Exit code behavior table (CRITICAL)\n- Session state management\n- Performance considerations\n\n### [TROUBLESHOOTING.md](TROUBLESHOOTING.md)\nComprehensive debugging guide:\n- Skill not triggering (UserPromptSubmit)\n- PreToolUse not blocking\n- False positives (too many triggers)\n- Hook not executing at all\n- Performance issues\n\n### [PATTERNS_LIBRARY.md](PATTERNS_LIBRARY.md)\nReady-to-use pattern collection:\n- Intent pattern library (regex)\n- File path pattern library (glob)\n- Content pattern library (regex)\n- Organized by use case\n- Copy-paste ready\n\n### [ADVANCED.md](ADVANCED.md)\nFuture enhancements and ideas:\n- Dynamic rule updates\n- Skill dependencies\n- Conditional enforcement\n- Skill analytics\n- Skill versioning\n\n---\n\n## Quick Reference Summary\n\n### Create New Skill (5 Steps)\n\n1. Create `.claude\u002Fskills\u002F{name}\u002FSKILL.md` with frontmatter\n2. Add entry to `.claude\u002Fskills\u002Fskill-rules.json`\n3. Test with `npx tsx` commands\n4. Refine patterns based on testing\n5. Keep SKILL.md under 500 lines\n\n### Trigger Types\n\n- **Keywords**: Explicit topic mentions\n- **Intent**: Implicit action detection\n- **File Paths**: Location-based activation\n- **Content**: Technology-specific detection\n\nSee [TRIGGER_TYPES.md](TRIGGER_TYPES.md) for complete details.\n\n### Enforcement\n\n- **BLOCK**: Exit code 2, critical only\n- **SUGGEST**: Inject context, most common\n- **WARN**: Advisory, rarely used\n\n### Skip Conditions\n\n- **Session tracking**: Automatic (prevents repeated nags)\n- **File markers**: `\u002F\u002F @skip-validation` (permanent skip)\n- **Env vars**: `SKIP_SKILL_GUARDRAILS` (emergency disable)\n\n### Anthropic Best Practices\n\n✅ **500-line rule**: Keep SKILL.md under 500 lines\n✅ **Progressive disclosure**: Use reference files for details\n✅ **Table of contents**: Add to reference files > 100 lines\n✅ **One level deep**: Don't nest references deeply\n✅ **Rich descriptions**: Include all trigger keywords (max 1024 chars)\n✅ **Test first**: Build 3+ evaluations before extensive documentation\n✅ **Gerund naming**: Prefer verb + -ing (e.g., \"processing-pdfs\")\n\n### Troubleshoot\n\nTest hooks manually:\n```bash\n# UserPromptSubmit\necho '{\"prompt\":\"test\"}' | npx tsx .claude\u002Fhooks\u002Fskill-activation-prompt.ts\n\n# PreToolUse\ncat \u003C\u003C'EOF' | npx tsx .claude\u002Fhooks\u002Fskill-verification-guard.ts\n{\"tool_name\":\"Edit\",\"tool_input\":{\"file_path\":\"test.ts\"}}\nEOF\n```\n\nSee [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for complete debugging guide.\n\n---\n\n## Related Files\n\n**Configuration:**\n- `.claude\u002Fskills\u002Fskill-rules.json` - Master configuration\n- `.claude\u002Fhooks\u002Fstate\u002F` - Session tracking\n- `.claude\u002Fsettings.json` - Hook registration\n\n**Hooks:**\n- `.claude\u002Fhooks\u002Fskill-activation-prompt.ts` - UserPromptSubmit\n- `.claude\u002Fhooks\u002Ferror-handling-reminder.ts` - Stop event (gentle reminders)\n\n**All Skills:**\n- `.claude\u002Fskills\u002F*\u002FSKILL.md` - Skill content files\n\n---\n\n**Skill Status**: COMPLETE - Restructured following Anthropic best practices ✅\n**Line Count**: \u003C 500 (following 500-line rule) ✅\n**Progressive Disclosure**: Reference files for detailed information ✅\n\n**Next**: Create more skills, refine patterns based on usage\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.\n","","imported","https:\u002F\u002Fgithub.com\u002Fsickn33\u002Fantigravity-awesome-skills","user_system_seed","SkillOPIC",true,107,898,"2026-05-16 13:40:44",{"id":8,"name":21,"slug":22,"icon":23,"description":24,"sort":25,"createdAt":26},"编程开发","coding","mdi-code-braces","代码生成、调试、审查，提升开发效率",2,"2026-05-16 12:53:40",{"id":7,"name":28,"slug":29,"icon":30,"description":31,"moduleId":8,"sort":25,"skillCount":32,"createdAt":26},"后端开发","backend","mdi-server","API、数据库、服务端架构",296,[34],{"id":35,"skillId":4,"version":36,"fileName":37,"fileSize":38,"filePath":39,"fileHash":40,"manifest":41,"createdAt":19},"b1b4091e-dc07-4c4c-a75a-57bd48ab691d","1.0.0","skill-developer.zip",20810,"uploads\u002Fskills\u002F9b98ae91-ae05-4a11-8d39-da7ba3055900\u002Fskill-developer.zip","46bff4edbdf0e13a2aee982b6b65a642a48ef0b0865c6a6ff0e92bd59590506d","[{\"path\":\"ADVANCED.md\",\"isDirectory\":false,\"size\":3979},{\"path\":\"HOOK_MECHANISMS.md\",\"isDirectory\":false,\"size\":7920},{\"path\":\"PATTERNS_LIBRARY.md\",\"isDirectory\":false,\"size\":3347},{\"path\":\"SKILL.md\",\"isDirectory\":false,\"size\":12365},{\"path\":\"SKILL_RULES_REFERENCE.md\",\"isDirectory\":false,\"size\":8692},{\"path\":\"TRIGGER_TYPES.md\",\"isDirectory\":false,\"size\":7709},{\"path\":\"TROUBLESHOOTING.md\",\"isDirectory\":false,\"size\":10080}]",{"code":43,"message":44,"data":45},200,"success",{"items":46,"stats":47,"page":50},[],{"averageRating":48,"totalRatings":48,"ratingCounts":49},0,[48,48,48,48,48],{"limit":51,"offset":48,"hasMore":52,"nextOffset":51,"ratedOnly":16},15,false]