skill writer

Usage

Describe what the skill should do, and this will generate a complete skill YAML file.

Instructions

When the user describes a skill they want to create:

1. Understand the Purpose: Clarify what the skill should analyze or check
2. Design the Prompt: Write a clear, specific system prompt for the Claude agent
3. Configure Tools: Select appropriate tool restrictions based on the skill’s needs
4. Define Output Expectations: Ensure the skill will produce valid SkillReport output

Skill Definition Schema

name: skill-name  # kebab-case, unique identifier
description: Short description of what the skill does

prompt: |
  Detailed instructions for the Claude agent.
  - What to analyze
  - What to look for
  - How to categorize findings
  - Severity guidelines

tools:
  allowed:  # Tools the skill CAN use
    - Read
    - Grep
    - Glob
    - WebFetch
    - WebSearch
  denied:   # Tools the skill CANNOT use
    - Write
    - Edit
    - Bash

Available Tools

Severity Guidelines

Instruct skills to use these severity levels:

• critical: Actively exploitable, high impact, immediate action required
• high: Exploitable with moderate effort, should fix before merge
• medium: Potential issue, needs review and consideration
• low: Minor concern, fix when convenient
• info: Observation, no action required

Output Schema

All skills must output a SkillReport:

{
  skill: string;      // Skill name
  summary: string;    // Brief overview of findings
  findings: [{
    id: string;       // Unique finding ID
    severity: 'critical' | 'high' | 'medium' | 'low' | 'info';
    title: string;    // Short title
    description: string; // Detailed explanation
    location?: {      // Where the issue is
      path: string;
      startLine: number;
      endLine?: number;
    };
    suggestedFix?: {  // Optional fix
      description: string;
      diff: string;   // Unified diff format
    };
  }];
  metadata?: Record<string, unknown>;
}

Example Output

When asked to create a skill, output the complete YAML:

name: test-coverage
description: Check if new code has adequate test coverage

prompt: |
  You are a test coverage analyst. Review the PR changes and check:

  1. New functions/methods have corresponding tests
  2. Edge cases are covered
  3. Error paths are tested
  4. Test names are descriptive

  Focus on:
  - New code additions (not modifications to existing tests)
  - Public APIs and exported functions
  - Complex logic branches

  Severity levels:
  - high: Public API with no tests
  - medium: Complex logic without edge case tests
  - low: Missing negative/error case tests
  - info: Suggestions for additional coverage

tools:
  allowed:
    - Read
    - Grep
    - Glob
  denied:
    - Write
    - Edit
    - Bash
    - WebFetch
    - WebSearch

Process

1. Ask clarifying questions if the skill purpose is unclear
2. Generate the skill YAML
3. Explain any design decisions
4. Offer to refine based on feedback