SkillConform is the open-source CI and test suite for Agent Skills: conformance, capability inventory, cross-agent compatibility evidence, deterministic security review, and regression testing. It catches broken metadata, unsafe instructions, missing resources, embedded secrets, broad tool grants, and policy regressions before a skill reaches an agent.

Agent Skills are portable folders built around SKILL.md. The reference validator checks the core format; SkillConform adds a complementary quality layer for security review, workspace scanning, policy tests, CI, JSON, and SARIF.

Status: v0.3.0 is the latest public release on npm and GitHub. The CLI, library API, and GitHub Action are ready for early adopters. Static compatibility and security results are evidence for review, not runtime certification.

Quick start

Run without installing globally:

npx skillconform check ./my-skill
npx skillconform audit ./skills --fail-on warning

Generate machine-readable reports:

npx skillconform audit ./skills --format json -o skillconform.json
npx skillconform audit ./skills --format sarif -o skillconform.sarif

Inventory the capability surface before a skill is installed or published:

npx skillconform inventory ./skills
npx skillconform inventory ./skills --format json -o capabilities.json

The versioned skillconform.capabilities/v1 document records declared tools, local references, bundled scripts, detected network hosts, shell/network signals, and portability notes. It is evidence for review and CI policy—not a claim that a skill is safe or compatible with every agent.

Compare the same skill against documented host constraints:

npx skillconform matrix ./skills
npx skillconform matrix ./skills --format json -o compatibility.json

The versioned skillconform.compatibility/v1 matrix starts with Agent Skills, Claude Code, Claude API, OpenAI Skills, and Gemini CLI profiles. PASS means no static blocker was found, REVIEW means runtime/host evidence is still needed, and UNSUPPORTED means a documented constraint is contradicted. See cross-agent compatibility profiles.

For a guided walkthrough, follow the five-minute demo.

To run from source:

git clone https://github.com/GenRamzi/skillconform.git
cd skillconform
npm ci
npm run build
node dist/src/cli.js audit ./skills --fail-on warning

Commands

Command	Purpose
check [path]	Validate Agent Skills structure, metadata, naming, size, and references.
audit [path]	Run conformance checks plus deterministic security rules.
inventory [path]	Produce a deterministic capability/portability inventory.
matrix [path]	Compare static evidence with versioned host compatibility profiles.
test [file]	Execute regression expectations from skillconform.yaml.
init [file]	Create a starter policy-test configuration.

Common options:

--format pretty|json|sarif
--output, -o <file>
--fail-on error|warning|note|none
--quiet, -q

SkillConform returns exit code 0 when the selected threshold passes, 1 for policy findings, and 2 for invalid usage or configuration.

What it detects

• Required name and description metadata.
• Agent Skills naming and directory-matching rules.
• Invalid field types and non-portable frontmatter.
• Missing or escaping local references.
• Oversized SKILL.md instructions that defeat progressive disclosure.
• Embedded API keys, GitHub tokens, AWS keys, and private keys.
• Destructive shell operations, download-to-shell pipelines, privilege escalation, and dynamic evaluation.
• Prompt-injection phrases that attempt to override host instructions or reveal system prompts.
• Broad pre-approved shell access.
• Undeclared network requirements.

See the complete rule reference. Security findings are evidence for review, not a guarantee that a skill is safe.

Regression policy

Create a configuration:

npx skillconform init

Then define expectations:

version: 1
tests:
  - name: published skills remain clean
    path: skills
    mode: audit
    expect:
      errors: 0
      warningsAtMost: 0
      excludeRules:
        - SEC001
        - SEC002

Run it with:

npx skillconform test skillconform.yaml

GitHub Action

name: Agent Skill quality

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  skillconform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: GenRamzi/skillconform@v0.3.0
        with:
          path: skills
          mode: audit
          fail-on: warning

Pin the action to a version tag or immutable commit SHA in maintained repositories.

Library API

import { scanTarget, renderReport } from "skillconform";

const result = scanTarget("./skills", "audit");
process.stdout.write(renderReport(result, "json"));

Design principles

• Deterministic first: the same files produce the same findings without an API key.
• Portable: core checks follow the open Agent Skills specification.
• Reviewable: every finding has a stable rule ID and a concrete remediation.
• CI-native: reports work in terminals, scripts, and SARIF consumers.
• Least privilege: security rules favor explicit tools, paths, and network requirements.

Read the architecture, cross-agent compatibility profiles, SkillConform 2.0 direction, roadmap, and contribution guide before proposing larger changes.

Community and launch resources

• Test the tool and report a sanitized real-world result in the early-adopter feedback issue.
• Use the multi-channel launch kit for Show HN, Reddit, LinkedIn, X/Bluesky, and technical articles.
• Keep demonstrations reproducible and free of credentials, private skills, customer content, or unsupported security claims.

Ecosystem, adoption, and partnerships

SkillConform is the primary conformance layer in a small open-source reliability toolchain maintained by GenRamzi:

• Creative Agent Skills is a self-owned public integration that audits its skills/ directory with SkillConform in CI.
• ArgWitness is an early alpha for producing concrete old-valid/new-invalid counterexamples when MCP, OpenAI, or Anthropic tool schemas change.
• AgentProof is an experimental independent-verification project for test, CI, and regression claims.

These relationships describe architecture and maintenance scope; self-owned integrations are not counted as independent adoption. For the problem statement, target users, differentiators, measurable adoption milestones, partnership paths, and due-diligence links, read the project brief.

The highest-value contributions now are independent integrations, minimized false-positive fixtures, missing-rule reports, compatibility tests, and public case studies.

Scope and limitations

SkillConform performs static and policy analysis. It does not execute untrusted skill scripts, prove semantic correctness, replace sandboxing, or certify a skill as secure. Review skills before granting filesystem, shell, network, or external-service access.

License

Apache License 2.0. See LICENSE.