{"id":44380190,"url":"https://github.com/joeynyc/skillscore","last_synced_at":"2026-03-15T14:00:53.418Z","repository":{"id":337894505,"uuid":"1155710305","full_name":"joeynyc/skillscore","owner":"joeynyc","description":"CLI tool that evaluates AI agent skills and produces quality scores. Works with any SKILL.md-based skill from skills.sh, ClaHub, GitHub, or local directories.","archived":false,"fork":false,"pushed_at":"2026-02-11T20:59:03.000Z","size":3955,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-12T04:35:03.099Z","etag":null,"topics":["agent-skills","ai","claude-code","cli","evaluation","openclaw","quality-assurance","skills","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joeynyc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-11T20:20:16.000Z","updated_at":"2026-02-11T20:59:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/joeynyc/skillscore","commit_stats":null,"previous_names":["joeynyc/skillscore"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/joeynyc/skillscore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeynyc%2Fskillscore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeynyc%2Fskillscore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeynyc%2Fskillscore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeynyc%2Fskillscore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joeynyc","download_url":"https://codeload.github.com/joeynyc/skillscore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeynyc%2Fskillscore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29439597,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T07:24:13.446Z","status":"ssl_error","status_checked_at":"2026-02-14T07:23:58.969Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai","claude-code","cli","evaluation","openclaw","quality-assurance","skills","typescript"],"created_at":"2026-02-11T22:55:11.919Z","updated_at":"2026-03-15T14:00:53.380Z","avatar_url":"https://github.com/joeynyc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/banner.png\" alt=\"SkillScore\" width=\"100%\" /\u003e\n\n  \u003cbr /\u003e\n\n  [![npm version](https://badge.fury.io/js/skillscore.svg)](https://badge.fury.io/js/skillscore)\n  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n  [![Node.js CI](https://github.com/joeynyc/skillscore/workflows/Node.js%20CI/badge.svg)](https://github.com/joeynyc/skillscore/actions)\n  [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)\n\n  **The universal quality standard for AI agent skills.**\u003cbr /\u003e\n  Evaluate any SKILL.md — from [skills.sh](https://skills.sh), [ClawHub](https://clawhub.com), GitHub, or your local machine.\n\n\u003c/div\u003e\n\n---\n\n## ✨ Features\n\n- 🎯 **Comprehensive Evaluation**: 7 Anthropic-aligned scoring categories with weighted importance\n- 🎨 **Multiple Output Formats**: Terminal (colorful), JSON, and Markdown reports\n- 🔍 **Deterministic Analysis**: Reliable, reproducible scoring without requiring API keys\n- 📋 **Detailed Feedback**: Specific findings and actionable recommendations\n- ⚡ **Fast \u0026 Reliable**: Built with TypeScript for speed and reliability\n- 🌍 **Cross-Platform**: Works on Windows, macOS, and Linux\n- 🐙 **GitHub Integration**: Score skills directly from GitHub repositories\n- 📊 **Batch Mode**: Compare multiple skills with a summary table\n- 🗣️ **Verbose Mode**: See all findings, not just truncated summaries\n\n## 📦 Installation\n\n### Global Installation (Recommended)\n\n```bash\nnpm install -g skillscore\n```\n\n### Local Installation\n\n```bash\nnpm install skillscore\nnpx skillscore ./my-skill/\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/joeynyc/skillscore.git\ncd skillscore\nnpm install\nnpm run build\nnpm link\n```\n\n## 🚀 Quick Start\n\nEvaluate a skill directory:\n\n```bash\nskillscore ./my-skill/\n```\n\n## 📖 Usage Examples\n\n### Basic Usage\n\n```bash\n# Evaluate a skill\nskillscore ./skills/my-skill/\n\n# Evaluate with verbose output (shows all findings)\nskillscore ./skills/my-skill/ --verbose\n```\n\n### GitHub Integration\n\n```bash\n# Full GitHub URL (always recognized)\nskillscore https://github.com/FrancyJGLisboa/agent-skill-creator\n\n# GitHub shorthand (requires -g/--github flag)\nskillscore -g FrancyJGLisboa/agent-skill-creator\n```\n\n### Output Formats\n\n```bash\n# JSON output\nskillscore ./skills/my-skill/ --json\n\n# Markdown report\nskillscore ./skills/my-skill/ --markdown\n\n# Save to file\nskillscore ./skills/my-skill/ --output report.md\nskillscore ./skills/my-skill/ --json --output score.json\n```\n\n### Batch Mode\n\n```bash\n# Compare multiple skills (auto-enters batch mode)\nskillscore ./skill1 ./skill2 ./skill3\n\n# Explicit batch mode flag\nskillscore ./skill1 ./skill2 --batch\n\n# Compare GitHub skills\nskillscore -g user/repo1/skill1 user/repo2/skill2 --json\n```\n\n### Utility Commands\n\n```bash\n# Show version\nskillscore --version\n\n# Get help\nskillscore --help\n```\n\n## 📊 Example Output\n\n### Terminal Output\n```\n📊 SKILLSCORE EVALUATION REPORT\n============================================================\n\n📋 Skill: weather-fetcher\n   Fetches current weather data for any city when the user asks for forecasts or conditions.\n   Path: ./weather-skill\n\n🎯 OVERALL SCORE\n   A- - 92.0% (9.2/10.0 points)\n\n📝 CATEGORY BREAKDOWN\n------------------------------------------------------------\nIdentity \u0026 Metadata ████████████████████ 100.0%\n   YAML frontmatter with valid name/description, proper format, not vague\n   Score: 10/10 (weight: 20%)\n   ✓ Frontmatter name: \"weather-fetcher\" (+2)\n   ✓ Name format valid (lowercase-hyphen, ≤64 chars) (+2)\n   ✓ Frontmatter description present (+2)\n   ... 3 more findings\n\nClarity \u0026 Instructions ██████████████████░░ 90.0%\n   Workflow steps, consistent terminology, templates/examples, degrees of freedom\n   Score: 9/10 (weight: 15%)\n   ✓ Has structured workflow steps (numbered lists or checklists) (+3)\n   ✓ Consistent terminology throughout (+2)\n   ✓ 4 code blocks with templates/examples (+2)\n   ... 2 more findings (use --verbose to see all)\n\nSafety \u0026 Security ██████████████░░░░░░ 70.0%\n   No destructive commands without confirmation, no secret exfil, no privilege escalation\n   Score: 7/10 (weight: 15%)\n   ✓ No dangerous destructive commands found (+3)\n   ✓ No secret exfiltration risk detected (+2)\n   ⚠ Privilege escalation with justification: sudo (+1)\n\n📈 SUMMARY\n------------------------------------------------------------\n✅ Strengths: Identity \u0026 Metadata, Conciseness, Clarity \u0026 Instructions, Routing \u0026 Scope\n❌ Areas for improvement: Safety \u0026 Security\n\nGenerated: 3/13/2026, 1:37:51 AM\n```\n\n### Batch Mode Output\n```\n📊 BATCH SKILL EVALUATION\nEvaluating 3 skill(s)...\n\n[1/3] Processing: ./weather-skill\n✅ Completed\n\n[2/3] Processing: ./file-backup\n✅ Completed\n\n[3/3] Processing: user/repo/skill\n✅ Completed\n\n📋 COMPARISON SUMMARY\n\nSkill                          Grade  Score    Identity Routing Safety Status\nweather-fetcher                A-     92.0%    100%     100%    70%    OK\nfile-backup                    B+     87.0%    90%      80%     90%    OK\ndata-processor                 A      94.0%    100%     100%    85%    OK\n\n📈 BATCH SUMMARY\n✅ Successful: 3\n📊 Average Score: 91.0%\n```\n\n## 🏆 Scoring System\n\nSkillScore evaluates skills across **7 weighted categories** aligned with [Anthropic's official skill documentation](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills):\n\n| Category | Weight | Description |\n|----------|--------|-------------|\n| **Identity \u0026 Metadata** | 20% | YAML frontmatter name/description, lowercase-hyphen format, not vague |\n| **Conciseness** | 15% | Body ≤500 lines, progressive disclosure, no over-explaining basics |\n| **Clarity \u0026 Instructions** | 15% | Workflow steps, consistent terminology, templates/examples, degrees of freedom |\n| **Routing \u0026 Scope** | 15% | WHAT+WHEN description, negative routing, domain vocabulary, third-person voice |\n| **Robustness** | 10% | Error handling in code blocks, validation steps, dependency verification |\n| **Safety \u0026 Security** | 15% | No destructive commands, proximity-based secret exfil detection, no privilege escalation |\n| **Portability \u0026 Standards** | 10% | No platform-specific paths, MCP tool format, no time-sensitive info, relative paths |\n\n### Scoring Methodology\n\nEach category is scored from 0-10 points based on specific criteria:\n\n- **Identity \u0026 Metadata**: Validates YAML frontmatter `name` (lowercase-hyphen, ≤64 chars, no reserved words) and `description` (≤1024 chars, third person, no XML tags), rejects vague names/descriptions\n- **Conciseness**: Enforces the 500-line body limit, checks for progressive disclosure via file references, flags over-explaining basics Claude already knows\n- **Clarity \u0026 Instructions**: Checks for numbered steps or checklists, consistent terminology (no synonym pairs used interchangeably), code block examples, and a mix of imperative (\"must\") and flexible (\"consider\") guidance\n- **Routing \u0026 Scope**: Validates description has action verbs + trigger conditions, negative routing examples (\"don't use when...\"), domain-specific vocabulary, and third-person voice\n- **Robustness**: Scans code blocks for error handling (try/catch, `||`, `set -e`), validates dependency verification commands (`--version`, `command -v`), flags magic constants\n- **Safety \u0026 Security**: Proximity-based secret exfil detection (secrets + network within 5 lines), destructive command scanning with confirmation check, privilege escalation detection, unbounded loop detection\n- **Portability \u0026 Standards**: Flags Windows-style paths, hardcoded absolute paths, validates MCP tool `ServerName:tool_name` format, detects time-sensitive info (dates, pinned versions)\n\n### v2.0.0: Anthropic-Aligned Rubric\n\nComplete scoring redesign replacing the original 8 generic categories with 7 categories aligned to Anthropic's official skill documentation:\n\n| Change | Details |\n|--------|---------|\n| **Frontmatter validation** | Skills must have YAML frontmatter with `name` and `description` fields |\n| **Name format checks** | Names must be lowercase-hyphen (`^[a-z0-9][a-z0-9-]*$`), ≤64 chars, no reserved words |\n| **Conciseness scoring** | New category enforcing 500-line limit, progressive disclosure, no over-explaining |\n| **Third-person detection** | Descriptions should use third-person voice, not \"I/We/My\" |\n| **Proximity-based exfil** | Secret + network pattern detection within 5-line proximity windows |\n| **MCP format validation** | MCP tool references must use `ServerName:tool_name` format |\n| **Time-sensitive detection** | Flags specific dates, \"as of\", and pinned version references |\n\n### Grade Scale\n\n| Grade | Score Range | Description |\n|-------|-------------|-------------|\n| **A+** | 97-100% | Exceptional quality |\n| **A** | 93-96% | Excellent |\n| **A-** | 90-92% | Very good |\n| **B+** | 87-89% | Good |\n| **B** | 83-86% | Above average |\n| **B-** | 80-82% | Satisfactory |\n| **C+** | 77-79% | Acceptable |\n| **C** | 73-76% | Fair |\n| **C-** | 70-72% | Needs improvement |\n| **D+** | 67-69% | Poor |\n| **D** | 65-66% | Very poor |\n| **D-** | 60-64% | Failing |\n| **F** | 0-59% | Unacceptable |\n\n## 📁 What Makes a Good Skill?\n\n### Required Structure\n\n```\nmy-skill/\n├── SKILL.md           # Main skill definition (REQUIRED)\n├── README.md          # Documentation (recommended)\n├── package.json       # Dependencies (if applicable)\n├── scripts/           # Executable scripts\n│   ├── setup.sh\n│   └── main.py\n└── examples/          # Usage examples\n    └── example.md\n```\n\n### SKILL.md Template\n\n```markdown\n---\nname: my-awesome-skill\ndescription: Performs [specific task] when the user needs to [trigger condition].\n---\n\n# My Awesome Skill\n\nPerforms [specific task] using [specific tools/inputs].\n\n## When to Use\n\nUse this skill when you need to [specific task] with [specific tools/inputs].\n\n## When NOT to Use\n\nDon't use this skill when:\n- The task is [alternative scenario] — use [other skill] instead\n- You need [different capability]\n\n## Dependencies\n\n- Tool 1: Installation instructions (`tool --version` to verify)\n- API Key: How to obtain and configure\n- Environment: OS requirements\n\n## Workflow\n\n1. Step-by-step instructions\n2. Specific commands to run\n3. Expected outputs\n\n- [ ] Verify dependencies\n- [ ] Confirm configuration\n\n## Output\n\nResults are written to `./output/` as JSON files.\n\n## Error Handling\n\nYou must always validate output. Consider retrying on transient failures.\n\n```bash\nif ! result=$(./scripts/main.py --input \"data\"); then\n  echo \"Error: processing failed\"\n  exit 1\nfi\n```\n\n## Examples\n\n### Example Output\n\n```json\n{\n  \"status\": \"success\",\n  \"result\": \"Example of what the skill produces\"\n}\n```\n\n## Limitations\n\n- Known constraints\n- Platform-specific notes\n- Edge cases\n\nSee [docs/advanced.md](docs/advanced.md) for more details.\n```\n\n## 🔧 API Usage\n\nUse SkillScore programmatically in your Node.js projects:\n\n```typescript\nimport { SkillParser, SkillScorer, TerminalReporter } from 'skillscore';\nimport type { Reporter, SkillScore } from 'skillscore';\n\nconst parser = new SkillParser();\nconst scorer = new SkillScorer();\nconst reporter: Reporter = new TerminalReporter();\n\nasync function evaluateSkill(skillPath: string): Promise\u003cSkillScore\u003e {\n  const skill = await parser.parseSkill(skillPath);\n  const score = await scorer.scoreSkill(skill);\n  const report = reporter.generateReport(score);\n\n  console.log(report);\n  return score;\n}\n```\n\nAll three reporters (`TerminalReporter`, `JsonReporter`, `MarkdownReporter`) implement the `Reporter` interface.\n\n### ParsedSkill Fields (v2.0)\n\nThe parser now extracts additional metadata used by the new scoring rubric:\n\n```typescript\ninterface ParsedSkill {\n  // Existing fields\n  skillPath: string;\n  skillMdExists: boolean;\n  skillMdContent: string;\n  name: string;\n  description: string;\n  files: string[];\n  metadata: Record\u003cstring, unknown\u003e;\n  structure: FileStructure;\n\n  // New in v2.0\n  frontmatter: Record\u003cstring, unknown\u003e;    // YAML frontmatter (same ref as metadata)\n  bodyContent: string;                      // SKILL.md after stripping frontmatter\n  bodyLineCount: number;                    // Line count of body\n  nameSource: 'frontmatter' | 'heading' | 'fallback';\n  descriptionSource: 'frontmatter' | 'inline' | 'inferred' | 'none';\n  referencedFiles: string[];               // Markdown links extracted from SKILL.md\n}\n```\n\n## 🛠️ CLI Options\n\n```\nUsage: skillscore [options] \u003cpath...\u003e\n\nArguments:\n  path                   Path(s) to skill directory, GitHub URL, or shorthand\n\nOptions:\n  -V, --version         Output the version number\n  -j, --json            Output in JSON format\n  -m, --markdown        Output in Markdown format\n  -o, --output \u003cfile\u003e   Write output to file\n  -v, --verbose         Show ALL findings (not just truncated)\n  -b, --batch           Batch mode for comparing multiple skills\n  -g, --github          Treat shorthand paths as GitHub repos (user/repo/path)\n  -h, --help           Display help for command\n```\n\n## 🧪 Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests in watch mode\nnpm test\n\n# Run tests once\nnpm run test:run\n\n# Lint code\nnpm run lint\n\n# Build project\nnpm run build\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### Development Setup\n\n```bash\ngit clone https://github.com/joeynyc/skillscore.git\ncd skillscore\nnpm install\nnpm run build\nnpm link\n\n# Run in development mode\nnpm run dev ./test-skill/\n\n# Build for production\nnpm run build\n```\n\n### Running Tests\n\n```bash\nnpm test\n```\n\n### Submitting Changes\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass (`npm test`)\n6. Lint your code (`npm run lint`)\n7. Commit your changes (`git commit -m 'Add amazing feature'`)\n8. Push to the branch (`git push origin feature/amazing-feature`)\n9. Open a Pull Request\n\n### Coding Standards\n\n- Use TypeScript for all new code\n- Follow existing code style (enforced by ESLint)\n- Add tests for new features\n- Update documentation for API changes\n- Keep commits focused and descriptive\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Error: \"Path does not exist\"**\n- Check for typos in the path\n- Ensure you have permission to read the directory\n- Verify the path points to a directory, not a file\n\n**Error: \"No SKILL.md file found\"**\n- Skills must contain a SKILL.md file\n- Check if you're pointing to the right directory\n- The file must be named exactly \"SKILL.md\"\n\n**Error: \"Git is not available\"**\n- Install Git to clone GitHub repositories\n- macOS: `xcode-select --install`\n- Ubuntu: `sudo apt-get install git`\n- Windows: Download from git-scm.com\n\n**Scores seem too high/low**\n- Scoring is calibrated against real-world skills\n- See the scoring methodology above\n- Consider the specific criteria for each category\n\n### Getting Help\n\n- 🐛 [Report Issues](https://github.com/joeynyc/skillscore/issues)\n- 💬 [Discussions](https://github.com/joeynyc/skillscore/discussions)\n- 📚 [Documentation](https://github.com/joeynyc/skillscore/wiki)\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Inspired by the need for quality assessment in AI agent skills\n- Built for the OpenClaw and Claude Code communities\n- Thanks to all contributors and skill creators\n- Scoring methodology aligned with [Anthropic's official skill documentation](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills)\n\n## 📊 Example Scores\n\nReal-world skills scored with SkillScore v2.0:\n\n- **FrancyJGLisboa/agent-skill-creator**: 83.5% (B) - Perfect identity \u0026 robustness, needs negative routing and trimming (617 lines)\n- **gapmiss/obsidian-plugin-skill**: 52% (F) - No frontmatter, weak routing signals, missing structured workflow\n- **skill-creator** (local): 86% (B) - Strong identity \u0026 conciseness (353 lines, 6 file refs), needs error handling in code blocks\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cstrong\u003eMade with ❤️ for the AI agent community\u003c/strong\u003e\u003cbr\u003e\n  \u003csmall\u003eHelp us improve AI agent skills, one evaluation at a time\u003c/small\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoeynyc%2Fskillscore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoeynyc%2Fskillscore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoeynyc%2Fskillscore/lists"}