agentic-skills-manager 1.0.2

Scan skills before your agent trusts it.

Manage skills for Claude, Cursor, Codex, and OpenCode. Skills Manager scans every install and update.

Why · Scanner · AI review · Commands · Install · Reference

Why I built it

An agent skill can steer tool calls, run shell commands, and read files available to your agent. Installing one means trusting more than SKILL.md. Setup scripts, hidden files, hooks, archives, and binaries elsewhere in the source matter too.

I built Skills Manager because most skill installation workflows copy a repository directly into an agent's trusted directory. That is too much trust for code that can change how the agent behaves.

Skills Manager checks the selected GitHub repository or local folder before it copies anything. Static findings decide whether the operation can continue. If the skill passes, Skills Manager records its source so the same checks can run again before an update.

What the scanner reads

The scanner does not stop at SKILL.md. It walks the selected source tree and checks:

• Private keys and credential-like values
• Shell execution, subprocess use, destructive commands, and network scripts
• Symlinks, hard links, path traversal, and unsafe archive contents
• Git hooks, package lifecycle scripts, registry rewrites, and native loading
• Hidden configuration, binaries, oversized files, and common scanner-evasion techniques

The scanner reads untrusted source. It does not execute bundled skill code.

flowchart LR
    Source["GitHub or local source"] --> Resolve[Resolve]
    Resolve --> Inventory[Inventory every file]
    Inventory --> StaticScan[Static scan]
    Inventory --> AiReview[Optional AI review]
    StaticScan --> Gate{Policy gate}
    AiReview --> Gate
    Gate -->|Pass| Lifecycle[Install or update]
    Gate -->|Block| Report[Report and exit non-zero]
    Lifecycle --> Metadata[Record source metadata]

See it block an unsafe skill

The demo source includes a private key, a network download piped into a shell, a destructive command, and a hidden credential file. The scan identifies the exact files and stops before copying the skill:

Security result: unsafe (critical)
[CRITICAL] .env: Private key material found.
[HIGH] setup.sh: Network script piped into a shell.
[HIGH] setup.sh: Destructive 'rm -rf' command found.
exit code: 1

AI review is a second opinion

Static checks run every time. Add --ai-checks when you also want Claude, Cursor, Codex, or OpenCode to review the source for intent that pattern matching cannot settle:

skills scan https://github.com/owner/repo \
  --ai-checks --ai-agent codex

The selected agent's findings join the report, but its verdict cannot clear a static block. By default, a blocked static scan skips AI review. --force-run-ai-checks runs it anyway while keeping the source blocked.

The four agent CLIs do not provide the same isolation. Read the security policy before reviewing untrusted source on a workstation with sensitive files or credentials.

What it does

scan and analyze also have CI modes with JSON verdicts and non-zero policy exits.

Install and try it

pip install agentic-skills-manager

skills scan https://github.com/owner/repo
skills install https://github.com/owner/repo
skills list --verbose

install scans the source again before copying it. For an isolated CLI environment, use pipx install agentic-skills-manager instead.

The package installs six command names: skill, skills, skill-manager, skills-manager, agentic-skill-manager, and agentic-skills-manager. They all run the same entry point. This README uses skills.

curl -O https://raw.githubusercontent.com/mazen160/skills-manager/main/skills_manager.py
python3 skills_manager.py --help

Run skills with no arguments to print the banner and command list.

Common workflows

Work with local, single-file, and monorepo sources

# Scan locally without copying anything
skills scan ./path/to/skill

# Install one skill from a GitHub blob URL
skills install https://github.com/blader/humanizer/blob/main/SKILL.md

# Find every skill below a repository root
skills install https://github.com/owner/repo --recursive

# Install for Codex instead of Claude, the default target
skills install https://github.com/owner/repo --agent codex

Blob URLs ending in SKILL.md resolve to the containing skill directory. Variants with ?plain=1 or a line fragment work too. With --recursive, each directory below the selected root that contains SKILL.md becomes an install candidate.

Block medium-severity findings

skills install https://github.com/owner/repo \
  --minimum-accepted-severity low

Low and medium findings pass by default. Setting the accepted ceiling to low blocks anything medium or above.

To get an AI opinion after a static block, add --force-run-ai-checks --ai-agent claude. The static verdict still determines the exit status.

Exclude a reviewed rule or path

Every finding prints a stable rule ID. Exclusions are repeatable:

skills scan ./plugin-repository \
  --exclude git-hook-directory \
  --exclude git-hook-configuration

skills install ./skill \
  --exclude-path .githooks \
  --exclude-path 'docs/private/**'

--exclude RULE removes that rule from the verdict but leaves the matching content in place. --exclude-path GLOB omits matching source-relative content from the scan and, during installation, from the installed copy. Install exclusions are recorded in .skills-install.json and preserved by future updates.

Check and apply updates

skills update
skills update --apply --ai-checks --ai-agent codex

The first command compares installed content with its tracked source. The second applies the update after its security checks pass.

Analyze context and enforce limits in CI

skills analyze ~/.claude/skills ~/.codex/skills \
  --max-skill-tokens 50000 --max-file-tokens 10000 \
  --fail-on-max-tokens

skills scan https://github.com/owner/repo --ci --output result.json
skills analyze ./skills --ci --fail-on-max-tokens

For each skill, analyze shows its size, file count, validation errors, and three token estimates: metadata only, SKILL.md, and the full directory. CI mode writes JSON to stdout, sends the human report to stderr, and returns non-zero when policy fails.

Where the protection stops

Skills Manager scans before it copies. Static checks always run, and high or critical findings block installation by default. You can tighten that ceiling, or bypass it explicitly with --unsafe-install after reviewing the source yourself. The flag still prints every finding.

Approved files are copied atomically and tagged with source metadata for later update checks. After installation, the host agent decides how to interpret and execute the skill. Skills Manager is not a runtime sandbox, and a clean report is not proof that a skill is safe.

AI review can add findings. It cannot remove a static finding or make a blocked source pass.

The full trust model, reviewer isolation, and private reporting instructions are in SECURITY.md.

Reference

{"ai_skipped": false, "findings": 6, "review_type": "static", "risk_level": "critical", "safe": false, "source": "https://github.com/owner/repo", "tool": "skills-manager"}

skill
skills
skill-manager
skills-manager
agentic-skill-manager
agentic-skills-manager

git clone https://github.com/mazen160/skills-manager.git
cd skills-manager
python3 -m unittest discover -s tests -v

Project status

Skills Manager 1.0.2 is available on PyPI. CI tests it on Python 3.9 through 3.13.

Troubleshooting

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md for the development, test, and packaging workflow. Security-sensitive findings belong in the private channel documented in SECURITY.md, not a public issue.

See the changelog for release history.

Author

Mazin Ahmed: Website · X · LinkedIn · GitHub

License

MIT © Mazin Ahmed. See the license.