# 克隆特定的 PR 分支
git clone -b skill-analysis https://github.com/eovidiu/skills.git
cd skills/skill-quality-analyzer

# 复制到您的 Claude skills 目录
cp -r ../skill-quality-analyzer ~/.claude/skills/

# PR #83 合并到主分支后
git clone https://github.com/anthropics/skills.git
cd skills/skill-quality-analyzer
cp -r . ~/.claude/skills/skill-quality-analyzer/

---
name: api-contract-manager
description: Manage API contracts with validation and versioning. Use when designing APIs or ensuring contract compliance. Triggers: "validate API contract", "check API compatibility", "version API schema".
---

# API Contract Manager

## Overview
Manages API contracts through validation, versioning, and compatibility checking. Ensures APIs adhere to organizational standards and maintain backward compatibility.

## When to Use This Skill

**Use this skill when:**
- Designing new API endpoints
- Validating existing API contracts
- Checking breaking changes between versions
- Ensuring compliance with API standards

**Trigger phrases:**
- "Validate this API contract"
- "Check API compatibility between versions"
- "Does this API meet our standards?"

## Workflow

[Detailed step-by-step process]

## Resources
- `references/openapi-spec.md` - OpenAPI specification guidelines
- `scripts/validator.py` - Contract validation script
- `assets/contract-template.yaml` - Template for new contracts

## Trigger Phrases

Natural ways to invoke this skill:
- "Analyze code quality for this repository"
- "Run quality check on my skill"
- "Review this skill's structure"
- "Is this skill well-built?"
- "Evaluate skill from [GitHub URL]"

"""
Validation script for API contracts.

This script validates API contracts against OpenAPI 3.0 specification
and checks for breaking changes between versions.
"""

import json
import sys
from typing import Dict, List, Optional
from pathlib import Path


class ContractValidator:
    """Validates API contracts and detects breaking changes."""

    def __init__(self, contract_path: Path):
        """
        Initialize validator with contract file.

        Args:
            contract_path: Path to OpenAPI contract file

        Raises:
            FileNotFoundError: If contract file doesn't exist
            ValueError: If contract is invalid JSON
        """
        if not contract_path.exists():
            raise FileNotFoundError(f"Contract not found: {contract_path}")

        with open(contract_path) as f:
            self.contract = json.load(f)

    def validate_structure(self) -> List[str]:
        """
        Validate contract structure against OpenAPI spec.

        Returns:
            List of validation errors, empty if valid
        """
        errors = []

        # Check required top-level fields
        required_fields = ['openapi', 'info', 'paths']
        for field in required_fields:
            if field not in self.contract:
                errors.append(f"Missing required field: {field}")

        # Validate OpenAPI version
        if 'openapi' in self.contract:
            version = self.contract['openapi']
            if not version.startswith('3.'):
                errors.append(f"Unsupported OpenAPI version: {version}")

        return errors


def main():
    """Main entry point for contract validation."""
    if len(sys.argv) != 2:
        print("Usage: python validator.py <contract.json>")
        sys.exit(1)

    contract_path = Path(sys.argv[1])

    try:
        validator = ContractValidator(contract_path)
        errors = validator.validate_structure()

        if errors:
            print("Validation failed:")
            for error in errors:
                print(f"  - {error}")
            sys.exit(1)
        else:
            print("✅ Contract is valid")
            sys.exit(0)

    except Exception as e:
        print(f"Error: {e}")
        sys.exit(1)


if __name__ == '__main__':
    main()

## Tools Used

This skill uses the following tools:
- `read_file` - To load contract files
- `grep` - To search for specific patterns
- `bash` - To run validation scripts

MCP Integration:
- Uses `openapi-mcp` server for spec validation
- Connection managed automatically
- Fallback to local validation if MCP unavailable

Resource Strategy:
- Main SKILL.md kept under 5KB
- Detailed specs in references/
- Examples loaded on-demand

# Skill Quality Analysis Report

## Executive Summary
- Overall Score: 78/100 (C+)
- Letter Grade: C+
- Certification Status: FAILED (Security < 80)
- Top Priority: Fix security vulnerabilities

## Dimension Scores

### 1. Structure & Documentation: 85/100 (B)
**Strengths:**
- ✅ Valid YAML frontmatter
- ✅ Clear description with trigger phrases
- ✅ Well-organized sections

**Weaknesses:**
- ❌ Missing examples for advanced use cases
- ❌ References/ directory lacks README

