SkillForge

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

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

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

Related MCP server: Skills MCP Server

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.

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 a skill before running it (audit)

Scan a skill for hidden payloads, trojan unicode, prompt injections, and invalid resource pointers:

skillforge audit ./skills/my-new-skill

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 Unicode (SEC-001): Zero-width spaces (\u200B, \uFEFF), homoglyphs, and directional overrides used to hide prompt instructions.

• 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.

• Trojan Source Bidi Overrides (SEC-005): Bidirectional control characters (\u202E, \u2066) that alter code execution order while displaying harmlessly.

• Markdown Link Spoofing (SEC-006): Mismatched visual labels and target URLs hiding deceptive redirect destinations.

• 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.

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

skillforge audit ./skills/my-new-skill --sarif results.sarif

3. 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 (22 skills)
  Always-Loaded Startup Pointer Cost: ~1305 tokens
  On-Demand SKILL.md Body Cost:       ~7483 tokens
  Disclosed Resources Cost:           ~349 tokens

4. 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.

5. 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

6. 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.

7. 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)

8. 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.

9. 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.

10. 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

11. 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

12. 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

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

• 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/* or scripts/* files on demand.

• validate_skill(content): Test frontmatter syntax.

• audit_skill(content): Audit a raw skill document for prompt injections and malicious patterns.

• skill://{name}: Resource URI for direct document retrieval.

Supported Assistants

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

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 (22 Zero-Slop Skills)

SkillForge ships with 22 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.

• secret-sanitizer: Pre-commit git diff auditor that prevents API keys, private tokens, and credentials from leaking.

• 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.

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.

Context Efficiency & Multi-Agent Operations

• 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.

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

License: MIT