Skill Developer Guide

Skill Developer Guide

What Is This

The "Skill Developer Guide" is a comprehensive support skill for the Happycapy Skills platform, specifically tailored to assist developers in creating, configuring, and maintaining Claude Code skills. This guide skill, identified as skill-developer, is designed to provide actionable suggestions, reference best practices, and clarify the operational architecture for skills, based on Anthropic’s official guidance. It leverages an automated activation system that listens for relevant keywords and intent patterns, ensuring developers receive immediate, context-specific assistance during the skill development lifecycle.

The skill’s technical foundation includes a two-hook architecture, YAML frontmatter compliance, enforcement level configuration, and built-in patterns for progressive disclosure and the 500-line rule. It is particularly useful for managing skill triggers, understanding file structure, working with the hook system, and debugging or extending skill functionality.

Why Use It

Efficient and accurate skill development in the Happycapy Skills platform relies on adherence to best practices, robust automation, and clear configuration. The Skill Developer Guide provides several advantages:

• Contextual Guidance: Automatically suggests relevant skills and documentation snippets based on your development context, detected through keywords and intent.
• Standardization: Promotes Anthropic’s best practices, including strict YAML frontmatter rules and the 500-line code limit.
• Error Reduction: Offers real-time debugging tips and structural validation, reducing common mistakes in skill activation or trigger setup.
• Progressive Disclosure: Ensures that additional information is revealed as needed, preventing cognitive overload.
• Automation: Uses hooks to preemptively surface relevant information, streamlining the skill authoring and troubleshooting process.

How to Use It

The Skill Developer Guide is designed for seamless, mostly automatic integration into your workflow. Below are the core operational mechanisms and example configurations:

Skill Structure

Each skill must begin with a YAML frontmatter block, which clearly defines the skill’s name, description, triggers, and other metadata:

---
name: skill-developer
description: Create and manage Claude Code skills following Anthropic best practices.
category: design
enforcement: suggest
triggers:
  keywords: [skill, trigger, hook, progressive disclosure, 500-line rule]
  intents: [create skill, modify skill, debug skill, manage triggers]
hooks:
  - UserPromptSubmit
  - PreToolUse
---

Two-Hook Architecture

The system relies on two key hooks:

1. UserPromptSubmit Hook

   • Location: .claude/hooks/skill-activation-prompt.ts
   • Role: Activated before Claude processes the user's prompt. It scans the prompt for specific keywords or intent patterns and injects contextual reminders about relevant skills into the session context.
   • Example: If a user types "How do I add a new trigger pattern?", the hook suggests documentation or configuration snippets for skill triggers.

2. PreToolUse Hook

   • Location: .claude/hooks/skill-pretool.ts
   • Role: Fires immediately before any tool or skill is executed. It validates that all necessary preconditions are met, such as correct structure or compliance with the 500-line rule.

Managing Triggers and Enforcement

Triggers can be based on:

• Keywords: Direct matches in the user’s prompt
• Intent Patterns: Inferred actions or questions
• File Paths: Activation when editing specific files (e.g., skill-rules.json)
• Content Patterns: Regular expressions or content heuristics

Enforcement levels (block, suggest, warn) control how strictly the skill’s guidance is applied. For example:

enforcement: suggest

This will prompt suggestions without blocking the user.

Best Practices and Progressive Disclosure

• 500-Line Rule: Each skill's implementation should not exceed 500 lines of code, promoting maintainability and readability.
• Progressive Disclosure: Only provide additional information or options when users indicate need, typically through follow-up prompts or detected confusion.

Example:

Adding a New Trigger

To add a trigger to an existing skill, update the YAML frontmatter:

triggers:
  keywords: [new trigger, update trigger]
  intents: [add trigger, modify trigger]

The Skill Developer Guide will automatically detect this change and offer advice or checks.

When to Use It

The Skill Developer Guide is automatically activated when you:

• Discuss creating or adding new skills
• Modify skill triggers or enforcement rules
• Work with skill-rules.json
• Debug skill activation or hook issues
• Ask about best practices, YAML structure, or the 500-line rule
• Require guidance on progressive disclosure implementation

This ensures that both new and experienced developers are supported during all critical phases of skill management.

Important Notes

• Strict YAML Compliance: Always ensure that your skill’s frontmatter is correctly formatted for automatic detection.
• Session Tracking: The system maintains session context to provide cumulative guidance as your workflow progresses.
• Custom Hooks: If implementing custom hooks, reference official templates and follow the separation of concerns principle.
• Non-Intrusive Suggestions: By default, the guide only suggests-never blocks-unless explicitly configured otherwise.
• Documentation Source: Refer to the official GitHub repository for up-to-date examples and template files.

In summary, the Skill Developer Guide is an essential automation and reference utility for any developer building or maintaining skills on the Happycapy Skills platform. It ensures best practices, reduces errors, and streamlines the entire skill development process.