**Recommendations:**
1. Add 2-3 more realistic examples
2. Create references/README.md explaining structure
3. Include template files in assets/

### 2. Security: 65/100 (D)
**CRITICAL ISSUES (Must Fix):**
- ❌ Hardcoded API key in scripts/fetcher.py:15
- ❌ User input passed to subprocess without validation (scripts/runner.py:42)

**HIGH PRIORITY:**
- ⚠️  Base64 encoded string in SKILL.md (line 234) - unclear purpose
- ⚠️  Network call to undocumented endpoint (scripts/sync.py:67)

**Recommendations:**
1. IMMEDIATE: Remove hardcoded API key, use environment variable
2. IMMEDIATE: Add input validation and sanitization in runner.py
3. Document purpose of base64 string or remove if unnecessary
4. Document network endpoint in SKILL.md or remove if not needed

[Continues for all dimensions...]

## Action Plan

### Immediate Actions (Required for Certification)
1. Fix security issues (scripts/fetcher.py, scripts/runner.py)
2. Add input validation
3. Remove hardcoded secrets

### Short-term Improvements (2-4 hours)
1. Add missing examples
2. Improve script documentation
3. Create references/README.md

### Long-term Enhancements (Optional)
1. Add MCP integration for external APIs
2. Create interactive tutorials
3. Build test suite

Claude: Let's review your skill quality together! I'll guide you through each dimension.

--- DIMENSION 1: Structure & Documentation (20%) ---

Current Score: 75/100 (C)

I found these issues:

1. Your description is good but could be more specific:
   Current: "Manages API contracts"
   Better: "Validate API contracts with OpenAPI 3.0 and detect breaking changes.
            Use when designing APIs or ensuring backward compatibility."

Would you like me to suggest an improved description? (y/n)

User: y

Claude: Here's my suggestion:
[Provides improved description]

Would you like to update it now? I can help you edit SKILL.md. (y/n)

User: y

[Claude helps edit the file]

Claude: Great! Description improved. Now let's check your trigger phrases...

[Continues through all issues in this dimension]

Claude: --- SUMMARY: Structure & Documentation ---
Before: 75/100
After: 90/100 (+15 points!)

Ready to move to the next dimension: Security? (y/n)

# Skill Certification Result

## ❌ CERTIFICATION FAILED

**Overall Score:** 68/100 (D+)
**Decision:** DO NOT DEPLOY

## Blocking Issues (Must Fix)

### CRITICAL: Security Threshold Not Met
- Current: 65/100
- Required: ≥80/100
- Gap: -15 points

**Blocking security issues:**
1. Hardcoded API key (scripts/fetcher.py:15) - CRITICAL
2. Unvalidated user input to subprocess (scripts/runner.py:42) - CRITICAL
3. Undocumented network call (scripts/sync.py:67) - HIGH

### FAILED: Overall Score Below 70
- Current: 68/100
- Required: ≥70/100
- Gap: -2 points

## Quick Fix Checklist

To pass certification, complete these steps:

- [ ] Remove hardcoded API key, use os.environ['API_KEY']
- [ ] Add input validation in runner.py before subprocess call
- [ ] Document network endpoint in SKILL.md or remove
- [ ] Add 1-2 examples to improve UX score (+5 points estimated)

**Estimated time to fix:** 1-2 hours
**Re-run certification after fixes:** `analyze skill quality --mode certification`

Overall Score = (Structure × 0.20) + (Security × 0.30) + (UX × 0.20) +
                (Code Quality × 0.15) + (Integration × 0.15)

User: "Analyze skill quality for https://github.com/anthropics/skills/tree/main/mcp-builder"

Claude (using skill-quality-analyzer):

Step 1: Fetching skill from GitHub...
✅ Cloned successfully

Step 2: Understanding skill purpose...
This skill guides developers through creating MCP servers.

Step 3: Running security analysis...
✅ Security scan complete: SAFE (95/100)
- No critical or high findings
- 1 medium finding: Large reference files (acceptable)

Step 4-7: Evaluating all dimensions...

Step 8: Generating comprehensive report...

# Quality Analysis: mcp-builder

## Overall Assessment
- **Score:** 94/100 (A)
- **Grade:** A (Excellent)
- **Certification:** ✅ PASS

## Dimension Scores

### Structure & Documentation: 98/100 (A+)
**Exemplary**
- Perfect YAML frontmatter
- Excellent description with clear triggers
- Comprehensive workflow documentation
- Multiple reference documents
- Well-organized scripts

