GitHub Verification: 5 Things Your Repo Needs Before Submitting

Why This Exists

Every skill in the catalog goes through an automated GitHub security check. Five Critical signals are required for any repo, plus 11 more in "Recommended" and "Bonus" tiers that boost the trust score but don't block publication.

These signals were chosen because they catch the most common problems we see in beginner repos: secrets leaked into git, code with vulnerabilities that was never scanned, unsigned releases that can't be traced to the source, and unclear licensing that prevents users from touching the code.

skills-il org repos get these settings automatically because our category repos are pre-configured. Your external repo needs to set them manually. This guide is the pre-submission checklist. It takes about 15 minutes to walk through all five.

The Critical Signals

1. Spec Compliant (spec_compliant)

What it checks: gh skill publish --dry-run runs over your SKILL.md and validates it against the open agentskills.io specification. If there are structural errors, missing fields, or HTML injection in the description, the check fails.

How to enable:

1. Install GitHub CLI 2.90.0 or later: brew install gh (Mac) or instructions for any OS. From 2.90 onward gh skill is built in, no separate extension install needed.
2. Run the check locally: gh skill publish --dry-run path/to/your-skill.

If errors appear, fix them based on the output. The CLI prints the line and column of every issue.

Note: This check is only for skills, not MCPs. MCP servers go through a separate validation pipeline (Tank, Snyk, Cisco) and gh skill publish cannot run against them.

2. Secret Scanning (secret_scanning)

What it checks: GitHub scans every commit for leaked API keys, passwords, service-account JSONs, and tokens. If scanning is enabled and there are no open secret alerts, the signal passes.

How to enable:

1. Go to the repo's Settings.
2. Scroll to Code security and analysis.
3. Enable both Secret scanning and Push protection.

For public repos this is free. Since March 2024 GitHub auto-enables it on new repos in personal accounts, but pre-existing repos and org-owned repos still need to be enabled manually. If yours says Disabled, just click Enable. Two minutes of work for permanent peace of mind.

Tip: Also enable Push protection. It blocks the push at the source when a secret is detected, instead of alerting after the secret is already in history. A secret that was already pushed counts as exposed even if you delete it later.

3. Code Scanning (code_scanning)

What it checks: CodeQL scans your code for common vulnerabilities (SQL injection, path traversal, XSS, etc.). The signal passes when CodeQL Default Setup is configured.

How to enable:

1. In the repo, go to Settings → Code security and analysis.
2. Under Code scanning, click Set up → Default.
3. Pick the main branch (master/main) and the languages it auto-detected.
4. Save.

The scan runs automatically on every push to main plus weekly on existing code. For private repos this requires GitHub Advanced Security (paid); for public repos it's free.

Don't see the option? Your organization might have disabled it at the org level. Talk to your GitHub admin or move the repo to a personal account temporarily.

4. Signed Release (signed_release)

What it checks: The latest release has a Sigstore attestation generated by GitHub Actions. This proves the release was actually built from the code in the repo, not swapped out afterward.

How to enable:

1. Create .github/workflows/release.yml in the repo with this content:

name: Release
on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
      attestations: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/attest-build-provenance@v4
        with:
          subject-path: |
            **/SKILL.md
            **/SKILL_HE.md
            **/metadata.json

1. Push a new tag: git tag v1.0.0 && git push origin v1.0.0.
2. The workflow generates an attestation that gets recorded in Sigstore Rekor.
3. Verify via the repo's Releases page (you'll see a "Verified attestation" badge), or download an artifact and run gh attestation verify <artifact> --owner <owner>.

Watch the subject-path format: It must be newline-separated (as above), not space-separated. A space silently breaks the action.

skills-il provides a reusable workflow that wraps all the details. It's already embedded in every skills-il/* category repo. To use it in yours:

jobs:
  release:
    uses: skills-il/release-workflow/.github/workflows/release.yml@v1

5. License Declared (license_declared)

What it checks: The repo contains a LICENSE file with a recognized SPDX identifier (MIT, Apache-2.0, BSD-3-Clause, etc.). Repos with no license, or with a license GitHub can't auto-detect, fail the check.

How to add:

1. On the repo's main page, click Add file → Create new file.
2. File name: LICENSE (uppercase, no extension).
3. GitHub will show a Choose a license template button on the right. Click it and pick a template. MIT is the standard choice for skills.
4. Push to master.

GitHub auto-detects the license and displays it in the repo sidebar. Within a minute it appears in the API and our check passes.

Why not a license note in the README? GitHub doesn't recognize licenses tucked into a README, even if it explicitly says "MIT License". You need a separate LICENSE file.

Frequently Asked Questions

What if only 4 of 5 pass? Can I still submit? Yes, but you won't be auto-approved. The submission goes into the human review queue with a clear error pointing at the failing signal. An admin will email you with a link back to this guide.

I'm a solo maintainer. Do I still need MFA? MFA is one of the 9 Recommended signals, not Critical. It doesn't block publication, but it does raise your trust score. To enable for your account: GitHub → Settings → Password and authentication → Two-factor authentication. Organizations that enforce MFA across all members get a separate signal.

My skill lives in a monorepo. Does the check run over the whole repo? spec_compliant only checks the specific skill folder. The other 4 are at the repo level and can't be scoped to a single folder. If you have multiple skills in one repo this actually works in your favor: the settings cover all skills at once.

My repo is private. Can I submit? No. The skills-il catalog only works with public repos, both because users install the skill directly from GitHub and because some checks (like license detection, secret scanning state) require GitHub to read the repo.

What's the difference between the Critical signals and other security requirements? The Critical signals are the minimum bar to appear in the catalog. We have additional layers (Tank scanner, manual review, weekly fact-checks) that run separately and don't depend on these signals.

Further Reading

• Security Page - overview of the verification system
• Trust Score Guide - what affects the score beyond the Critical signals
• Security Policy - how we handle vulnerability reports