{
  "$schema": "../schemas/rubric.schema.json",
  "evaluation_target": "content",
  "scope": "SKILL.md body (markdown content after YAML frontmatter)",
  "scale": {
    "min": 1,
    "max": 3
  },
  "reference_examples": {
    "judging_guidelines": [
      "Evaluate what is written, not what could be inferred or added.",
      "Penalize explanations of concepts Claude already knows (e.g., what a PDF is, how libraries work, basic programming concepts).",
      "Reward brevity that preserves clarity; penalize verbosity even if accurate.",
      "Code examples should be executable and complete, not pseudocode, unless flexibility is explicitly justified.",
      "Time-sensitive information (specific dates, version numbers) should penalize conciseness unless placed in an 'old patterns' or 'deprecated' section.",
      "For simple skills (single task, no multi-step process), workflow clarity can score 3 if the single action is unambiguous.",
      "For skills under 50 lines with no need for external references, progressive disclosure can score 3 with just well-organized sections.",
      "Missing validation/verification steps in workflows involving destructive or batch operations should cap workflow clarity at 2.",
      "When bundle files are provided, score `progressive_disclosure` against the actual bundle structure (file listing + any referenced paths) rather than on references alone."
    ],
    "good_overall_examples": [
      "## Quick start\n\nExtract text with pdfplumber:\n```python\nimport pdfplumber\nwith pdfplumber.open(\"file.pdf\") as pdf:\n    text = pdf.pages[0].extract_text()\n```\n\n## Advanced features\n\n**Form filling**: See [FORMS.md](FORMS.md) for complete guide\n**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods",
      "## Commit message format\n\nGenerate commit messages following these examples:\n\n**Example 1:**\nInput: Added user authentication with JWT tokens\nOutput:\n```\nfeat(auth): implement JWT-based authentication\n\nAdd login endpoint and token validation middleware\n```\n\nFollow this style: type(scope): brief description, then detailed explanation.",
      "## Document editing process\n\n1. Make your edits to `word/document.xml`\n2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`\n3. If validation fails:\n   - Review the error message carefully\n   - Fix the issues in the XML\n   - Run validation again\n4. **Only proceed when validation passes**\n5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`"
    ],
    "bad_overall_examples": [
      "PDF (Portable Document Format) files are a common file format that contains text, images, and other content. To extract text from a PDF, you'll need to use a library. There are many libraries available for PDF processing, but we recommend pdfplumber because it's easy to use and handles most cases well. First, you'll need to install it using pip...",
      "You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or camelot, or tabula-py depending on your needs. Each has different strengths...",
      "Process the document.\n\nSee advanced.md for more details.\n\n(In advanced.md: See details.md for the actual instructions.)",
      "If you're doing this before August 2025, use the old API. After August 2025, use the new API."
    ]
  },
  "dimensions": [
    {
      "id": "conciseness",
      "name": "Conciseness / Token Efficiency",
      "weight": 0.3,
      "question": "Does it respect token budget and assume Claude's intelligence?",
      "rationale": "The context window is a public good. Every unnecessary token competes with conversation history and other context. Skills should add only what Claude doesn't already know.",
      "scores": [
        {
          "score": 1,
          "anchor": "Verbose; explains concepts Claude knows; padded with unnecessary context",
          "example": "PDF (Portable Document Format) files are a common file format that contains text, images, and other content. To extract text from a PDF, you'll need to use a library. There are many libraries available..."
        },
        {
          "score": 2,
          "anchor": "Mostly efficient but includes some unnecessary explanation or could be tightened",
          "example": "Use pdfplumber for text extraction. It's a good library that handles most PDF formats well.\n\n```python\nimport pdfplumber\nwith pdfplumber.open(\"file.pdf\") as pdf:\n    text = pdf.pages[0].extract_text()\n```"
        },
        {
          "score": 3,
          "anchor": "Lean and efficient; assumes Claude's competence; every token earns its place",
          "example": "## Extract PDF text\n\n```python\nimport pdfplumber\nwith pdfplumber.open(\"file.pdf\") as pdf:\n    text = pdf.pages[0].extract_text()\n```"
        }
      ]
    },
    {
      "id": "actionability",
      "name": "Actionability",
      "weight": 0.3,
      "question": "Does it provide concrete, executable guidance vs vague direction?",
      "rationale": "Skills succeed when Claude knows exactly what to do. Concrete code, specific commands, and clear examples beat abstract descriptions.",
      "scores": [
        {
          "score": 1,
          "anchor": "Vague or abstract; no concrete code/commands; describes rather than instructs",
          "example": "Use a PDF library to extract the text content from the document and process it as needed."
        },
        {
          "score": 2,
          "anchor": "Some concrete guidance but incomplete; pseudocode instead of executable code; missing key details",
          "example": "Use pdfplumber to extract text:\n```\n# pseudocode\nopen pdf\nfor each page:\n    extract text\n```"
        },
        {
          "score": 3,
          "anchor": "Fully executable code/commands; specific examples; copy-paste ready",
          "example": "```python\nimport pdfplumber\nwith pdfplumber.open(\"file.pdf\") as pdf:\n    for page in pdf.pages:\n        print(page.extract_text())\n```\n\nFor tables: `page.extract_tables()` returns list of lists."
        }
      ]
    },
    {
      "id": "workflow_clarity",
      "name": "Workflow Clarity",
      "weight": 0.25,
      "question": "Are multi-step processes clearly sequenced with validation checkpoints?",
      "rationale": "Complex operations fail when steps are unclear or validation is missing. Clear workflows with explicit checkpoints catch errors early and guide Claude through fragile operations.",
      "scores": [
        {
          "score": 1,
          "anchor": "Steps unclear or missing; no sequence for multi-step tasks; no validation mentioned for risky operations",
          "example": "Edit the XML file, then rebuild the document. Make sure it's valid."
        },
        {
          "score": 2,
          "anchor": "Steps listed but validation gaps; sequence present but checkpoints missing or implicit",
          "example": "1. Unpack the document\n2. Edit word/document.xml\n3. Repack the document\n4. Test the output"
        },
        {
          "score": 3,
          "anchor": "Clear sequence with explicit validation steps; feedback loops for error recovery; checklists for complex processes",
          "example": "1. Unpack: `python scripts/unpack.py input.docx`\n2. Edit `word/document.xml`\n3. **Validate**: `python scripts/validate.py unpacked/`\n4. If errors: fix and re-validate\n5. **Only when valid**: `python scripts/pack.py unpacked/ output.docx`"
        }
      ]
    },
    {
      "id": "progressive_disclosure",
      "name": "Progressive Disclosure",
      "weight": 0.15,
      "question": "Does it appropriately structure content across files with clear navigation?",
      "rationale": "SKILL.md should be an overview pointing to detailed materials. References should be one level deep, clearly signaled, and organized for discovery.",
      "scores": [
        {
          "score": 1,
          "anchor": "Monolithic wall of text; deeply nested references (2+ levels); poor organization",
          "example": "See advanced.md for details.\n\n(In advanced.md: See details.md for the actual information.)\n\n(In details.md: The real content is here.)"
        },
        {
          "score": 2,
          "anchor": "Some structure but could be better organized; references present but not clearly signaled; content that should be separate is inline",
          "example": "## Overview\n[200 lines of API reference that could be in a separate file]\n\n## Advanced\nSee ADVANCED.md"
        },
        {
          "score": 3,
          "anchor": "Clear overview with well-signaled one-level-deep references; content appropriately split; easy navigation",
          "example": "## Quick start\n[Concise getting-started content]\n\n## Advanced features\n**Form filling**: See [FORMS.md](FORMS.md)\n**API reference**: See [REFERENCE.md](REFERENCE.md)\n**Examples**: See [EXAMPLES.md](EXAMPLES.md)"
        }
      ]
    }
  ],
  "scoring_notes": {
    "simple_skills": "For simple, single-purpose skills (under 50 lines, single task), workflow_clarity and progressive_disclosure can score 3 if the content is clear and well-organized, even without explicit multi-step workflows or external file references.",
    "code_vs_instruction_skills": "Apply the same rubric to both. Code skills should have executable examples; instruction-only skills should have concrete, specific guidance. Absence of code in an instruction-only skill is not penalized if the guidance is actionable.",
    "feedback_loops": "Feedback loops (validate -> fix -> retry) are especially important for: batch operations, destructive changes, XML/document manipulation, database operations. Missing feedback loops in these contexts should cap workflow_clarity at 2."
  }
}