skill-builder

---
name: process-pdfs
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.
---

<objective>
Extract text and tables from PDF files, fill forms, and merge documents using Python libraries.
</objective>

<quick_start>
Extract text with pdfplumber:

```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

</example_skill>
</quick_start>

<xml_structure>
<required_tags>
All skills must have these tags:

- **`<objective>`** - What the skill does and why it matters
- **`<quick_start>`** - Immediate, actionable guidance
- **`<success_criteria>`** or **`<when_successful>`** - How to know it worked
</required_tags>

<conditional_tags>
Based on skill complexity, add these tags as needed:

- **`<context>`** - Background/situational information
- **`<workflow>` or `<process>`** - Step-by-step procedures
- **`<advanced_features>`** - Deep-dive topics (progressive disclosure)
- **`<validation>`** - How to verify outputs
- **`<examples>`** - Multi-shot learning
- **`<anti_patterns>`** - Common mistakes to avoid
- **`<security_checklist>`** - Non-negotiable security patterns
- **`<testing>`** - Testing workflows
- **`<common_patterns>`** - Code examples and recipes
- **`<reference_guides>` or `<detailed_references>`** - Links to reference files
</conditional_tags>

<critical_rule>
**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
</critical_rule>
</xml_structure>

<intelligence_rules>
<simple_skills>
Single domain, straightforward tasks: Use required tags only.

Example: Text extraction, file format conversion, simple API calls
</simple_skills>

<medium_skills>
Multiple patterns, some complexity: Use required tags + workflow/examples as needed.

Example: Document processing with multiple steps, API integration with configuration
</medium_skills>

<complex_skills>
Multiple domains, security concerns, API integrations: Use required tags + conditional tags as appropriate.

Example: Payment processing, authentication systems, multi-step workflows with validation
</complex_skills>

<principle>
Don't over-engineer simple skills. Don't under-specify complex skills. Match tag selection to actual complexity and user needs.
</principle>
</intelligence_rules>

<generation_protocol>
<step_0>
<description>
**Adaptive Requirements Gathering**: Before building, gather requirements through intelligent questioning that infers obvious details and asks about genuine gaps.
</description>

<critical_first_action>
**BEFORE doing anything else**, check if context was provided.

IF no context provided (user just invoked the skill without describing what to build):
→ **IMMEDIATELY use AskUserQuestion** with these exact options:

1. **Create a new skill** - Build a skill from scratch
2. **Update an existing skill** - Modify or improve an existing skill
3. **Get guidance on skill design** - Help me think through what kind of skill I need

**DO NOT** ask "what would you like to build?" in plain text. **USE the AskUserQuestion tool.**

Routing after selection:
- "Create new" → proceed to adaptive intake below
- "Update existing" → enumerate existing skills as numbered list (see below), then gather requirements for changes
- "Guidance" → help user clarify needs before building

<update_existing_flow>
When "Update existing" is selected:

1. **List all skills in chat as numbered list** (DO NOT use AskUserQuestion - there may be many skills):
   - Glob for `~/skills/*/SKILL.md`
   - Present as numbered list in chat:
     ```
     Available skills:
     1. create-agent-skills
     2. generate-natal-chart
     3. manage-stripe
     ...
     ```
   - Ask: "Which skill would you like to update? (enter number)"

2. After user enters number, read that skill's SKILL.md
3. Ask what they want to change/improve using AskUserQuestion or direct question
4. Proceed with modifications
</update_existing_flow>

IF context was provided (user said "build a skill for X"):
→ Skip this gate. Proceed directly to adaptive intake.
</critical_first_action>

<adaptive_intake>
<analyze_description>
Parse the initial description:
- What's explicitly stated (operations, services, outputs)
- What can be inferred without asking (skill type, complexity, obvious patterns)
- What's genuinely unclear or ambiguous (scope boundaries, edge cases, specific behaviors)

Do NOT ask about things that are obvious from context.
</analyze_description>

<generate_questions>
Use AskUserQuestion to ask 2-4 domain-specific questions based on actual gaps.

Question generation guidance:
- **Scope questions**: "What specific operations?" not "What should it do?"
- **Complexity questions**: "Should this handle [specific edge case]?" based on domain knowledge
- **Output questions**: "What should the user see/get when successful?"
- **Boundary questions**: "Should this also handle [related thing] or stay focused?"

Avoid:
- Questions answerable from the initial description
- Generic questions that apply to all skills
- Yes/no questions when options would be more helpful
- Obvious questions like "what should it be called?" when the name is clear

Each question option should include a description explaining the implications of that choice.
</generate_questions>

<decision_gate>
After receiving answers, present decision gate using AskUserQuestion:

Question: "Ready to proceed with building, or would you like me to ask more questions?"

Options:
1. **Proceed to building** - I have enough context to build the skill
2. **Ask more questions** - There are more details to clarify
3. **Let me add details** - I want to provide additional context

If "Ask more questions" selected → loop back to generate_questions with refined focus
If "Let me add details" → receive additional context, then re-evaluate
If "Proceed" → continue to research_trigger, then step_1
</decision_gate>

<research_trigger>
<detection_patterns>
Detect if the skill involves ANY of the following:

**External APIs or web services:**
- Keywords: "API", "endpoint", "REST", "GraphQL", "webhook", "HTTP"
- Service names: "Stripe", "AWS", "Firebase", "OpenAI", "Anthropic", etc.

**Standard vocabularies and ontologies:**
- Keywords: "schema.org", "vocabulary", "ontology", "JSON-LD", "RDF", "microdata"
- Examples: Schema.org types, Dublin Core, FOAF

**Protocol specifications:**
- Keywords: "specification", "standard", "protocol"
- Examples: "HTTP", "WebSocket", "MQTT", "OAuth", "SAML"

**Third-party libraries or frameworks:**
- Keywords: "library", "package", "framework", "npm", "pip", "cargo"
- Examples: "React", "Django", "pandas", "TensorFlow"

**Data format standards:**
- Keywords: "format", "parser", "serialization"
- Examples: "CSV", "Parquet", "Protocol Buffers", "Avro", "XML"

Detection method: Check user's initial description and all collected requirements for these keywords or patterns.
</detection_patterns>

<research_prompt>
When detected, use AskUserQuestion:

"This skill involves [detected technology/standard]. Would you like me to research current [technology] documentation and patterns before building?"

Options:
1. **Yes, research first** - Fetch 2024-2025 documentation for accurate, up-to-date implementation
2. **No, proceed with general patterns** - Use knowledge cutoff data (January 2025)
3. **I'll provide the documentation** - User will supply relevant documentation or links

If option 1 selected:
- For web APIs: Use WebSearch for "[technology] API documentation 2024 2025"
- For libraries: Use Context7 MCP if available, otherwise WebSearch
- For standards/vocabularies: Use WebSearch for "[standard] specification latest"
- Focus on: current versions, recent changes, migration guides, common patterns
- Summarize findings in internal notes for use in skill generation

If option 3 selected:
- Wait for user to provide documentation
- Read provided links or files
- Summarize key information for skill generation
</research_prompt>

<research_findings_usage>
Incorporate research findings into:
- **Step 1** (Domain analysis): Update with current patterns and best practices
- **Step 4** (Content writing): Use current syntax, API endpoints, method signatures
- **Step 5** (Reference files): Include links to up-to-date documentation
- **Examples and code blocks**: Ensure all code examples use current versions

Note findings in skill generation process:

</research_findings_usage>
</research_trigger>
</adaptive_intake>
</step_0>

<step_0_5>
<description>**Project Context Detection**: Determine if skill should be project-specific or global.</description>

<detection_logic>
Check for project indicators in current working directory or parent directories:

1. **Primary indicators** (strong project context):
   - `CLAUDE.md` file exists
   - `.claude/` directory exists
   - Git repository root (`.git/` directory)

2. **Secondary indicators** (language-specific projects):
   - `package.json` (Node.js)
   - `pyproject.toml` or `setup.py` (Python)
   - `Cargo.toml` (Rust)
   - `pom.xml` or `build.gradle` (Java)
   - `go.mod` (Go)

3. **Path determination**:
   ```bash
   # Use Bash to check project context:
   if [ -f "CLAUDE.md" ] || [ -d ".claude" ]; then
     PROJECT_CONTEXT=true
     PROJECT_ROOT=$(pwd)
   elif git rev-parse --git-dir > /dev/null 2>&1; then
     PROJECT_CONTEXT=true
     PROJECT_ROOT=$(git rev-parse --show-toplevel)
   else
     PROJECT_CONTEXT=false
   fi

# Check SKILL.md exists
[ -f "$SKILLS_PATH/$SKILL_NAME/SKILL.md" ] && echo "✅ SKILL.md exists" || echo "❌ SKILL.md missing"

# Check directory name matches YAML name
YAML_NAME=$(head -20 "$SKILLS_PATH/$SKILL_NAME/SKILL.md" | grep "^name:" | cut -d: -f2 | tr -d ' ')
[ "$YAML_NAME" = "$SKILL_NAME" ] && echo "✅ Name matches directory" || echo "⚠️  Name mismatch"

# Extract and validate YAML
head -20 "$SKILLS_PATH/$SKILL_NAME/SKILL.md" | python3 -c "
import yaml, sys
try:
    doc = yaml.safe_load(sys.stdin)
    print('✅ YAML syntax valid')

    # Check required fields
    if 'name' in doc:
        print(f'✅ Name field present: {doc[\"name\"]}')
        if len(doc['name']) <= 64:
            print(f'✅ Name length OK: {len(doc[\"name\"])} chars')
        else:
            print(f'⚠️  Name too long: {len(doc[\"name\"])} chars (max 64)')
    else:
        print('❌ Name field missing')

    if 'description' in doc:
        print(f'✅ Description field present: {len(doc[\"description\"])} chars')
        if len(doc['description']) <= 1024:
            print(f'✅ Description length OK')
        else:
            print(f'⚠️  Description too long: {len(doc[\"description\"])} chars (max 1024)')
    else:
        print('❌ Description field missing')

except yaml.YAMLError as e:
    print(f'❌ YAML parse error: {e}')
"

LINE_COUNT=$(wc -l < "$SKILLS_PATH/$SKILL_NAME/SKILL.md")
echo "SKILL.md line count: $LINE_COUNT"
if [ $LINE_COUNT -lt 500 ]; then
    echo "✅ Line count under 500 limit ($LINE_COUNT lines, $(( (500 - LINE_COUNT) )) remaining)"
else
    echo "⚠️  Line count exceeds 500 limit ($LINE_COUNT lines, $(( (LINE_COUNT - 500) )) over)"
fi

# Check for markdown headings
HEADING_COUNT=$(grep -c '^#' "$SKILLS_PATH/$SKILL_NAME/SKILL.md" || echo 0)
if [ $HEADING_COUNT -eq 0 ]; then
    echo "✅ No markdown headings found"
else
    echo "⚠️  Found $HEADING_COUNT markdown headings - should use XML tags instead"
    grep -n '^#' "$SKILLS_PATH/$SKILL_NAME/SKILL.md"
fi

# Check required tags
for TAG in "objective" "quick_start" "success_criteria"; do
    if grep -q "<$TAG>" "$SKILLS_PATH/$SKILL_NAME/SKILL.md"; then
        echo "✅ Required tag <$TAG> present"
    else
        if [ "$TAG" = "success_criteria" ]; then
            if grep -q "<when_successful>" "$SKILLS_PATH/$SKILL_NAME/SKILL.md"; then
                echo "✅ Alternative tag <when_successful> present"
            else
                echo "❌ Missing required tag: <$TAG> or <when_successful>"
            fi
        else
            echo "❌ Missing required tag: <$TAG>"
        fi
    fi
done

# List all XML tags found
echo "XML tags found:"
grep -oE '<[a-z_]+>' "$SKILLS_PATH/$SKILL_NAME/SKILL.md" | sort | uniq -c | sort -rn

if [ $LINE_COUNT -gt 300 ]; then
    if [ -d "$SKILLS_PATH/$SKILL_NAME/references" ]; then
        REF_COUNT=$(find "$SKILLS_PATH/$SKILL_NAME/references" -name "*.md" | wc -l)
        echo "✅ Progressive disclosure: $REF_COUNT reference files created"
    else
        echo "⚠️  SKILL.md is $LINE_COUNT lines but no reference files found - consider splitting"
    fi
fi

# Check all reference links exist
grep -oE '\[.*\]\([^)]+\.md\)' "$SKILLS_PATH/$SKILL_NAME/SKILL.md" | while read link; do
    FILE=$(echo "$link" | sed 's/.*(\(.*\))/\1/')
    if [ -f "$SKILLS_PATH/$SKILL_NAME/$FILE" ]; then
        echo "✅ Reference link valid: $FILE"
    else
        echo "⚠️  Broken reference link: $FILE"
    fi
done

# Check verb-noun pattern
SKILL_FIRST_WORD=$(echo "$SKILL_NAME" | cut -d- -f1)
COMMON_VERBS="create manage setup generate analyze process coordinate build handle configure deploy execute extract transform validate parse render compile"

if echo "$COMMON_VERBS" | grep -qw "$SKILL_FIRST_WORD"; then
    echo "✅ Naming convention: '$SKILL_FIRST_WORD' follows verb-noun pattern"
else
    echo "⚠️  Naming: '$SKILL_FIRST_WORD' is not a common verb - verify it's action-oriented"
fi

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Skill Validation Report: [skill-name]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

File Structure:     [✅/❌] [details]
YAML Frontmatter:   [✅/❌] [details]
Line Count:         [✅/⚠️]  [X lines / 500 limit]
Required Tags:      [✅/❌] [3/3 present]
No MD Headings:     [✅/⚠️]  [X found]
XML Structure:      [✅/❌] [tags properly nested]
Progressive Disc:   [✅/⚠️]  [X ref files]
Reference Links:    [✅/⚠️]  [all valid / X broken]
Naming Convention:  [✅/⚠️]  [verb-noun pattern]
Slash Command:      [✅/❌] [exists at correct path]

Overall Status: [PASS ✅ / NEEDS FIXES ⚠️  / FAIL ❌]

[If issues found, list them with suggested fixes]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---
description: {Brief description of what the skill does}
argument-hint: [{argument description}]
allowed-tools: Skill({skill-name})
---

<objective>
Delegate {task} to the {skill-name} skill for: $ARGUMENTS

This routes to specialized skill containing patterns, best practices, and workflows.
</objective>

<process>
1. Use Skill tool to invoke {skill-name} skill
2. Pass user's request: $ARGUMENTS
3. Let skill handle workflow
</process>

<success_criteria>
- Skill successfully invoked
- Arguments passed correctly to skill
</success_criteria>

---
name: skill-name-here
description: What it does and when to use it (third person, specific triggers)
---