跳到主内容
智客 ZICQ

技能库 智客分类:Agent 工作流 skill-developer

Skill Developer

根据Anthropic的官方最佳做法,包括500行规则和渐进披露模式,以自动激活系统创建和管理克洛德法典技能的全面指南.

676 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

根据Anthropic的官方最佳做法,包括500行规则和渐进披露模式,以自动激活系统创建和管理克洛德法典技能的全面指南.

何时用

这个技能

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Skill Developer Guide、Purpose、When to Use This Skill、System Overview、Two-Hook Architecture、Configuration File。 其中含规范建议的小节:分步指令。

文件分析

文件分析:这是一份仅含 SKILL.md 的指令型技能,代理激活后整份正文进入上下文。

官方 description(原文)

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.

Skill Developer GuidePurposeWhen to Use This SkillSystem OverviewTwo-Hook ArchitectureConfiguration FileSkill Types1. Guardrail Skills2. Domain SkillsQuick Start: Creating a New SkillStep 1: Create Skill FileMy New Skill

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
skill-developer
description
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.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「skill-developer」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-890ac20ce6f6e4de-%E6%8A%80%E8%83%BD%E5%BC%80%E5%8F%91%E8%80%85.html
请存为 .cursor/skills/skill-developer/SKILL.md 或 .claude/skills/skill-developer/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/sickn33/agentic-awesome-skills' --list

npx skills add 'https://github.com/sickn33/agentic-awesome-skills' --skill 'skill-developer'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版

name: skill-developer description: "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." risk: critical source: community date_added: "2026-02-27"

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:

---
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)
  • ✅ Content: Under 500 lines - use reference files for details
  • ✅ Examples: Real code examples
  • ✅ Structure: Clear headings, lists, code blocks

Step 2: Add to skill-rules.json

See SKILL_RULES_REFERENCE.md for complete schema.

Basic Template:

{
  "my-new-skill": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "medium",
    "promptTriggers": {
      "keywords": ["keyword1", "keyword2"],
      "intentPatterns": ["(create|add).*?something"]
    }
  }
}

Step 3: Test Triggers

Test UserPromptSubmit:

echo '{"session_id":"test","prompt":"your test prompt"}' | \
  npx tsx .claude/hooks/skill-activation-prompt.ts

Test PreToolUse:

cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{"session_id":"test","tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
EOF

Step 4: 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 5: 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:

// @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:

export SKIP_SKILL_GUARDRAILS=true  # Disables ALL PreToolUse blocks

Skill-specific:

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

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

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

Deep dive into hook internals:

  • UserPromptSubmit flow (detailed)
  • PreToolUse flow (detailed)
  • Exit code behavior table (CRITICAL)
  • Session state management
  • Performance considerations

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

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

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 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:

# 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 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

Limitations

  • Use this skill only when the task clearly matches the scope described above.
  • Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
  • Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

相关技能

Agent 工作流

Skill Creator

创造有效技能指南。 当用户想创造出新的技能(或更新现有的技能),以专业知识,工作流程,或工具集成来扩展克洛德的能力时,应该使用这种技能.

Agent 工作流

Clawdhub

使用ClawdHub CLI搜索,安装,更新并发布从taladhub.com的代理技能. 需要获取苍蝇上的新技能时使用,将安装的技能同步到最新版本或特定版本,或者发布 npm-instainddhub CLI 的新/更新的技能文件夹.

Agent 工作流

Agent Team Orchestration

管弦乐团多代理团队,任务设定周期,交接协议,审查工作流程. 使用时间: (1)建立2+特派员队伍,具有不同专业,(2)确定任务路线和生命周期(收录框_ spec_建设_审查_完成),(3)在特派员之间制定交接协议,(4)建立审查和质量关口,(5)管理特派员之间的交流和文物共享.

Agent 工作流

Superpowers

Spec-first,TDD,子代理驱动的软件开发工作流程. 当:(1)构建任何新功能或应用——触发脑暴_计划_子代理执行回路,(2)调试出一个bug或测试失败——触发系统性的根起过程,(3)用户说"让我们构建","帮助我计划","我想添加X",或"这个被打破",(4)完成一个功…