corubrics-rubric

A Pi skill that authors a CoRubrics-compatible rubric from a strict JSON spec and exports it as an .xlsx whose Rúbrica block pastes straight into a CoRubrics Google Sheet.

Purpose

CoRubrics (corubrics.co) is a Spanish SaaS for co-evaluation and rubric-based grading. It publishes no API, no webhooks, no SDK and no developer documentation, and its terms of service forbid reverse engineering and automated scraping. Its evaluation flow therefore cannot be driven programmatically, and this skill does not try to.

What the platform also does not do is help write the rubric. It validates nothing about rubric quality: non-graduated descriptors, criteria that are not observable, and duplicated wording are all accepted as-is.

This skill covers exactly that missing layer:

1. Author — a strict JSON spec models the criteria and their four graduated descriptors.
2. Audit — the auditor rejects mechanical defects (ERROR) and reports quality hazards and copy-paste risks (WARNING) before anything is exported.
3. Export — the builder writes a byte-faithful copy of the CoRubrics template, changing only the generated rows and two style entries, so the result pastes without a single fix-up.

The platform keeps owning the evaluation flow; the skill stays strictly in the authoring layer.

Who it is for

Teachers who grade with CoRubrics and build many rubrics with a homogeneous structure — in particular vocational training (FP) and LOMLOE modules — and who want those rubrics consistent, defensible and gradeable with real evidence.

You do not need to be a programmer. The spec is a plain text file and the two commands are copy-paste; agents running in Pi load the skill on their own when you ask for a rubric.

Rubric content is written in Spanish, because the CoRubrics template and its level labels are Spanish:

Level	Score
EXPERTO	4
AVANZADO	3
APRENDIZ	2
NOVEL	1

What it does not do

• No programmatic access to corubrics.co. No API, webhooks or SDK exist, and the terms forbid scraping and reverse engineering. Authoring, auditing and export only.
• Not the evaluation itself. The Alumnos (students) and Profes (co-evaluators) sheets are yours to fill from your own class list; the skill never writes them.
• No grading or analytics. It produces rubrics, not marks.
• No changes to the fixed scale. The level names and the scores 4 / 3 / 2 / 1 are owned by CoRubrics and stay untouched.
• Not the homonymous tools. The legacy CoRubrics Google Sheets add-on and corubric.com are different products; this skill targets corubrics.co and its Rúbrica sheet layout only.

Requirements

Python 3.8 or newer, standard library only — there is nothing to install, no pip, no virtual environment. Developed and tested on Python 3.14.

Installation

A Pi skill is a directory containing a SKILL.md. Pi discovers directories recursively under its skill locations, so installing this skill means putting the repository inside one of them.

Global install (recommended)

Clone straight into the global skills directory:

git clone https://github.com/jmoredev/corubrics-skill.git ~/.pi/agent/skills/corubrics-rubric

~/.agents/skills/ works the same way and is shared with other agent harnesses that follow the Agent Skills standard. Restart Pi (or start a new session) and corubrics-rubric appears in the available skills. Update later with git pull inside that directory.

Keep the clone elsewhere and link it

Useful when you develop the skill or keep all your repositories in one place. Clone anywhere and link it into a skill location:

git clone https://github.com/jmoredev/corubrics-skill.git ~/dev/corubrics-skill

# macOS / Linux
ln -s ~/dev/corubrics-skill ~/.pi/agent/skills/corubrics-rubric

# Windows (cmd, no administrator rights needed)
mklink /J "%USERPROFILE%\.pi\agent\skills\corubrics-rubric" "%USERPROFILE%\dev\corubrics-skill"

Pi does not require the directory name to match the skill name, so the link name is a free choice.

Register the directory in settings

If you prefer not to move or link anything, point Pi at the clone from ~/.pi/agent/settings.json (global) or .pi/settings.json (this project only):

{
  "skills": ["~/dev/corubrics-skill"]
}

