The quality layer for SKILL.md — lint, sign, test your Agent Skills
SkillForge is
eslint/rubocopfor 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.
pip install aif-skillforge
aif check SKILL.md # lint + security scan
aif score SKILL.md # letter grade (A+..F) with shareable badgeThat'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
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.
aif score my-skill.mdOutput:
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.
Add to .pre-commit-config.yaml:
repos:
- repo: https://github.com/LiqunChen0606/skillforge
rev: v0.6.4
hooks:
- id: aif-checkNow every commit that touches SKILL.md or *.aif gets linted automatically.
.github/workflows/skill-lint.yml:
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: LiqunChen0606/skillforge@v0.6.4
with:
path: ./skillsPRs that break skill quality fail CI before merge.
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
aif fix SKILL.md --write # fix and overwrite the file
aif fix SKILL.md --check # dry-run: show what would change, exit 1 if fixes needed
aif fix SKILL.md --diff # print unified diff of proposed fixesFixes: NameFormat (kebab-case), missing frontmatter (scaffold name/description), DescriptionLength (truncate), RequiredSections (add stub ## Steps / ## Verification), NoEmptyBlocks (insert TODO placeholders).
Add to your claude_desktop_config.json:
{
"mcpServers": {
"skillforge": {
"command": "aif",
"args": ["mcp-server"]
}
}
}Exposes 4 tools: check_skill, score_skill, scan_skill, fix_skill. Any MCP-compatible client can invoke them natively during a conversation.
Weekly scan of public SKILL.md files on GitHub, graded by aif score, ranked top 25. Any public repo with a SKILL.md is automatically included.
When you publish a skill, sign it. Consumers verify.
aif skill keygen # Generate Ed25519 keypair (one time)
aif skill sign my-skill.aif --key ~/.aif/private.key # Sign
aif skill verify-signature my-skill.aif \
--signature <sig> --pubkey ~/.aif/public.keyAny byte change to the skill file invalidates the signature. Useful when skills come from untrusted marketplaces.
aif skill test my-skill.aif --format junit -o test-results.xmlEmits standard JUnit XML that GitHub Actions, Jenkins, CircleCI, etc. all display natively. Add --baseline baseline.json to catch regressions vs. a saved baseline.
import skillforge
# Lint
results = skillforge.lint(open("my-skill.aif").read())
# Security scan
findings = skillforge.scan(open("my-skill.aif").read())
# Sign / verify
priv, pub = skillforge.generate_keypair()
sig = skillforge.sign_skill(open("my-skill.aif").read(), priv)Full walkthrough: tutorial/skillforge_tutorial.ipynb.
- Not a skill runtime — it lints and signs, it doesn't execute skills
- Not an LLM framework — pairs with Claude Code, Cursor, any SKILL.md consumer
- Not a replacement for SKILL.md — works directly on your existing Markdown files
The Agent Skills standard is adopted by 30+ platforms, and skills are proliferating fast. Nobody has linting, signing, or CI for them. A broken skill doesn't throw errors — it just quietly makes your agent behave wrong. SkillForge fixes that.
SkillForge is built on AIF (AI-native Interchange Format), a typed semantic IR for documents. The quality tools above are the production-ready surface. The underlying format has additional capabilities documented separately:
- AIF document format — typed blocks (
@claim,@evidence,@step,@red_flag), HTML/PDF/Markdown import, LML output modes for LLM consumption - Skill execution benchmark — measures whether typed formats improve LLM compliance (spoiler: +4pp overall on 126 runs, claude-opus-4-6)
- Token comparison benchmark — honest size comparison across raw HTML, cleaned text, Markdown, AIF LML (10 Wikipedia articles)
- Roundtrip tutorial — HTML/Markdown/PDF → AIF → format with fidelity checks on live Wikipedia data
These are research / power-user capabilities. The 60-second quick start above is the supported path.
Dual-licensed under Apache 2.0 OR MIT.
Issues and PRs welcome. If you're using SkillForge in production, a star on GitHub helps. If something's broken, file an issue — single-author project, fast turnaround.