Skip to main content
SkillForge Logo

SkillForge

Universal package manager, security auditor, and context token profiler for portable AI agent skills (SKILL.md).

PyPI version Python versions CI License: MIT Audited by SkillForge HOL Guard

Audit, package, test, and profile portable agent skills across Claude Code, Cursor, Google Antigravity, Gemini CLI, Codex CLI, OpenCode, Windsurf, GitHub Copilot, Cline, and Roo Code.


Quickstart

Run commands directly without installing using uvx or pipx:

# 1. Check workspace health, token load, and installed skills
uvx agent-skillforge doctor

# 2. Audit a skill directory for prompt injections and malicious patterns
uvx agent-skillforge audit ./skills/my-skill

# 3. Profile token cost: startup pointer cost vs on-demand body cost
uvx agent-skillforge budget

# 4. Generate an official verified security badge
uvx agent-skillforge badge ./skills/my-skill

Or install permanently with pip:

pip install agent-skillforge

Why SkillForge

As AI coding assistants adopt the open SKILL.md format, two practical problems appear in day-to-day use:

  1. Supply-chain security: Community skills are plain executable instructions. Unreviewed skills can contain prompt injections, invisible zero-width unicode characters, or exfiltrate local credentials (~/.ssh, ~/.aws/credentials).
  2. Context token burn: Skills load description text into the model prompt on every turn. Unoptimized skills waste hundreds of tokens before the agent starts thinking, increasing API costs and reducing reasoning quality.
