Repo-native rubrics and linters for portable agent workflows.

AI coding agents produce better results with well-structured skills and AGENTS.md. skills gives you rubric-graded writing and review workflows that turn rough prompts into professional-grade skill definitions, with validation, iterative critic feedback, and cross-platform portability across Claude Code, OpenAI Codex CLI, Cursor, Windsurf, and CI.

Includes:

• Installable skills (this repo) — writing + review workflows for skill directories and agent context files
• @jkeskikangas/skillcheck — a linter/validator you can run in CI or locally

Agentic software development fails in predictable, expensive ways:

• Instruction drift — a “helpful” agent invents repo commands, ignores conventions, or uses the wrong build/test workflow.
• Context collapse — critical constraints live in someone’s head (or a chat log), not in the repo where the agent can reliably find them.
• Non-portability — a prompt/skill works in one tool, then breaks when you switch (Codex ↔ Claude ↔ Cursor ↔ CI).
• Unreviewable artifacts — skills that look plausible but can’t be validated, graded, or improved systematically.

This repo treats agent behavior as an engineering surface you can spec, lint, review, and ship:

• AGENTS.md is the repo’s operating manual for humans and agents (what to run, how to stay safe, how to escalate).
• A skill directory is a capability package (trigger → steps → constraints → references), not a loose prompt snippet.
• Rubrics + linters make quality repeatable, not vibe-based.

Install a reviewer skill into your agent (via the skills.sh CLI):

npx skills add jkeskikangas/skills@latest -s reviewing-skills

Then, in your agent, run reviewing-skills on your skill folder to get a grade + prioritized fixes.

You prompt: “Review my skill and tell me if it’s good.”

You get (via skills/reviewing-skills/SKILL.md):

Grade: C (2.8 / 5.0) — ITERATE

  Dimension              Score  Weight
  ─────────────────────  ─────  ──────
  Spec compliance        3.0    30%
  Clarity & structure    2.5    25%
  Robustness             3.0    20%
  Token efficiency       2.5    15%
  Portability            3.5    10%

P1  missing-validation  SKILL.md references scripts/validate.sh but file
    does not exist.
    Fix: create scripts/validate.sh or remove the reference.

P2  vague-trigger       "Use this skill when appropriate" — does not help
    the agent decide when to activate.
    Fix: replace with concrete trigger conditions.

Apply the fixes, re-run — score jumps to 4.6 / 5.0 (Grade A, PASS).

Install the skills into your agent using the skills.sh CLI:

npx skills add jkeskikangas/skills@latest

For reproducible installs, pin to a version tag:

npx skills add jkeskikangas/skills@v0.2.3

See CHANGELOG.md for release notes. Each release also creates a corresponding git tag.

• --all: install all skills to all detected agents
• -s <skill>: select a single skill
• -a <agent>: select a single agent

npx skills add jkeskikangas/skills@latest --all
npx skills add jkeskikangas/skills@latest -s writing-skills -a claude-code

After running skills add, you should see skill directories in your agent’s skills folder (exact path depends on the agent). Common locations:

• ~/.claude/skills/ (Claude Code)
• ~/.codex/skills/ (OpenAI Codex CLI)

Quick success check:

ls ~/.claude/skills/writing-skills/SKILL.md
# or
ls ~/.codex/skills/writing-skills/SKILL.md

Windows PowerShell equivalent:

Test-Path "$HOME\.claude\skills\writing-skills\SKILL.md"

Then invoke one of the installed skills in your agent (example: $reviewing-skills).

Clone the repo and copy skill directories into your agent’s skills path:

git clone https://github.com/jkeskikangas/skills.git
cp -r skills/writing-skills ~/.claude/skills/writing-skills

• You’re starting from scratch → writing-skills
• You already have a skill and want it to pass spec + portability checks → reviewing-skills
• Your repo needs reliable agent context → writing-agents-md
• You want a new grading rubric or to refine one → writing-rubrics

Each writing skill follows a generator → validate → two-phase quality gate loop:

1. Write — generate the artifact (SKILL.md, AGENTS.md, rubric)
2. Validate — run linters (skillcheck, agnix)
3. Quality gate — self-critic review, then a fresh-context subagent re-grade
4. Fix + repeat — apply P1/P2 findings and re-validate (≤ 3 loops; stop when score ≥ 4.5 and no P1s)

If you only do one review pass, you mostly catch “typos while you still remember what you meant”. The second pass is different: it asks “does this stand alone when run by a fresh agent with no extra context?”

That’s the production condition for skills. Most costly failures happen when:

• A skill implicitly relies on unstated repo conventions.
• The agent follows the steps but misses a hidden constraint (safety, token limits, tool scope, platform differences).
• A rubric sounds reasonable but grades inconsistently (drift).

The two-phase gate is a low-cost way to surface these issues before they become multi-hour debugging sessions or risky changes.

From the repo root:

npx @jkeskikangas/skillcheck skills/
npx agnix skills/

In scope:

• Writing + reviewing agent skill definitions (SKILL.md + supporting resources)
• Writing + reviewing rubrics used by those skills
• Writing + reviewing AGENTS.md project context files
• Validation scripts for structural correctness

Non-goals:

• Agent runtime or execution framework
• Prompt library / prompt template collection
• IDE plugin or editor extension
• Package manager / dependency management for skills

• Works on macOS, Linux, and Windows (requires Node.js 18+).
• No native dependencies; intended to run anywhere Node runs.
• CI validates on Ubuntu/macOS/Windows across Node 18/20/22.

This project uses semantic versioning. Skill schema changes are tracked in skills/writing-agents-md/references/schema-changelog.md.

• Major: breaking changes to skill schema or validation scripts
• Minor: new skills, new validation checks, new rubric dimensions
• Patch: documentation fixes, rubric wording, non-breaking script fixes

• schemas/skill-frontmatter.schema.json — SKILL.md YAML frontmatter
• schemas/lint-output.schema.json — skillcheck --format json output

• I installed but don’t see the skill. Re-run with explicit selection (skill + agent), then verify the target agent’s skills folder:
  • npx skills add jkeskikangas/skills@latest -s writing-skills -a claude-code
• My agent doesn’t pick up the skill. Confirm the skill’s SKILL.md is in the agent’s configured skills path and restart the agent/extension.
• I want to contribute. Start with CONTRIBUTING.md. Security issues: see SECURITY.md.

• Star the repo to signal demand.
• Share with teams standardizing agent workflows (Codex/Claude/Cursor/Windsurf).

• promptfoo — great for prompt/agent/RAG evaluation + regression testing; skills focuses on portable, rubric-graded skill authoring + structural validation.
• LangSmith — full LLMOps platform (tracing, evals, prompt iteration); skills stays lightweight and repo-native without a backend.
• Awesome ChatGPT Prompts — large community prompt library; typically unscored/unvalidated; skills adds schemas, linters, and rubrics for repeatable quality.

Apache-2.0 — see LICENSE for details.