skill-developer

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, keyword triggers, hook mechanisms (UserPromptSubmit), session tracking, and the 500-line rule.

Skill Developer

SKILL_SYSTEM_AUTHORITY::[ MISSION::enable_domain_specific_guidance_via_automatic_skill_injection, SCOPE::skill_creation+trigger_tuning+500_line_enforcement+progressive_disclosure, GOVERNANCE_HIERARCHY::[CLAUDE.md→Skills→skill-developer] ]

---

SKILL TYPES

GUARDRAIL_SKILL::[
  TYPE::"guardrail",
  PURPOSE::enforce_critical_best_practices→prevent_errors,
  AUTO_INJECT::true,
  SESSION_AWARE::true[inject_once_per_conversation],
  USE_WHEN::[runtime_errors, data_integrity, compatibility_critical],
  EXAMPLES::[database-verification, frontend-dev-guidelines]
]

DOMAIN_SKILL::[
  TYPE::"domain",
  PURPOSE::provide_comprehensive_guidance_for_specific_area,
  AUTO_INJECT::true,
  ADVISORY::not_mandatory,
  USE_WHEN::[complex_systems, best_practices, architectural_patterns],
  EXAMPLES::[python-best-practices, skill-developer, api-security]
]

---

THE 500-LINE RULE (CRITICAL)

ABSOLUTE_LIMITS::[
  TARGET::all_skills<500_lines,
  MAX_BREACH::5_files_can_exceed_500[across_entire_system],
  HARD_LIMIT::NO_file>600_lines[EVER],
  REASON::"Agents_process_linearly→long_files_waste_tokens"
]

ENFORCEMENT::[
  approaching_500→STOP_and_extract_to_resources/,
  >500_and_not_top5→refactor_immediately,
  approaching_600→MANDATORY_refactor_no_exceptions,
  STRATEGY::progressive_disclosure[main_SKILL.md→resources/deep_dives]
]

HOW_TO_STAY_UNDER_500::[
  1_move_examples→resources/subdirectory,
  2_extract_deep_dives→topic_specific_resource_files,
  3_use_summaries_main→detailed_content_resources,
  4_remove_redundancy_and_wordiness
]

---

CREATING NEW SKILLS (5-STEP PROCESS)

STEP_1_CREATE::[
  file::SKILL.md,
  content::[YAML_frontmatter, core_guidance, resource_references],
  location::.claude/skills/{skill-name}/SKILL.md
]

STEP_2_CONFIGURE::[
  file::skill-rules.json,
  add::[skill_name, triggers, type, autoInject_flag, keywords]
]

STEP_3_TEST::[
  tool::UserPromptSubmit_hook,
  verify::trigger_detection_with_3+_scenarios,
  adjust::keyword_patterns_based_on_results
]

STEP_4_REFINE::[
  review::effectiveness_in_real_scenarios,
  update::trigger_keywords_for_coverage,
  adjust::resource_references_for_clarity
]

STEP_5_FINALIZE::[
  ensure::<500_lines,
  verify::progressive_disclosure_working,
  confirm::no_TOCs_or_line_numbers[FORBIDDEN]
]

---

FORBIDDEN IN SKILLS ❌

NEVER::[
  table_of_contents→bloat_for_agents,
  line_number_references→stale_and_fragile,
  heading_navigation_links→agents_scan_natively,
  examples>300_lines_in_main→move_to_resources/,
  verbose_explanations→compress_to_OCTAVE,
  circular_references→skills_don't_reference_CLAUDE.md
]

INSTEAD::[
  clear_descriptive_headings→agents_scan_naturally,
  anchor_text_references→see_patterns-library.md,
  keep_<500_lines→navigation_unnecessary,
  progressive_disclosure→main+resources/deep_dives,
  OCTAVE_format→semantic_density
]

---

SESSION STATE & DEDUPLICATION

AUTOMATIC_TRACKING::[
  MECHANISM::[skills_injected_once_per_conversation, subsequent_detections_reuse_loaded],
  STATE_FILE::.claude/hooks/state/{conversation_id}-skills-suggested.json,
  MANUAL_LOADING::IF[autoInject:false]→Skill("skill-name")_tool
]

---

TESTING & VALIDATION

BEFORE_DOCUMENTATION::[
  test_with::3+_real_world_scenarios,
  verify::triggers_activate_correctly,
  confirm::content_provides_guidance,
  NEVER::document_untested_skills
]

---

SKILL HEALTH & MAINTENANCE

PRE_COMMIT_HOOK::[
  script::.claude/hooks/pre-commit/validate_skill_references.py,
  triggers::[changes_to_skills, internal_docs, src/files],
  validates::[file_links_exist, new_docs_referenced, pattern_coverage],
  behavior::[fail_on_broken_links, warn_on_missing_references]
]

MANUAL_CHECKLIST[/wrap_command]::[
  new_constants_utilities→Update_code_reuse_skill,
  new_docs→Add_links_to_resource_files,
  new_patterns→Update_promptTriggers_keywords,
  verify::skill-rules.json_sync_with_codebase
]

BEST_PRACTICES::[
  run_/wrap→end_of_sessions[check_skill_updates],
  trust_pre_commit_warnings→unreferenced_docs,
  keep_skill_rules.json_sync,
  update_descriptions→when_adding_triggers,
  test_after_updates→verify_triggers_work
]

---

GOVERNANCE HIERARCHY

CLAUDE.md::[
  content::global_context+high_level_architecture+universal_style,
  references::1_line_pointers_to_skills
]

SKILLS::[
  content::domain_specific_guidance+patterns+procedures,
  triggered_by::context_keywords,
  examples::[python-best-practices, api-security, skill-developer]
]

SKILL_DEVELOPER::[
  content::skill_system_mechanics+trigger_patterns+500_line_rule,
  role::explains_complete_hierarchy,
  maintained_by::skill_expert_agent
]

CIRCULAR_PREVENTION::[
  skills_DON'T_reference_CLAUDE.md,
  CLAUDE.md_references_skills_one_line,
  skill_developer_maintains_hierarchy
]

---

REFERENCE RESOURCES

For detailed information on specific topics (in resources/ directory):

• trigger-types.md - Complete keyword trigger guide
• skill-rules-reference.md - Full skill-rules.json schema
• hook-mechanisms.md - Deep dive into UserPromptSubmit flow
• patterns-library.md - Ready-to-use pattern collection
• two-tier-system.md - Complete architecture guide
• skill-creation-guide.md - Step-by-step creation

---

QUICK REFERENCE

CREATE_NEW_SKILL::[
  1_SKILL.md_with_frontmatter,
  2_add_to_skill-rules.json,
  3_test_triggers,
  4_refine_patterns,
  5_keep<500_lines
]

CRITICAL_RULES::[
  500_line_limit[max_5_files>500, none>600],
  progressive_disclosure[use_resource_files],
  FORBIDDEN::[TOCs, line_numbers, circular_refs],
  TEST::3+_scenarios_before_documenting
]