{
  "$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).",
      "Penalize wasted tokens — redundancy, padding, and explaining things Claude already knows — but do NOT penalize length that carries necessary, non-obvious information. A long skill that is information-dense and on-topic is fine and should not lose points for its size.",
      "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.",
      "A well-organised single file can score 3 on progressive disclosure regardless of length. Splitting content across multiple files is one valid way to organise, not a requirement — judge on navigability (clear headings, logical ordering, signposting), not file count, and never dock a skill merely for consolidating into one file.",
      "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` on how well the content is organised across whatever structure the author chose (single file or multiple). A consolidated single file that is well-structured is not penalised for not splitting."
    ],
    "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`",
      "## Overview\n[concise orientation]\n\n## Extract text\n[dense, complete instructions]\n\n## Fill forms\n[dense, complete instructions]\n\n## API reference\n[full method list inline]\n\nA single, long, well-sectioned file with a clear heading hierarchy and logical ordering — everything one navigation hop away, nothing padded."
    ],
    "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 avoid wasted tokens and assume Claude's intelligence, without being docked for legitimate length?",
      "rationale": "The context window is a public good, so skills should add only what Claude doesn't already know and avoid padding, redundancy, and re-explaining basics. But necessary, information-dense length is not waste: a long skill that stays on-topic and high-signal is fully efficient. Penalize wasted tokens, never length itself.",
      "scores": [
        {
          "score": 1,
          "anchor": "Wastes tokens; explains concepts Claude knows; padded with unnecessary context or repetition",
          "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 repetition that 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": "Information-dense; assumes Claude's competence; every token earns its place. Length is not penalized — a long skill scores 3 when the content justifies it and nothing is padding.",
          "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 / Organisation",
      "weight": 0.15,
      "question": "Is the content well-organised and easy to navigate, whether in one file or several?",
      "rationale": "Content should be easy to navigate. A single, well-structured file with a clear heading hierarchy and logical ordering is a perfectly good way to organise a skill; splitting into multiple files is optional and only helps when the body would otherwise be hard to navigate. Score on organisation and navigability — penalize disorganised walls of text and broken or deeply-nested references, never consolidation into one file.",
      "scores": [
        {
          "score": 1,
          "anchor": "Disorganised wall of text with no clear sections; OR broken / deeply-nested references (2+ levels)",
          "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 uneven; headings present but ordering or signposting is weak, or related content is scattered",
          "example": "## Overview\n[mix of getting-started and deep reference, no clear ordering]\n\n## More\nSome additional notes, loosely grouped."
        },
        {
          "score": 3,
          "anchor": "Clear, navigable organisation — a well-structured single file (logical heading hierarchy, sensible ordering, content grouped) OR appropriately signposted one-level-deep references. A consolidated single file is rewarded, not penalized, when it is well-organised.",
          "example": "## Overview\n[concise orientation]\n\n## Extract text\n[complete instructions]\n\n## Fill forms\n[complete instructions]\n\n## API reference\n[full method list]\n\nLong but cleanly sectioned, logically ordered, everything findable — no splitting required. (Equally valid: a short overview that signposts FORMS.md and REFERENCE.md one level deep.)"
        }
      ]
    }
  ],
  "scoring_notes": {
    "single_file_skills": "A large, well-organised single file is a first-class outcome. Progressive disclosure scores on organisation and navigability, not file count — never dock a skill for consolidating content into one file rather than splitting it across multiple files. Splitting is one valid option, not a requirement.",
    "length": "Legitimate length is not a defect. Conciseness penalizes wasted tokens (padding, repetition, explaining what Claude already knows), not the overall size of a skill. A long, information-dense skill can score 3 on conciseness.",
    "simple_skills": "For single-purpose skills, workflow_clarity and progressive_disclosure can score 3 if the content is clear and well-organised, even without explicit multi-step workflows or external file references. Size is not a factor.",
    "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."
  }
}