Capability Manual Copy-Paste General Skill CLIs SkillForge
Runtime None Node.js / npm Python 3.11+ (pip / uvx)
Offline Security Audit No No 100% Local Pattern, AST & Sandbox Scanner
Prompt Injection Check No No Built-in (SEC-002)
Deceptive Installer Check No No Built-in (SEC-010)
Executable-in-Assets Check No No Built-in (SEC-011)
Allowed-Tools Enforcer No No Built-in (SEC-012)
Memory & Hook Poisoning No No Built-in (SEC-013, OWASP ASI06)
Lethal Trifecta Analysis No No Built-in (SEC-014, OWASP AST10)
Obfuscation & Hex Payloads No No Built-in (SEC-015, Cisco obfuscation)
Resource Abuse & Fork Bombs No No Built-in (SEC-016, Cisco resource_abuse)
Unpinned Package Installs No No Built-in (SEC-017, Cisco supply_chain)
MCP Configuration Auditor No No Built-in (skillforge audit-mcp)
Hidden Unicode / Bidi Scans No No Built-in (SEC-001)
Python AST & Sandbox Harness No No Built-in (SEC-008, audit --sandbox)
Link Phishing / Spoofing No No Built-in (SEC-007)
Context Token Profiler No No Built-in (skillforge budget)
Context File Linter No No Built-in (skillforge lint-context)
Trigger Eval Testing No No Built-in (skillforge test)
Context Budget Optimizer No No Built-in (skillforge optimize)
OpenAPI / Swagger Importer No No Built-in (skillforge import-openapi)
OASIS SARIF v2.1.0 Export No No Built-in (--sarif for Code Scanning)
Reproducible Lockfile No Manifest only SHA-256 + Pinned Git Commit SHA
Cryptographic Attestation No No HMAC-SHA256 & Ed25519 (sign, verify-signature)
Language Server (LSP) No No Built-in (skillforge lsp stdio daemon)
Remote Registry & Crawler No Partial Built-in (skillforge search-remote, index)
Terminal Dashboard (TUI) No No Built-in (skillforge tui via Rich)
MCP Runtime Security Firewall No No Built-in (firewall-mcp, --wrap-config)
Multi-Model Trigger Benchmark No No Built-in (skillforge bench)
Progressive Disclosure Slicer No No Built-in (skillforge refactor-progressive)
Zero-Trust Script Jail Runner No No Python/Bash/Node + bwrap OS jail (run-sandboxed)
CycloneDX 1.6 AIBOM & SPDX Generator No No Built-in (skillforge sbom)
SLSA v1.0 Provenance Attestation No No HMAC-SHA256 & Ed25519 (provenance, verify-provenance)
Skill Dependency Graph & Topological Resolver No No Built-in (skillforge graph)
Universal Context Rule Synchronizer No No Built-in (skillforge sync-rules, incl. Gemini & Copilot)
Policy-as-Code & Expiring Suppressions No Partial Built-in (skillforge policy, audit --policy)
MCP Tool Poisoning & Cross-Server Sweep No Partial Built-in (MCP-005 to MCP-007, scan-all)
Lifecycle Updates & Lockfile Interop No Partial Built-in (check, update, migrate-lock)
Local Offline Usage Telemetry Ledger No Telemetry Built-in (skillforge telemetry, DO_NOT_TRACK)
Native MCP Server & Agent Plugins 1.0 No Partial **Built-in (`serve-mcp --transport stdio
Supported Assistants Manual Single target Claude, Cursor, Antigravity, Gemini CLI, Codex CLI, OpenCode, Windsurf, Cline, Roo Code, Copilot

Workflows

1. Diagnose your workspace (doctor)

Inspect all installed skills across your project or global directories (Claude Code, Cursor, Antigravity, Windsurf, Cline) for security issues, token load, and broken pointers:

# Diagnose active project
skillforge doctor

# Diagnose global user configuration
skillforge doctor --global
SkillForge Doctor Diagnostic (Project: 4 skills)
  Health Status:        PASSED (All Healthy)
  Startup Context Load: ~340 tokens (Every turn discovery cost)
  On-Demand Body Cost:  ~2180 tokens
  Security Findings:    0 Critical, 0 High, 0 Total

2. Audit skills before running them (audit)

Scan an individual skill, a directory of skills, or the entire repository for prompt injections, AST taint flows, hidden payloads, and broken pointers:

# Audit an individual skill
skillforge audit ./skills/my-new-skill

# Execute bundled Python scripts in an isolated offline sandbox harness
skillforge audit ./skills/my-new-skill --sandbox

# Audit an entire collection directory or project root
skillforge audit ./skills
skillforge audit .
Audit Report: my-new-skill
Status: PASSED (Score: 100/100)
Context Load: 60 pointer tokens | 520 body tokens (27 lines)
Total Findings: 0

The auditor checks for:

  • Invisible & Bidi Unicode (SEC-001): Zero-width spaces (\u200B, \uFEFF), homoglyphs, and bidirectional control characters (\u202E, \u2066) used to conceal prompt instructions or alter execution order.
  • Prompt Injections (SEC-002): Directives like "ignore previous instructions", "system override", or attempts to bypass safety guards. Quoted defensive examples are flagged as MEDIUM, while imperative commands remain CRITICAL.
  • Dangerous Shell Commands (SEC-003): Patterns like curl ... | bash, base64-decoded execution, and suspicious outbound transmission.
  • Credential Path Access (SEC-004): Unauthorized access to ~/.ssh, ~/.aws/credentials, or local environment files.
  • Exfiltration Endpoints (SEC-005): Outbound transmission to capture services (webhook.site, pipedream.net, requestbin.net) or environment variable exfiltration.
  • Hardcoded Secrets (SEC-006): Embedded API keys and provider tokens (ghp_, github_pat_, sk-ant-, AIzaSy, AKIA).
  • Markdown Link Spoofing (SEC-007): Mismatched visible URL hostnames and target URL destinations hiding deceptive redirects.
  • Python AST, Taint & Sandbox Analysis (SEC-008): Structural AST inspection of bundled Python scripts for eval(), exec(), subprocess(..., shell=True), pickle.loads(), environment-to-network taint flows, plus optional runtime isolation via --sandbox (blocking outbound sockets and subprocess creation while monitoring canary secrets).
  • Unrestricted Tool Scope (SEC-009): Wildcard tool permissions (*, Bash(*)) in allowed-tools frontmatter.
  • Markdown-as-Installer Detection (SEC-010): Deceptive copy-paste terminal pipelines (curl | bash, irm | iex) disguised as setup instructions.
  • Executable Payload in Assets (SEC-011): Native binaries (PE, ELF, Mach-O) or scripts concealed inside assets/.
  • Allowed-Tools Scope Enforcer (SEC-012): Flags shell execution blocks or bundled scripts when frontmatter allowed-tools excludes command execution.
  • Persistent Memory & Git Hook Poisoning (SEC-013): Detects shell append/redirection operations (>>, >, tee -a) targeting CLAUDE.md, AGENTS.md, MEMORY.md, .cursorrules, .windsurfrules, or .git/hooks/* (OWASP ASI06).
  • Lethal Trifecta Compound Risk (SEC-014): Flags packages combining private credential/env access, untrusted remote content ingestion, and external network egress (OWASP AST10).
  • Obfuscated Payloads & Encoded Wrappers (SEC-015): Detects base64 pipelines to shell, python b64decode eval wrappers, powershell encoded commands, and dense hex-escape sequences.
  • Destructive Resource Abuse & Fork Bombs (SEC-016): Identifies bash fork bombs (:(){ :|:& };:), disk exhaustion (dd if=/dev/urandom), and raw block device overwrites (mkfs, > /dev/sd*).
  • Unpinned Runtime Package Installs (SEC-017): Detects runtime package installations (pip install, npm install -g) without pinned versions or lockfiles.
  • Trigger Quality (QUAL-001): Ensures descriptions specify concrete activation conditions.
  • Directory Alignment (QUAL-002): Ensures folder name matches the frontmatter name.
  • Progressive Disclosure Budget (QUAL-003): Flags SKILL.md bodies exceeding 500 lines or ~5,000 tokens so secondary reference material is moved to references/.
  • Broken Disclosure Pointers (QUAL-004): Checks that cited references/... and scripts/... files exist on disk.
  • Applicability Hijacking (QUAL-006): Flags overbroad trigger descriptions claiming all tasks.

For CI pipelines, pass --strict to fail on warnings, --json for automation, or --sarif for GitHub Code Scanning:

# Audit an individual skill
skillforge audit ./skills/my-new-skill --sarif results.sarif

# Or audit the entire workspace
skillforge audit . --sarif results.sarif

3. Audit Model Context Protocol configurations (audit-mcp)

Inspect client MCP configuration files (mcp.json, claude_desktop_config.json, .gemini/settings.json) for hardcoded secrets, shell wrappers, unpinned packages, and overbroad root directory grants:

# Audit default mcp.json
skillforge audit-mcp

# Audit an explicit client configuration
skillforge audit-mcp ./mcp.json --strict
Audit Report: mcp.json
Status: PASSED (Score: 100/100)
Total Findings: 0

4. Profile startup token load (budget)

Model-invoked skills keep their name and description in the prompt on every turn. Measure how many tokens your skills consume before triggering:

skillforge budget
# Inspect built-in catalog:
skillforge budget --builtin
Context Budget Profile (37 skills)
  Always-Loaded Startup Pointer Cost: ~2286 tokens
  On-Demand SKILL.md Body Cost:       ~14357 tokens
  Disclosed Resources Cost:           ~3947 tokens

5. Test trigger accuracy with eval suites (test)

Verify that your skill description triggers on relevant user requests, ignores unrelated prompts, and satisfies keyword constraints:

# Generate a starter evals/evals.json test suite
skillforge test ./skills/my-skill --init

# Run test cases
skillforge test ./skills/my-skill
Running evals for 'my-skill' (4 test cases)...
  [PASS] trigger_positive_core_my_skill: "Please help me with my-skill following our workflow."
  [PASS] trigger_positive_task: "I need to execute a task: my skill workflow description"
  [PASS] suppress_negative_unrelated_math: "Calculate the Fibonacci sequence for n=30 in Python."
  [PASS] suppress_negative_greeting: "Hello there, what is the weather like in Tokyo today?"

Result: PASSED (4/4 passed)

Use --json in CI to ensure changes to description do not break activation behavior.

6. Optimize bloated skills with progressive disclosure (optimize)

When a skill exceeds the 500-line or 5,000-token limit (QUAL-003), extract secondary guides into references/ while keeping concise pointers in SKILL.md:

# Refactor an oversized skill in-place
skillforge optimize ./skills/bloated-api-skill --max-lines 400

# Or write to a new destination folder
skillforge optimize ./skills/bloated-api-skill -o ./skills/clean-api-skill
Optimized 'bloated-api-skill':
  Lines:  680 -> 240 (440 lines saved)
  Tokens: ~6200 -> ~2100 (4100 tokens saved)
  Extracted References:
    - references/database-guidelines.md
    - references/api-endpoints-manual.md
  Destination: ./skills/clean-api-skill
  Audit Verification: PASSED

7. Convert OpenAPI / Swagger specs into skills (import-openapi)

Convert an OpenAPI 3.0, 3.1, or Swagger 2.0 specification (JSON or YAML) into a portable skill package:

skillforge import-openapi ./openapi.yaml --output ./skills
Successfully imported 'petstore-api' into skills/petstore-api
  SKILL.md:               28 lines (~320 body tokens)
  endpoints.md reference: ~1850 tokens

The resulting package places an executive summary in SKILL.md and moves full endpoint schemas to references/endpoints.md, keeping prompt overhead low.

8. Lint agent instruction files (lint-context)

Scan root-level instruction documents (AGENTS.md, CLAUDE.md, .cursorrules, .windsurfrules, .gemini/GEMINI.md) for context-window health:

# Scan active project instruction files
skillforge lint-context

# Fail CI if warnings or excessive bloat are found
skillforge lint-context --strict

# Output machine-readable JSON
skillforge lint-context --json
Context Linter: my-project
Status: WARNINGS DETECTED
Files Scanned: 2 (AGENTS.md, CLAUDE.md)
Context Overhead: ~1840 tokens across 210 lines
Total Findings: 2

Findings:
  [HIGH] CTX-001 (CLAUDE.md:162): Context file has 162 lines (exceeds 150-line ceiling); oversized context degrades model attention and inflates per-turn token cost. Prune self-evident instructions or extract deep manuals to references/
  [LOW] CTX-003 (AGENTS.md:14): Generic buzzword 'seamless' found; replace with concrete operational constraints.

9. Generate a verified security badge (badge)

Show users that your skill passed security auditing. Generate a markdown or HTML badge for your repository:

skillforge badge ./my-skill
[![Audited by SkillForge](https://img.shields.io/badge/SkillForge-Security%20Passed%20100%2F100-2ea44f?logo=shield&style=flat-square)](https://github.com/gintingism/skillforge)

10. Install directly from GitHub (add)

Pull skills from remote repositories with security auditing and commit pinning:

# Pull a specific skill from a repository
skillforge add anthropics/skills:pdf

# Pin to an exact release tag or branch
skillforge add anthropics/skills:pdf@v1.2.0

# Install from a custom repository
skillforge add gintingism/skillforge:systematic-debugging

SkillForge audits the skill, installs it into detected assistant directories, and records the SHA-256 digest and Git commit SHA in skillforge.lock.

11. Verify skill integrity and detect drift (verify)

Check installed skills against skillforge.lock in CI/CD or local environments without making network requests. Detects file tampering, missing dependencies, or unmanaged skills:

# Verify active project
skillforge verify

# Emit JSON for automation
skillforge verify --json
  OK       clean-code (sha256: 4f3a9e1208bc...)
  OK       systematic-debugging (sha256: 8a91bc7d01fe...)

Verification PASSED: 2 skill(s) match skillforge.lock.

12. Compare changes before updating (diff)

Inspect diffs between local skills and upstream repositories, or compare two skill versions:

skillforge diff ./skills/my-skill
skillforge diff my-skill gintingism/skillforge:my-skill

13. Manage installed skills (list & remove)

See which skills are active across your editor targets:

skillforge list
Installed Skills:
  [ClaudeCode]:
    - antislop-code
    - systematic-debugging
  [Cursor]:
    - antislop-code
    - systematic-debugging

Remove a skill from all detected assistants and update your lockfile:

skillforge remove antislop-code

14. Create and package skills (create & pack)

Scaffold a single skill file or a full package directory with scripts and references:

# Single skill file
skillforge create api-design -d "Design REST/gRPC APIs. Use when creating new backend endpoints."

# Full package with scripts/ and references/
skillforge create db-migrator -d "Run Postgres migrations safely. Use when writing SQL schema updates." --full

Pack a skill into a zip archive, or unpack one safely with path traversal protection:

skillforge pack ./db-migrator --output ./db-migrator.zip
skillforge unpack ./db-migrator.zip --output ./skills

15. Search remote skills and community index (search-remote & index)

Discover skills from verified remote repositories or index entire skill collections into your local discovery catalog:

# Query curated remote index by keyword or tag
skillforge search-remote "trifecta"
skillforge search-remote "" --tag security

# Scan and index skills from any local directory or cloned repository
skillforge index ./community-skills --url https://github.com/my-org/skills

# Install with automatic security gate enforcement (blocks score < 80 or critical findings)
skillforge install lethal-trifecta-guard

16. Real-time editor linting with Language Server Protocol (lsp)

SkillForge includes an LSP daemon conforming to Language Server Protocol 3.17 over standard I/O:

# Start Language Server Protocol daemon
skillforge lsp

Configure skillforge lsp as an LSP server in Cursor (settings.json), VS Code, or Neovim (nvim-lspconfig) for *.md files containing YAML frontmatter:

  • Real-time Diagnostics: flags missing required frontmatter, kebab-case violations, token budget blowups, and rules SEC-001 through SEC-017 on save.
  • Hover Analysis: provides live word count, token weight estimations, and security score.
  • Completions: auto-completes standard skill schema keys (name, description, version, author, tags, allowed-tools).

17. Cryptographic signing and tamper verification (sign & verify-signature)

Prevent supply chain attacks and man-in-the-middle tampering by generating HMAC-SHA256 or asymmetric Ed25519 file manifest signatures for published skills and lockfiles:

# Generate an asymmetric Ed25519 keypair (writes release.pem and release.pem.pub)
skillforge keygen --algorithm ed25519 --out release.pem

# Sign a skill package directory or lockfile with Ed25519
skillforge sign ./skills/db-migrator --algorithm ed25519 --key-file release.pem --signer "security-team"
skillforge sign ./skillforge.lock --algorithm ed25519 --key-file release.pem

# Verify tamper-integrity with the public key
skillforge verify-signature ./skills/db-migrator --key-file release.pem.pub
skillforge verify-signature ./skillforge.lock --key-file release.pem.pub

18. Interactive Terminal Dashboard (tui)

Inspect token budgets, security posture, and installed assistant adapters in a unified terminal view:

# Snapshot report (ideal for scripts and CI)
skillforge tui --static

# Live dashboard with periodic refresh
skillforge tui --watch

19. MCP Runtime Security Firewall (firewall-mcp)

Protect agents against confused deputy flaws, tool parameter injection, and credential leakage by placing SkillForge's JSON-RPC firewall between the client and an MCP server:

# Automatically wrap all stdio servers in an existing mcp.json config
skillforge firewall-mcp --wrap-config ./mcp.json

# Wrap an upstream MCP server over stdio with live inspection and secret redaction
skillforge firewall-mcp --audit-log ./mcp-audit.jsonl -- npx -y @modelcontextprotocol/server-postgres

# Inspect a recorded JSONL stream of MCP traffic offline
skillforge firewall-mcp --check ./captured-traffic.jsonl --json

20. Multi-Model Trigger Benchmark Matrix (bench)

Evaluate trigger precision, recall, F1 score, and false positive rate across multiple routing profiles (claude-sonnet-router, gemini-flash-router, gpt-strict-router):

# Benchmark a single skill or workspace
skillforge bench ./skills/my-skill

# Export a quantitative JSON scorecard
skillforge bench . --output ./benchmark_scorecard.json

21. Progressive Disclosure Slicer (refactor-progressive)

Automatically slice a monolithic SKILL.md into references/*.md while verifying that 100% of code blocks and domain terms are preserved:

skillforge refactor-progressive ./skills/bloated-skill --target-tokens 500

22. Zero-Trust Sandboxed Script Runner (run-sandboxed)

Execute bundled Python (.py), shell (.sh/.bash), or Node.js (.js/.mjs) helper scripts inside an ephemeral filesystem jail with outbound sockets, subprocess creation, and host environment credentials stripped (automatically layered with Linux bwrap --unshare-net when available):

skillforge run-sandboxed ./skills/my-skill/scripts/helper.py --timeout 5.0

23. CycloneDX 1.6 AIBOM & SPDX Bill of Materials (sbom)

Generate a machine-readable CycloneDX v1.6 or SPDX v2.3 AI Bill of Materials (AIBOM) inventorying installed skills, SHA-256 package digests, token weights, MCP servers, and security audit findings:

# Export CycloneDX v1.6 AIBOM to bom.json
skillforge sbom . --output ./bom.json

# Export SPDX v2.3 format
skillforge sbom . --format spdx --output ./bom.spdx.json

24. SLSA v1.0 Provenance & in-toto Attestation (provenance & verify-provenance)

Generate and verify tamper-evident in-toto v1 Statements (https://slsa.dev/provenance/v1) recording per-file SHA-256 subject digests, builder identity, security audit scores, and optional HMAC-SHA256 or Ed25519 signatures:

# Generate Ed25519-signed SLSA v1.0 provenance attestation
skillforge provenance ./skills/my-skill --algorithm ed25519 --key-file release.pem --signer "release-ci"

# Verify provenance subjects and Ed25519 signature against disk
skillforge verify-provenance ./skills/my-skill --key-file release.pem.pub

25. Skill Dependency Graph & Topological Resolver (graph)

Analyze dependencies declared in SKILL.md frontmatter, compute topological load order, calculate cumulative transitive token costs, and detect circular dependencies (DEP-001), missing dependencies (DEP-002), or allowed-tools privilege escalation (DEP-003):

# Inspect dependency graph and topological load order
skillforge graph ./skills

# Export Mermaid flowchart TD diagram
skillforge graph ./skills --mermaid

26. Universal Context Rules Synchronizer (sync-rules)

Maintain AGENTS.md as your single source of truth and compile synchronized instruction files for Cursor (.cursor/rules/00-core.mdc), Claude Code (CLAUDE.md), .cursorrules, Windsurf (.windsurfrules), Cline (.clinerules), Gemini CLI (GEMINI.md), and GitHub Copilot (.github/copilot-instructions.md), or run in CI --check mode to catch rule drift (SYNC-001) and contradictory directives (SYNC-002):

# Synchronize AGENTS.md into Cursor, Claude, Gemini, and Copilot
skillforge sync-rules . --targets cursor,claude,cursorrules,gemini,copilot

# Verify in CI that no editor rules have drifted or introduced opposing directives
skillforge sync-rules . --targets cursor,claude,cursorrules --check

27. Policy-as-Code & Scoped Rule Suppression (policy & audit --policy)

Define declarative .skillforge-policy.yaml rules with minimum audit score gates, severity overrides, and scoped suppressions that require a justification reason and optional expiration date:

# Scaffold .skillforge-policy.yaml
skillforge policy --init

# Validate syntax and fail if any suppressions have expired
skillforge policy --check

# Run audit against policy
skillforge audit ./skills --policy .skillforge-policy.yaml

28. Machine-Wide Discovery Sweep & MCP Poisoning Checks (scan-all)

Inspect MCP server tool schemas for hidden tool poisoning (MCP-005), cross-server tool shadowing (MCP-006), and cross-server toxic flows (MCP-007), or sweep an entire workspace and home IDE directories in one run:

# Sweep workspace skills and mcp.json files
skillforge scan-all .

# Include ~/.claude, ~/.cursor, ~/.gemini, ~/.windsurf, and export SARIF
skillforge scan-all . --home --sarif sweep.sarif

29. Skill Lifecycle Updates & Lockfile Interop (check, update, migrate-lock)

Check locked skills for upstream updates or local drift, apply audited updates that pass security gates, or convert vercel-labs/skills lockfiles (skills-lock.json) into SHA-256 verified skillforge.lock:

# Check locked skills for upstream updates or local drift
skillforge check

# Fetch, audit, install, and update lockfile hashes safely
skillforge update --min-score 80

# Convert skills-lock.json to skillforge.lock
skillforge migrate-lock ./skills-lock.json

30. Local Offline Skill Usage Telemetry (telemetry)

Track local MCP server usage (get_skill, get_skill_resource), token loading counts, and unused installed skills that consume startup pointer tokens without being invoked (100% offline, honors DO_NOT_TRACK=1):

# Inspect skill usage ranking and unused pointer-token waste
skillforge telemetry

Automate in CI/CD (GitHub Action)

Add SkillForge to your GitHub Actions workflow to audit pull requests, enforce token budgets, and upload SARIF reports to GitHub Code Scanning:

name: Audit Agent Skills
on: [pull_request, push]

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - name: Run SkillForge Security & Token Linter
        uses: gintingism/skillforge@main
        with:
          path: './skills'
          strict: 'true'
          budget: 'true'
          sarif: 'skillforge-findings.sarif'

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: 'skillforge-findings.sarif'

Model Context Protocol (MCP) Integration

SkillForge includes a native MCP server conforming to the Agent Plugins 1.0 specification (configured via mcp.json), so coding agents can inspect, search, and audit skills during their development loop:

{
  "mcpServers": {
    "skillforge": {
      "command": "skillforge",
      "args": ["serve-mcp"],
      "env": {
        "SKILLFORGE_REGISTRY_PATH": ".skillforge"
      }
    }
  }
}

Exposed MCP tools (supports --transport stdio|sse|streamable-http):

  • search_skills(query, limit): Search local and built-in skill catalogs.
  • get_skill(name): Read the full SKILL.md instructions.
  • get_skill_resource(name, resource_path): Read disclosed references/*, scripts/*, or text assets/* files on demand with path traversal protection.
  • validate_skill(content): Test frontmatter syntax in memory.
  • audit_skill(content): Audit a raw skill document for prompt injections, AST taint flows, and malicious patterns.
  • audit_mcp_config(config_path): Audit an mcp.json configuration for plaintext secrets, shell wrappers, and tool poisoning.
  • check_policy(content, policy_path): Evaluate a SKILL.md document against a .skillforge-policy.yaml gate.
  • skill://{name}: Resource URI for direct document retrieval.

Supported Assistants

SkillForge detects your assistant environment and places skills in the canonical directory:

Assistant Detected by Installed location
Google Antigravity .gemini/ .gemini/config/skills/<name>/SKILL.md
Gemini CLI .gemini/skills/, GEMINI.md .gemini/skills/<name>/SKILL.md
Claude Code & Claude Desktop .claude/ .claude/skills/<name>/SKILL.md
Cursor .cursor/ .cursor/skills/<name>/SKILL.md
Windsurf .windsurf/, .windsurfrules .windsurf/skills/<name>/SKILL.md
Cline .cline/, .roomodes .cline/skills/<name>/SKILL.md
Roo Code .roo/, .roomodes .roo/skills/<name>/SKILL.md
OpenCode .opencode/, opencode.json .opencode/skills/<name>/SKILL.md
Codex CLI .codex/ .codex/skills/<name>/SKILL.md
Universal Agents (npx skills) .agents/ .agents/skills/<name>/SKILL.md
AGENTS.md Catalog AGENTS.md Appended to AGENTS.md catalog
GitHub Copilot .github/ .github/copilot-instructions.md

To install a skill globally to your user profile instead of the current project, add --global (-g):

skillforge install systematic-debugging --global

Built-in Skills (37 Zero-Slop Skills)

SkillForge ships with 37 practical engineering skills to address common agent failure modes identified in benchmark research:

Code Quality, Security & Performance

  • supply-chain-sentinel: Check package existence, registry age, and run CVE audits (pip-audit, npm audit) before adding dependencies.
  • supply-chain-lockfile-guard: Lockfile cryptographic integrity verification, unpinned runtime install detection, and lifecycle script auditing (references/lockfile-audit-checklist.md).
  • secret-sanitizer: Pre-commit git diff auditor that prevents API keys, private tokens, and credentials from leaking.
  • lethal-trifecta-guard: Isolation boundaries against the Lethal Trifecta (OWASP AST10) separating private credentials, untrusted content ingestion, and external network egress (references/isolation-boundaries.md).
  • memory-hygiene-sentinel: Cross-session memory and git hook protection for CLAUDE.md, AGENTS.md, MEMORY.md, .cursorrules, and .git/hooks/ (OWASP ASI06, references/memory-audit-checklist.md).
  • contract-test-generator: Property-based testing and contract boundary fuzz tests (Hypothesis, fast-check) to verify invariants.
  • blast-radius-containment: Upstream reference tracing and a strict file touch budget before modifying shared code or public APIs.
  • security-threat-modeler: Trust-boundary mapping, IDOR/BOLA object-level authorization checks, SSRF validation, and injection sink verification.
  • performance-profiler: Baseline-first latency (p50/p95/p99), N+1 query detection, and algorithmic complexity verification before optimizing.
  • antislop-code: Comment hygiene and anti-overengineering filters that remove trivial narrative comments and prevent speculative generality.
  • spec-driven-development: Schema-first API design and red-green verification loops before writing application logic.
  • zero-downtime-migration: Four-phase Expand-Contract pattern for non-breaking database schema and API evolutions.
  • code-review: Multi-pass adversarial code review matrix (correctness, security, performance, test integrity) before merging pull requests.
  • git-workflow: Atomic conventional commits, pre-staging diff checks, protected branch safety guardrails, and conflict pause protocol.
  • test-driven-development: Red-Green-Refactor development cycle with test runner discovery, failing reproduction assertions, and raw terminal exit criteria.
  • dependency-upgrade: Systematic version updates with changelog and CVE audits, incremental single-package bumps, and rollback safeguards.
  • architecture-griller: Pre-implementation design interrogation, trade-off matrix analysis, and Architecture Decision Record (ADR) authoring (references/adr-template.md).
  • browser-qa-verifier: Live headless browser QA with Playwright/DevTools, console/network error listeners, three-state UI verification, and accessible locator rules (references/playwright-checklist.md).
  • database-query-safety: SQL execution plan (EXPLAIN ANALYZE) auditing, composite B-Tree index ordering, non-blocking DDL migrations, and Row-Level Security (RLS) checks (references/sql-anti-patterns.md).

Autonomous Loop Stability & Debugging

  • systematic-debugging: Four-phase diagnosis protocol (Reproduce, Isolate, Hypothesize, Surgical Patch) before touching code.
  • cognitive-loop-breaker: Three-strikes circuit breaker that forces a hard git restore and hypothesis invalidation when stuck in repetitive edit-fail loops.
  • flaky-test-isolation: Stress-reproduction loop (50x iterations) and diagnosis protocol for race conditions, clock skew, and state leakage.
  • runtime-api-verification: Interactive signature introspection (inspect, dir(), compiler definitions) to prevent hallucinated arguments.
  • git-worktree-isolation: Isolated Git worktrees for concurrent tasks, speculative fixes, and clean rollback boundaries (references/worktree-cleanup-protocol.md).
  • atomic-rollback-guard: Mandatory restore checkpoints before destructive code mutations and automated hard rollbacks on test failure (references/rollback-decision-tree.md).
  • traceback-postmortem: 5-line root cause distillation from lengthy stack traces to prevent context window poisoning (references/5-whys-template.md).

Context Efficiency & Multi-Agent Operations

  • mcp-least-privilege-sentinel: Least-privilege boundary enforcement, read-write segregation, and scoped filesystem permissions for MCP tools (references/mcp-permission-matrix.md).
  • attention-anchor-ledger: State anchor ledger to prevent model attention degradation (lost-in-the-middle) in long-context threads exceeding 100k tokens (references/state-anchor-schema.md).
  • skill-architect: Multi-file progressive disclosure guide for authoring low-token SKILL.md, AGENTS.md, and CLAUDE.md files.
  • caveman: Terse technical communication mode that reduces token spend while preserving exact paths, commands, and errors.
  • context-compactor: Structured state distillation and active hypothesis ledgers for long-running agent threads nearing context limits.
  • mcp-tool-designer: Type-safe schema design, idempotent hints, token boundaries, and stderr error separation for MCP servers.
  • agent-observability: OpenTelemetry tracing standards, step timing, and 16KB payload truncation boundaries.
  • human-in-the-loop: Three-tier permission model separating read-only queries from irreversible actions.
  • summarize: Executive engineering summaries with exact file and line citations.
  • tavily-search: Authoritative primary-source technical research with cross-verification.
  • self-improving-agent: Error recording loop that turns recurring bugs into durable project rules.

Static Scanner Scope & Honest Limitations

SkillForge provides deterministic, 100% offline static and sandboxed auditing to catch dangerous instruction patterns before skills run:

  • What SkillForge Catches: Malicious shell pipelines (curl | bash, irm | iex), reverse shells, unauthorized file reads (~/.ssh, ~/.aws), persistent memory and git hook poisoning (SEC-013), Lethal Trifecta compound exfiltration chains (SEC-014), obfuscated execution wrappers (SEC-015), fork bombs and resource abuse (SEC-016), unpinned package installs (SEC-017), MCP configuration vulnerabilities (MCP-001 to MCP-004), Python AST taint flows and runtime sandbox network/process violations (SEC-008 / --sandbox), zero-width unicode obfuscation, deceptive link targets, executables hidden in assets/, and context-window token bloat. A small regression corpus in tests/test_corpus.py guards these patterns; it is not a measurement of real-world detection rates.
  • What Requires Human Review & Sandboxes: Pure natural-language policy evasion (instructions that subtly coax models into biased or non-compliant decisions without executable code or known jailbreak keywords) cannot be reliably detected by regex or AST analysis alone. We recommend combining SkillForge audits with runtime OS sandboxing and requiring human confirmation for irreversible external actions.

Contributing & Development

  • Package Distribution: Published on PyPI as agent-skillforge.
  • Launch Guidelines: See docs/LAUNCH_PLAYBOOK.md for distribution notes.
  • Local Development:
    git clone https://github.com/gintingism/skillforge.git
    cd skillforge
    python -m pip install -e ".[dev]"
    pytest
    mypy src
    

Listed on HOL Plugins

SkillForge on HOL Plugins shows the latest scan, trust score and release evidence for this plugin.


License: MIT

Metadata

Release files for agent-skillforge 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-skillforge 0.8.0
File Size Uploaded Provenance Actions
agent_skillforge-0.8.0.tar.gz 207.1 kB With provenance Details for agent_skillforge-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-skillforge 0.8.0
File Interpreter ABI Platform Actions
agent_skillforge-0.8.0-py3-none-any.whl Python 3 none any Details for agent_skillforge-0.8.0-py3-none-any.whl

Total release size: 392.4 kB

Release files / agent_skillforge-0.8.0.tar.gz

Download URL agent_skillforge-0.8.0.tar.gz
Size 207.1 kB
Tags Source
SHA-256 checksum
How to use checksums
8ddec519aba54fae08af82809a9942c354ba0daf0b898c23557fa31c654e0372
BLAKE2b-256 checksum
How to use checksums
d2eef9299bd73d33e92cad72bb2186e7fd74f6a800d0d52470de0d9aa203f752
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / agent_skillforge-0.8.0-py3-none-any.whl

Download URL agent_skillforge-0.8.0-py3-none-any.whl
Size 185.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
38b4ea08ea7e2a50bae972a15048c89fc64af0e4a8a7b55aeb8bed38add500fb
BLAKE2b-256 checksum
How to use checksums
2bb319cb943f2bccec267cb737bd309229d478ef5ee70acdc1b60eea8c455089
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for agent-skillforge 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agent_skillforge-0.8.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page