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:
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
LiqunChen0606