GapMultiplier   int             `json:"gap_multiplier" jsonschema:"Gap threshold multiplier (0 = use default 2)"`
	MinDetections   int             `json:"min_detections" jsonschema:"Min detections per cluster (-1 = use default 0)"`

	gapThreshold := float64(CLUSTER_GAP_MULTIPLIER) * clipDuration

	gapMultiplier := CLUSTER_GAP_MULTIPLIER
	if input.GapMultiplier > 0 {
		gapMultiplier = input.GapMultiplier
	}
	minDetections := MIN_DETECTIONS_PER_CLUSTER
	if input.MinDetections >= 0 {
		minDetections = input.MinDetections
	}
	gapThreshold := float64(gapMultiplier) * clipDuration

			if len(cluster) <= MIN_DETECTIONS_PER_CLUSTER {

			if len(cluster) <= minDetections {

    if ! "$PROJECT_DIR/skraak" calls from-preds --csv "$csv_path" --dot-data=false > "$actual_json" 2>"$stderr_output"; then

    if ! "$PROJECT_DIR/skraak" calls from-preds --csv "$csv_path" --dot-data=false --gap-multiplier 3 --min-detections 1 > "$actual_json" 2>"$stderr_output"; then

        # Find calls in expected but not in actual
        local missing extra
        missing=$(jq -n --slurpfile exp "$expected_json" --slurpfile act "$actual_json" \
            '([$exp[0].calls | .[] | {file, start_time, end_time, ebird_code, segments}] | sort) - ([$act[0].calls | .[] | {file, start_time, end_time, ebird_code, segments}] | sort) | length')
        extra=$(jq -n --slurpfile exp "$expected_json" --slurpfile act "$actual_json" \
            '([$act[0].calls | .[] | {file, start_time, end_time, ebird_code, segments}] | sort) - ([$exp[0].calls | .[] | {file, start_time, end_time, ebird_code, segments}] | sort) | length')

        # Find calls in expected but not in actual (skip for large arrays to avoid hang)
        if [ "$actual_count" -lt 10000 ] && [ "$expected_count" -lt 10000 ]; then
            local missing extra
            missing=$(jq -n --slurpfile exp "$expected_json" --slurpfile act "$actual_json" \
                '([$exp[0].calls | .[] | {file, start_time, end_time, ebird_code, segments}] | sort) - ([$act[0].calls | .[] | {file, start_time, end_time, ebird_code, segments}] | sort) | length')
            extra=$(jq -n --slurpfile exp "$expected_json" --slurpfile act "$actual_json" \
                '([$act[0].calls | .[] | {file, start_time, end_time, ebird_code, segments}] | sort) - ([$exp[0].calls | .[] | {file, start_time, end_time, ebird_code, segments}] | sort) | length')

        echo "    Missing from actual: $missing calls"
        echo "    Extra in actual: $extra calls"

            echo "    Missing from actual: $missing calls"
            echo "    Extra in actual: $extra calls"
        else
            echo "    (skipping detailed diff — arrays too large)"
        fi

	gapMultiplier := fs.Int("gap-multiplier", 0, "Gap threshold multiplier (default: 2, e.g. 3 for kiwi)")
	minDetections := fs.Int("min-detections", -1, "Min detections per cluster, filters out small clusters (default: 0 = no filtering)")

		CSVPath:      *csvPath,
		Filter:       filterName,
		WriteDotData: *dotData,

		CSVPath:       *csvPath,
		Filter:        filterName,
		WriteDotData:  *dotData,
		GapMultiplier: *gapMultiplier,
		MinDetections: *minDetections,

---
name: writing-skills
description: Guides the creation of effective Claude Skills with proper structure, concise content, and progressive disclosure patterns. Use when authoring new Skills, improving existing Skills, or when the user asks about Skill creation best practices.
---
# Writing Skills
Helps create effective Claude Skills following Anthropic's best practices.
## Core Principles
**Concise is key**: The context window is shared. Only add context Claude doesn't already have. Challenge each piece: "Does Claude really need this explanation?"
**Set appropriate degrees of freedom**:
- High freedom (text instructions): Multiple approaches valid, context-dependent decisions
- Medium freedom (pseudocode/scripts with parameters): Preferred pattern exists, variation acceptable
- Low freedom (specific scripts): Operations fragile, consistency critical
**Test with all models**: Skills behave differently on Haiku vs Sonnet vs Opus. Test with all models you plan to use.
## Skill Structure Requirements
### YAML Frontmatter
```yaml
---
name: skill-name-here
description: What the skill does and when to use it. Always write in third person.
---
```
**Name requirements**:
- Maximum 64 characters
- Lowercase letters, numbers, hyphens only
- No XML tags, no reserved words (anthropic, claude)
- Use gerund form: `processing-pdfs`, `analyzing-spreadsheets`
**Description requirements**:
- Maximum 1024 characters
- Include both WHAT it does and WHEN to use it
- Write in third person (not "I can help" or "You can use")
- Be specific with key terms for discovery
### Body Organization
Keep SKILL.md under 500 lines. Use progressive disclosure for longer content:
```markdown
# Skill Name
## Quick start
[Basic usage here]
## Advanced features
**Feature A**: See [FEATURE_A.md](FEATURE_A.md)
**Feature B**: See [FEATURE_B.md](FEATURE_B.md)
```
**Important**: Keep file references one level deep from SKILL.md. Deeply nested references cause partial reads.
## Common Patterns
### Workflow Pattern (for complex tasks)
Provide a checklist for multi-step processes:
````markdown
## Research synthesis workflow
Copy this checklist and track progress:
```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```
**Step 1: Read all source documents**
[Details...]
**Step 2: Identify key themes**
[Details...]
````
### Template Pattern
**For strict requirements**:
```markdown
ALWAYS use this exact template structure:
[template here]
```
**For flexible guidance**:
```markdown
Here is a sensible default format, but use best judgment:
[template here]
Adjust sections as needed for the specific context.
```
### Examples Pattern
Show input/output pairs for quality-dependent tasks:
```markdown
## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication
Add login endpoint and token validation middleware
```
```
### Conditional Workflow Pattern
```markdown
## Document modification workflow
1. Determine the modification type:
   **Creating new content?** → Follow "Creation workflow"
   **Editing existing content?** → Follow "Editing workflow"
2. Creation workflow: [steps...]
3. Editing workflow: [steps...]
```
### Feedback Loop Pattern
**Common pattern**: Run validator → fix errors → repeat
```markdown
## Document editing process
1. Make edits to `word/document.xml`
2. **Validate immediately**: `python scripts/validate.py unpacked_dir/`
3. If validation fails:
   - Review error message
   - Fix issues
   - Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python scripts/pack.py unpacked_dir/ output.docx`
```
## Content Guidelines
### Avoid Time-Sensitive Information
**Bad**: "If you're doing this before August 2025, use the old API."
**Good**: Use "old patterns" section:
```markdown
## Current method
Use the v2 API endpoint: `api.example.com/v2/messages`
## Old patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used: `api.example.com/v1/messages`
This endpoint is no longer supported.
</details>
```
### Use Consistent Terminology
Choose one term and use it throughout:
- Always "API endpoint" (not mixing "URL", "route", "path")
- Always "field" (not mixing "box", "element", "control")
### Structure Long Reference Files
For files over 100 lines, include table of contents at top:
```markdown
# API Reference
## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples
## Authentication and setup
...
```
## Anti-Patterns to Avoid
- ❌ **Windows-style paths**: Use `scripts/helper.py`, not `scripts\helper.py`
- ❌ **Too many options**: Don't list 5 libraries. Provide a default with escape hatch
- ❌ **Vague descriptions**: Not "Helps with documents" but "Extracts text and tables from PDF files"
- ❌ **Deeply nested references**: Keep references one level deep from SKILL.md
- ❌ **Time-sensitive info**: Use "old patterns" section instead
- ❌ **Inconsistent terminology**: Pick one term per concept and stick to it
- ❌ **Over-explaining**: Don't explain what Claude already knows
## Skills with Executable Code
### Provide Utility Scripts
Pre-made scripts are better than generated code:
- More reliable
- Save tokens (no code in context)
- Save time (no generation)
- Ensure consistency
**Make execution intent clear**:
- "Run `analyze_form.py` to extract fields" (execute)
- "See `analyze_form.py` for the extraction algorithm" (read as reference)
### Solve, Don't Punt
Handle error conditions in scripts rather than failing and letting Claude figure it out:
```python
def process_file(path):
    """Process a file, creating it if it doesn't exist."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        print(f"File {path} not found, creating default")
        with open(path, "w") as f:
            f.write("")
        return ""
```
### Avoid Voodoo Constants
Document why configuration values are chosen:
```python
# HTTP requests typically complete within 30 seconds
# Longer timeout accounts for slow connections
REQUEST_TIMEOUT = 30
# Three retries balances reliability vs speed
# Most intermittent failures resolve by the second retry
MAX_RETRIES = 3
```
### Package Dependencies
List required packages and verify they're available in the code execution environment. Skills run in platform-specific environments:
- **claude.ai**: Can install from npm/PyPI and pull from GitHub
- **Anthropic API**: No network access, no runtime installation
### MCP Tool References
Always use fully qualified tool names: `ServerName:tool_name`
Example: `BigQuery:bigquery_schema`, `GitHub:create_issue`
## Development Process
### Evaluation-Driven Development
1. **Identify gaps**: Run Claude on tasks without the Skill. Document failures
2. **Create evaluations**: Build 3+ test scenarios
3. **Establish baseline**: Measure performance without the Skill
4. **Write minimal instructions**: Just enough to pass evaluations
5. **Iterate**: Execute evaluations, compare, refine
### Iterative Development with Claude
**Creating a new Skill**:
1. Complete a task without a Skill (Claude A helps you work through it)
2. Identify the reusable pattern (what context did you repeatedly provide?)
3. Ask Claude A to create a Skill capturing that pattern
4. Review for conciseness (remove unnecessary explanations)
5. Improve information architecture (organize into separate files if needed)
6. Test on similar tasks (use Claude B with the Skill loaded)
7. Iterate based on observation
**Improving existing Skills**:
1. Use the Skill in real workflows (Claude B)
2. Observe behavior (where does it struggle or succeed?)
3. Return to Claude A with current SKILL.md and observations
4. Review Claude A's suggestions
5. Apply changes and test with Claude B
6. Repeat based on usage
## Checklist for Effective Skills
### Core Quality
- [ ] Description is specific with key terms
- [ ] Description includes what it does AND when to use it
- [ ] Written in third person
- [ ] SKILL.md body under 500 lines
- [ ] Additional details in separate files (if needed)
- [ ] No time-sensitive information (or in "old patterns" section)
- [ ] Consistent terminology throughout
- [ ] Examples are concrete
- [ ] File references one level deep
- [ ] Progressive disclosure used appropriately
- [ ] Workflows have clear steps
### Code and Scripts (if applicable)
- [ ] Scripts solve problems, don't punt to Claude
- [ ] Error handling is explicit
- [ ] No voodoo constants (all values justified)
- [ ] Required packages listed and verified
- [ ] No Windows-style paths (forward slashes only)
- [ ] Validation steps for critical operations
- [ ] Feedback loops for quality-critical tasks
### Testing
- [ ] At least 3 evaluations created
- [ ] Tested with target models (Haiku/Sonnet/Opus)
- [ ] Tested with real usage scenarios
- [ ] Team feedback incorporated (if applicable)
## Quick Reference
**Good description example**:
```yaml
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
```
**Progressive disclosure example**:
```markdown
## Quick start
[Basic usage]
## Advanced
**Form filling**: See [FORMS.md](FORMS.md)
**API reference**: See [REFERENCE.md](REFERENCE.md)
```
**Workflow with checklist**:
````markdown
Copy this checklist:
```
- [ ] Step 1: Analyze
- [ ] Step 2: Validate
- [ ] Step 3: Execute
```
**Step 1**: [details]
````
**Feedback loop**:
```markdown
1. Make changes
2. Validate: `python validate.py`
3. If fails, fix and validate again
4. Only proceed when validation passes
```
## Tips
- **Token budget**: Keep SKILL.md under 500 lines
- **Degrees of freedom**: Match specificity to task fragility
- **File organization**: Name files descriptively (`form_validation_rules.md`)
- **Reference files**: One level deep from SKILL.md
- **Utility scripts**: Preferred over generated code for deterministic operations
- **Testing**: Build evaluations first, then write minimal docs to pass them
- **Iteration**: Work with Claude A to create/refine, Claude B to test, observe and iterate