In the global settings file, relative paths resolve against ~/.pi/agent; absolute paths and ~ are supported. Project-local settings load only after you trust the project folder.

Project-scoped install

To ship the skill with one course repository, clone it under .pi/skills/ or .agents/skills/ in that project, and commit it there.

One-off run, without installing

pi --skill ~/dev/corubrics-skill

--skill is repeatable. See Pi's own docs/skills.md for the full discovery rules.

Usage

1. Write the spec

{
  "titulo": "Rúbrica de ...",
  "contexto": { "marco": "FP", "modulo": "...", "resultado_aprendizaje": "RA5. ..." },
  "criterios": [
    {
      "aspecto": "Aspecto a evaluar",
      "experto": "Descriptor de nivel 4",
      "avanzado": "Descriptor de nivel 3",
      "aprendiz": "Descriptor de nivel 2",
      "novel": "Descriptor de nivel 1"
    }
  ],
  "pesos": [0.2, 0.2, 0.2, 0.2, 0.2]
}

• titulo and contexto are optional. contexto is traceability only and is never written to the sheet.
• pesos is optional. When omitted, every criterion weighs exactly 1/N (the recommended default); when supplied, the weights must be positive and sum to 1.0 within 1e-6; they are then rounded to four decimals, moving the rounding remainder to the last criterion so the written weights sum to exactly 1.0.
• Every criterion needs all five fields, and every field must be non-empty text without tabs, control characters or leading/trailing whitespace.
• A ready-to-use six-criterion FP example ships as assets/example-spec.json.

2. Audit it

python scripts/audit_rubric_spec.py --spec assets/example-spec.json

Add --json for machine-readable output. Fix every ERROR, judge every WARNING. Then judge the rubric qualitatively — see references/authoring-guide.md.

3. Build the workbook

python scripts/build_rubric_xlsx.py --spec assets/example-spec.json --out build/example.xlsx

The output path defaults to the spec path with an .xlsx suffix. The build refuses to write anything if the spec has errors, and writes the file atomically, so a failed run never damages an existing workbook.

4. Paste it into CoRubrics

1. Open the generated .xlsx.
2. On the Rúbrica sheet, select A1:F{2+N} (the header, the scores and your N criteria rows), copy.
3. In your Google Sheet, select A1 of the Rúbrica sheet and paste.
4. Delete any leftover rows below the pasted block.

Only the Rúbrica block is meant to be pasted. Sheet names and order (Rúbrica, Alumnos, Profes) and the level scores are CoRubrics-owned and are never touched.

Repository layout

Path	Contents
SKILL.md	The skill itself: activation contract, hard rules, decision gates, execution steps.
scripts/rubric_spec.py	Loads, strictly validates and normalises the spec; computes equal weights.
scripts/audit_rubric_spec.py	Heuristic audit: mechanical defects and quality warnings.
scripts/build_rubric_xlsx.py	The exporter: byte-fidelity engine over the CoRubrics template.
tests/test_rubric_skill.py	Stdlib unittest suite covering the three scripts.
references/	Decoded sheet format, FP/LOMLOE authoring guide, verified CoRubrics platform boundary.
assets/	The example spec and a byte copy of the CoRubrics template.
odd/	The author's feature document: objective, constraints, decisions and evidence.

Running the tests

python -m unittest discover -s tests -v

Verification status

Automated checks cover the spec validation and rejection paths, zip fidelity against the template, the exact sheet layout, weights, and XML escaping, including &, <, > and accents.

Not covered by automated checks, and therefore dependent on a teacher opening the file: how the workbook renders in Excel and Google Sheets, the interactive paste, and CoRubrics' own consumption of the pasted block. Descriptor cells ship with text wrapping enabled so the full descriptor stays visible.

Related documentation

• references/sheet-format.md — the exact Rúbrica layout and format rules.
• references/authoring-guide.md — writing criteria and the graduated ladder.
• references/corubrics-platform.md — the platform boundary, verified once and settled.