skillforge

SkillForge

The quality layer for SKILL.md — lint, sign, test your Agent Skills

SkillForge is eslint / rubocop for AI skill files. Catch missing sections, empty steps, malformed metadata, prompt-injection patterns, and broken references before you deploy the skill. Sign skills with Ed25519 so consumers can detect tampering. Test skill compliance in CI with a JUnit report.

---

60-second quick start

pip install aif-skillforge
aif check SKILL.md       # lint + security scan
aif score SKILL.md       # letter grade (A+..F) with shareable badge

That's it. Output:

SkillForge Quality Check: SKILL.md
============================================================
  [+] Parsed SKILL.md (1 skill block)
  [+] Skill: code-review v1.0
  [+] Lint: 7/7 checks passed
  [+] Document lint: 10/10 checks passed
------------------------------------------------------------
PASS — SKILL.md is clean

What it checks

7 structural lint checks — the things a reviewer would reject:

Check	Catches
Frontmatter	Missing name or description
RequiredSections	No @step or @verify block — skill is aspirational
DescriptionLength	Description > 1024 chars (won't fit in context routing)
NameFormat	Invalid chars in skill name
NoEmptyBlocks	Placeholder steps / verify blocks that were never filled in
BlockTypes	Non-skill content mixed into the skill block
VersionHash	Hash doesn't match content (tampered, or stale)

6 security checks (OWASP Agentic Skills Top 10 aligned):

Rule	Catches
prompt-injection	"Ignore previous instructions" patterns
hidden-unicode	Zero-width characters, direction overrides
dangerous-tool	eval, exec, rm -rf, unrestricted shell
external-fetch	curl url | bash style remote execution
privilege-escalation	sudo, admin requests, role manipulation
data-exfiltration	Credential-harvesting patterns

Run aif scan SKILL.md for security-only output.

Grade your skill with a shareable badge

aif score my-skill.md

Output:

SkillForge Score: my-skill.md
============================================================
  Score:  100/100  (A+)
  Lint:   0 errors, 0 warnings
  Security: 0 critical, 0 high, 0 medium, 0 low
------------------------------------------------------------
Grade: A+

Add a badge to your skill's README:

# Generate a Shields.io endpoint file, commit it to your repo
aif score my-skill.md --format shields -o badge.json
git add badge.json && git commit -m "add skillforge badge"

Then in your README:

![SkillForge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/USER/REPO/main/badge.json)

The badge auto-updates when you re-run aif score and re-commit the JSON. Grade mapping: A+ (97-100), A (93-96), A- (90-92), B+ (87-89), B (83-86), B- (80-82), C+ (77-79), C (73-76), C- (70-72), D (60-69), F (<60). An A+ means all 10 lint checks pass and zero security findings; an F means a critical security finding or multiple lint errors.

Also available: --format svg for a standalone SVG badge, --format json for CI integration, and --min-grade C to fail the command if the grade drops below a threshold.

Install it once, run it everywhere

Pre-commit hook

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/LiqunChen0606/skillforge
    rev: v0.6.4
    hooks:
      - id: aif-check

Now every commit that touches SKILL.md or *.aif gets linted automatically.

GitHub Actions

.github/workflows/skill-lint.yml:

on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: LiqunChen0606/[email protected]
        with:
          path: ./skills

PRs that break skill quality fail CI before merge.

Claude Code plugin

Add to your ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "skillforge-marketplace": {
      "source": {
        "source": "url",
        "url": "https://github.com/LiqunChen0606/skillforge.git"
      }
    }
  },
  "enabledPlugins": {
    "skillforge@skillforge-marketplace": true
  }
}

Or via slash commands (if your Claude Code version supports them):

/plugin marketplace add LiqunChen0606/skillforge
/plugin install skillforge@skillforge-marketplace

Then from any Claude Code session:

/lint-skill my-skill.md
/scan-skill my-skill.md
/sign-skill my-skill.md
/verify-skill my-skill.md

Autofix