Skill Creator

# Skill Authoring Example

version: "1"

defaults:
  agent: claude
  provider: local
  trials: 3
  timeout: 300
  threshold: 0.8

tasks:
  - name: fix-skill-draft
    agent: claude
    instruction: |
      Rewrite the existing `draft/SKILL.md` file in place so it follows the skill authoring standard.

      Keep the file lean and production-ready while preserving the draft's purpose.
      Requirements:
      - Use YAML frontmatter at the top of the file.
      - Include a non-empty `name`.
      - Include a non-empty `description`.
      - Include a clear "When to Use This Skill" section.
      - Include an "Error Handling" section.

    workspace:
      - src: fixtures/broken-skill/SKILL.md
        dest: draft/SKILL.md

    graders:
      - type: deterministic
        run: node graders/check-skill.js
        weight: 1

import { readFileSync } from 'node:fs';

let skill = '';
try {
  skill = readFileSync('draft/SKILL.md', 'utf8');
} catch (error) {
  console.log(JSON.stringify({
    status: 'failure',
    reason: 'missing input file',
    file: 'draft/SKILL.md',
    details: error instanceof Error ? error.message : String(error),
    score: 0,
    checks: [
      { name: 'input-file', passed: false, message: 'Missing or unreadable draft/SKILL.md' },
    ],
  }));
  process.exit(1);
}

const checks = [];
let passed = 0;

function addCheck(name, condition, message) {
  checks.push({ name, passed: condition, message: condition ? 'OK' : message });
  if (condition) passed += 1;
}

const frontmatterMatch = skill.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
const frontmatter = frontmatterMatch?.[1] ?? '';

addCheck('frontmatter', Boolean(frontmatterMatch), 'Missing YAML frontmatter at the top of the file');
addCheck('name', /^name:\s*\S.+$/m.test(frontmatter), 'name missing');
addCheck('description', /^description:\s*\S.+$/m.test(frontmatter), 'description missing');
addCheck('usage', /## When to Use This Skill/.test(skill), 'Missing usage section');
addCheck('error-handling', /## Error Handling/.test(skill), 'Missing error handling section');

const score = (passed / checks.length).toFixed(2);
console.log(JSON.stringify({
  score: Number(score),
  details: `${passed}/${checks.length} checks passed`,
  checks,
}));

{
  "version": "1.0.0",
  "organization": "Capgo",
  "date": "March 2026",
  "abstract": "Guide for authoring high-quality agent skills with lean instructions, progressive disclosure, and skillgrade validation.",
  "triggers": [
    "create a skill",
    "skill authoring",
    "agent skill best practices",
    "validate a skill",
    "skillgrade"
  ],
  "references": [
    "https://agentskills.io",
    "https://github.com/mgechev/skillgrade"
  ]
}