⚡ 10-Second Quickstart (Zero-Install)

No Node.js, npm, or permanent installation required. Run directly with uvx or pipx:

# 1. Diagnose your workstation & assistant skills for security & bloat
uvx agent-skillforge doctor

# 2. Audit any local or community skill before executing it
uvx agent-skillforge audit ./skills/my-skill

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

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

Or install permanently via pip:

pip install agent-skillforge

💡 Why SkillForge?

As AI coding assistants adopt the open SKILL.md format (standardized under the Agentic AI Foundation / AAIF), two major friction points have emerged:

1. Supply-Chain & Prompt Injection Attacks: Community skills are executable instruction sets. Unvetted skills can hide indirect prompt injections, Trojan Unicode characters, credential harvesters (~/.ssh, ~/.aws), or command injections.
2. Context Window & Token Burn: Loading unoptimized skills burns hundreds of tokens on every turn before an agent even starts thinking, driving up API bills and degrading reasoning quality.

🛠️ Core Workflows

1. Diagnose your workspace (doctor)

Inspect all installed skills across your project or global workstation (Claude Code, Cursor, Antigravity, Windsurf, Cline) for security vulnerabilities, context window load, and broken pointers:

# Diagnose active project
skillforge doctor

# Diagnose all global machine skills
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)

Before letting an agent read and execute a skill, inspect it for hidden payloads, broken progressive disclosure links, and prompt injection:

skillforge audit ./skills/my-new-skill

Example output:

Audit Report: my-new-skill
Status: PASSED (Score: 100/100)
Context Load: 60 pointer tokens | 520 body tokens (27 lines)
Total Findings: 0

What the auditor scans for:

• Invisible Unicode (SEC-001): Zero-width spaces (\u200B, \uFEFF), homoglyphs, and directional overrides used to hide prompt instructions from human code review.
• Prompt Injections & Jailbreaks (SEC-002): Directives like "ignore previous instructions", "system override", or attempts to disable safety guardrails. Quoted references in defensive guides are flagged as MEDIUM, while bare imperative commands remain CRITICAL.
• Dangerous Shell Commands (SEC-003): Script patterns like curl ... | bash, base64-decoded execution, and outbound data exfiltration.
• Credential Path Access (SEC-004): Unsanctioned attempts to access ~/.ssh, ~/.aws/credentials, or local environment secrets.
• Invisible Bidi & Control Characters (SEC-005): Trojan Source bidirectional control characters (\u202E, \u2066) that alter code execution order while displaying harmlessly.
• Markdown Link Spoofing & Phishing (SEC-006): Mismatched visual labels vs target URLs hiding malicious redirects.
• Trigger Quality (QUAL-001): Verifies model-invoked descriptions contain explicit activation conditions.
• Directory Alignment (QUAL-002): Ensures folder name matches YAML name.
• Progressive Disclosure Budget (QUAL-003): Flags SKILL.md bodies exceeding 500 lines or ~5,000 tokens so heavy references are moved to references/.
• Broken Disclosure Pointers (QUAL-004): Verifies cited references/... or scripts/... exist.

For CI pipelines, pass --strict to fail on any warning, or --json for automation:

skillforge audit ./skills/my-new-skill --strict --json

3. Profile your project's context token budget (budget)

Every model-invoked skill keeps its name and description in the startup context window on every turn. Measure how much context your skills consume before they even trigger:

skillforge budget
# Or inspect the 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. Generate an official verified badge (badge)

Show users that your skill is clean, secure, and audited. Generate an official badge for your skill 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)

5. Grab a skill directly from GitHub (add)

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

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

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

# Install from your team's repository
skillforge add gintingism/skillforge:systematic-debugging

SkillForge fetches the skill, audits its security, routes it to all detected assistant targets, and pins its SHA-256 digest + Git commit SHA into skillforge.lock.

6. Verify skill integrity and detect drift (verify)

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

# Verify active project
skillforge verify

# Output JSON for CI automation
skillforge verify --json

  OK       clean-code (sha256: 4f3a9e1208bc...)
  OK       systematic-debugging (sha256: 8a91bc7d01fe...)

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

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

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

To remove a skill from all detected assistants and update your lockfile:

skillforge remove antislop-code

9. Create and package your own skills (create & pack)

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

# Standard 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 it into a shareable 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 every Pull Request:

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

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

🔌 Model Context Protocol (MCP) Integration

SkillForge includes a native MCP server so your coding agent can inspect, search, and audit skills autonomously during its 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 automatically detects your assistant environment and routes skills to 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

📦 Shipped Built-in Skills (22 Zero-Slop Skills)

SkillForge ships with 22 practical engineering skills designed to counteract common agent failure modes identified in benchmark research (SWE-bench, Snyk ToxicSkills, Skill-Inject):

Code Quality, Security & Performance

• supply-chain-sentinel: Verify 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 .env credentials from leaking.
• contract-test-generator: Property-based testing and contract boundary fuzz tests (Hypothesis, fast-check) to verify algebraic 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 (removes trivial narrative comments, stops 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 payload evolutions.

Autonomous Loop Stability & Debugging

• systematic-debugging: Disciplined 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 kwargs.

Context Efficiency & Multi-Agent Operations

• skill-architect: Multi-file progressive disclosure guide (bundled with references/mechanics.md) for authoring low-token SKILL.md, AGENTS.md, and CLAUDE.md files.
• caveman: Terse, high-density 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.

🚀 Community & Contributing

• Distribution: Published on PyPI as agent-skillforge.
• Launch Playbook: See docs/LAUNCH_PLAYBOOK.md for community distribution and launch guidelines.
• Development:

  git clone https://github.com/gintingism/skillforge.git
  cd skillforge
  python -m pip install -e ".[dev]"
  pytest
  mypy src
  

License: MIT