Skillspector Code Skill

Overview

Security scanner for AI agent skills. Detect vulnerabilities, malicious patterns, and security risks before installing agent skills.

Top-level areas: .github/, contrib/, docs/, extensions/, src/, tests/.

Primary languages: Python, TypeScript, Shell. The codebase contains 282 public symbols across 69 source files.

Key symbols:

• is_language_compatible def is_language_compatible(rule_id: str, detected_language: str) -> bool — Return True when rule_id is reliable for detected_language.
• annotate_findings def annotate_findings( issues: list[dict[str, object]], detected_language: str, ) -> list[dict[str, object]] — Add a language_compatible field to each issue dict.
• ApiKey class ApiKey — A single API key with concurrency and rate-limit metadata.
• ApiKey.available def available(self) -> bool — True when this key can accept at least one more caller.
• ApiKeyPool class ApiKeyPool — Thread-safe pool of API keys with per-key concurrency slots.
• ApiKeyPool.__init__ def __init__(self, keys: list[ApiKey]) -> None
• ApiKeyPool.acquire def acquire(self, timeout: float | None = None) -> ApiKey — Acquire a slot on the least-loaded available key.
• ApiKeyPool.try_acquire def try_acquire(self) -> ApiKey | None — Non-blocking acquire — returns a key immediately or None.
• ApiKeyPool.release def release(self, key: ApiKey, *, success: bool = True) -> None — Release a slot on key back to the pool.
• ApiKeyPool.record_retry_success def record_retry_success(self) -> None — Increment the retry-success counter for reporting.
• ApiKeyPool.rate_limits_hit def rate_limits_hit(self) -> int — Total number of 429 responses encountered across all keys.
• ApiKeyPool.retry_successes def retry_successes(self) -> int — Total number of successful retries after a key switch.
• ApiKeyPool.keys_configured def keys_configured(self) -> int — Total number of keys in the pool.
• ApiKeyPool.total_capacity def total_capacity(self) -> int — Sum of max_concurrent across all keys.
• ApiKeyPool.active_requests def active_requests(self) -> int — Total active requests across all keys.
• ApiKeyPool.snapshot def snapshot(self) -> dict[str, object] — Return a snapshot dict suitable for report metadata.
• PooledChatModel class PooledChatModel — LangChain-compatible chat model wrapper with transparent key switching.
• PooledChatModel.__init__ def __init__( self, pool: ApiKeyPool, *, max_tokens: int = 4096, timeout: float = 30.0, max_retries: int = _MAX_RATE_LIMIT_RETRIES, ) -> None
• PooledChatModel.invoke def invoke(self, prompt: str) -> object — Synchronous invoke with automatic key switching on rate-limit.
• PooledChatModel.ainvoke def ainvoke(self, prompt: str) -> object — Async invoke with automatic key switching on rate-limit.

…and 262 more — see references/api.md.

When to Use

• Understanding the architecture and module layout of SkillSpector
• Extending or modifying SkillSpector consistent with its existing patterns
• Debugging issues by tracing through SkillSpector's modules and dependencies
• Setting up, running, or configuring SkillSpector
• Calling functions, classes, or methods in SkillSpector's public API

When NOT to use: General Python, TypeScript, Shell questions, tutorials, or tasks unrelated to the SkillSpector codebase.

Related: For general Python, TypeScript, Shell guidance, use language-specific skills instead.

Core Process

Step 1: Understand the Architecture

Read the existing code in SkillSpector before making changes. Check references/architecture.md to understand the module layout, dependency graph, and internal import structure. The goal is to extend existing patterns, not invent new ones.

Step 2: Locate Relevant Modules

Use references/api.md to find the public symbols, functions, and classes relevant to the task. Trace the call chain through SkillSpector's internal imports to understand how the pieces connect.

Step 3: Make Changes Following Existing Patterns

Implement the change consistent with SkillSpector's established conventions: naming patterns, error handling style, module organization, and test structure. Consistency matters more than personal preference.

Step 4: Verify the Change

Run the project's test suite and confirm all tests pass. If no tests exist for the changed behavior, write them first. Check that no regressions were introduced in adjacent modules.

Common Rationalizations

Red Flags

• Making changes to SkillSpector without reading references/architecture.md first
• Inventing new patterns instead of extending existing ones
• Skipping the test suite before declaring the task complete
• Modifying code outside the scope of the current task

Verification

Before declaring this workflow complete, confirm each item with evidence:

• Changes follow SkillSpector's existing patterns — evidence: diff review against references/architecture.md
• All tests pass — evidence: test runner output
• No regressions introduced in adjacent modules — evidence: full test suite output
• Code is consistent with the repository's naming and style conventions — evidence: code review

References

• Full API reference
• Architecture & dependencies
• Usage examples
• Setup & commands
• Configuration
• Full Code Digest