### Security: 95/100 (A)
**Excellent**
- No critical issues
- No high-priority issues
- 1 medium: Large reference files (16KB+) - acceptable for this use case
- All scripts use safe patterns

### User Experience: 92/100 (A)
**Excellent**
- Clear 4-phase workflow
- Extensive examples
- Well-documented edge cases
- Minor: Could add more beginner-friendly examples

### Code Quality: 90/100 (A-)
**Very Good**
- Clean Python scripts (connections.py, evaluation.py)
- Good documentation
- Consistent style
- Minor: Some functions could be broken down further

### Integration: 95/100 (A)
**Excellent**
- Sophisticated tool usage
- Efficient resource loading
- Good separation of concerns

## Recommendations

### Short-term (Optional Enhancements)
1. Add 1-2 beginner-friendly examples
2. Consider breaking down longer functions in evaluation.py

This skill exemplifies best practices and serves as an excellent template for others.

User: "Review this skill interactively: ./my-api-skill"

Claude: Let's improve your skill together! I'll guide you through each area.

🔍 Quick scan complete. I found some opportunities for improvement.

--- SECURITY CHECK (30% of score) ---

⚠️  I found 2 security concerns:

1. MEDIUM: Hardcoded API endpoint in SKILL.md line 45
   Current: `API_URL = "https://api.example.com"`
   Risk: If endpoint changes, skill breaks; not configurable
   Fix: Use environment variable or config file

2. LOW: Missing input validation in scripts/fetch.py line 23
   Current: `response = requests.get(user_url)`
   Risk: Could access unintended URLs
   Fix: Validate URL domain before request

Want me to show you how to fix these? (y/n)

User: y

Claude: Great! Let's fix the hardcoded endpoint first.

Here's the improved approach:

```python
# scripts/fetch.py
import os

# Use environment variable with fallback
API_URL = os.environ.get('API_URL', 'https://api.example.com')

# Validate URL before use
def fetch_data(endpoint):
    full_url = f"{API_URL}/{endpoint}"

    # Validate domain
    parsed = urllib.parse.urlparse(full_url)
    if parsed.netloc not in ['api.example.com', 'api-staging.example.com']:
        raise ValueError(f"Invalid domain: {parsed.netloc}")

    return requests.get(full_url)

### 示例 3：通过/失败认证

```markdown
User: "Certify skill quality for ./marketplace-submission --mode certification"

Claude (using skill-quality-analyzer):

🔍 Running certification analysis...

# Skill Certification: marketplace-submission

## ✅ CERTIFICATION PASSED

**Overall Score:** 82/100 (B)
**Decision:** APPROVED FOR DEPLOYMENT

## Dimension Results

✅ Overall Score: 82/100 (Required: ≥70)
✅ Security: 88/100 (Required: ≥80)
✅ Structure: 85/100 (Required: ≥70)
✅ UX: 78/100 (Required: ≥70)
✅ Code Quality: 75/100 (Required: ≥60)
✅ Integration: 70/100 (Required: ≥60)
✅ No CRITICAL security findings

## Quality Summary

Your skill meets all certification requirements:
- High security standards
- Good documentation
- Clear user experience
- Solid code quality
- Appropriate tool integration

**Recommendation:** APPROVED for marketplace submission

## Optional Enhancements (Not Required)

To reach "Excellent" (A grade), consider:
- Add 2 more examples (+3 UX points)
- Improve script documentation (+5 Code Quality points)
- Optimize tool usage (+5 Integration points)

Estimated time: 2-3 hours
Potential score: 82 → 90 (A-)

❌ 差：" Helps with API work"
✅ 好："Validate API contracts with OpenAPI 3.0 and detect breaking changes. Use when designing APIs or ensuring backward compatibility. Triggers: 'validate API contract', 'check API compatibility'."

# 使用详细输出运行安全分析器
python3 skill-security-analyzer/scripts/security_scanner.py ./my-skill --verbose

# 详细审查每个发现
# 在 SKILL.md 中记录合法用例

# 从 PR #83（当前）
git clone -b skill-analysis https://github.com/eovidiu/skills.git
cp -r skills/skill-quality-analyzer ~/.claude/skills/

# 合并后（未来）
git clone https://github.com/anthropics/skills.git
cp -r skills/skill-quality-analyzer ~/.claude/skills/

# 综合分析
"Analyze skill quality for https://github.com/user/my-skill"

# 交互式改进
"Review this skill interactively: ./my-skill"

# 认证检查
"Certify skill quality for ./marketplace-submission --mode certification"