Obscure Package Master

Use this skill if your uncertainty with a package's API is > 5% to create a deterministic, versioned mirror of the package repo with a built-in coordinate sy...

Security Scan

The skill mostly does what it claims (download a PyPI package, AST-parse it, and write a local skill mirror), but the included script performs sensitive filesystem writes, probes provider API key environment variables, and uses unsafe archive extraction—risks that are disproportionate to the simple stated purpose.

Purpose & Capability

The name/description (creating a deterministic, versioned local mirror/grep-map of a Python package) matches the behavior of the included generate_mirror.py: it downloads a package, extracts source, parses AST, writes a .skills/<package>-<version> directory with references and SKILL.md. Requesting provider-specific paths via env detection is consistent with installing the generated skill into a provider's skills folder.

Instruction Scope

SKILL.md and the script instruct the agent to download packages from PyPI, extract archives, and write files into the agent's skills directory. The code also inspects environment variables (provider API keys and AGENT_SKILLS_PATH) not declared in the skill metadata. While provider detection is plausible, the script's behavior grants it filesystem write access to a skills directory and reads many environment variables beyond the metadata.

Install Mechanism

No install spec (instruction-only) but the package includes a runnable Python script that performs network downloads and archive extraction. The script calls `pip download` (expected) and then uses tarfile.extractall() and zipfile.extractall() without path-sanitization—this is a known path-traversal/unsafe-extraction vulnerability that can write files outside the intended tmp dir. The script writes generated skill directories into provider/agent skill paths, which is powerful and persistent on disk.

Credentials

The skill metadata lists no required env vars, but SKILL.md and the script probe many provider API key env vars (ANTHROPIC_API_KEY, CLAUDE_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, CODEX_API_KEY, GITHUB_COPILOT_TOKEN, AGENT_PROVIDER, AGENT_SKILLS_PATH). Reading those secrets to detect provider is not strictly necessary for mirroring a PyPI package and is disproportionate without explicit declaration; the script does not exfiltrate them but will observe them if present.

Persistence & Privilege

The script intentionally writes a new skill into the agent's skills directory (e.g., ~/.openai/skills or ./.skills). This is consistent with the stated goal (generate a local skill), but it means the skill will create persistent files in agent-managed locations and could overwrite or clutter the skills folder. 'always' is false and the skill does not auto-enable itself across agents, but filesystem persistence is present.

What to consider before installing

This tool appears coherent for creating local mirrors of Python packages, but take precautions before running it: - Review and sandbox: Inspect the generate_mirror.py source yourself (it's included). Prefer running it in an isolated environment (container, ephemeral VM, or a throwaway account) so its filesystem writes and network downloads can't affect important data. - Archive extraction risk: The script uses tarfile.extractall() and zipfile.extractall() without sanitizing paths—malicious or malformed archives could write files outside tmp_download. Don’t run it on untrusted packages without adding safe extraction checks. - Environment probing: The script checks many provider API key environment variables (OpenAI/Gemini/Anthropic/Copilot). It doesn't appear to send them anywhere, but it will observe them. If you’re uncomfortable, run with those env vars unset or in a restricted environment. - Network trust: The tool uses pip to download source distributions from PyPI. If you mirror packages you don’t control, ensure you trust the package/version (supply pinned versions you reviewed). Consider using an internal package proxy/mirror if you have one. - Check generated content: After running, inspect the newly created .skills/<package>-<version>/references and SKILL.md before allowing an agent to use them. Make sure no unexpected files were created and no existing skills were overwritten. If you want to use this skill, consider patching the script to implement safe archive extraction (sanitize file names), and to avoid scanning for provider API keys unless explicitly requested.

This skill allows you to ground yourself in the objective reality of a package's source code by generating a deterministic "grep map" and a local mirror of its source.

Trigger Scenarios

• You are working with a library that is not in your top-tier training set (e.g., NOT numpy, pandas, requests).
• You find yourself searching for basic API signatures or parameters for a library.
• You have a >= 5% uncertainty about a package's API behavior or structure.
• The package's documentation is sparse or confusing.

Instructions

When the trigger conditions are met, follow these steps to generate a grounded reference for the package:

1. Identify the Package & Version: Determine the package name and the exact version you need (e.g., from requirements.txt, pyproject.toml, or pip show).

2. Run the Generator: Execute the generate_mirror.py script to create a local skill for that specific package version.

   python3 <path_to_scripts>/generate_mirror.py <package> <version>
   

3. Activate the New Skill: Once generated, a new skill will be available in .skills/<package>-<version>.

4. Use the Grep Map: Read the SKILL.md of the newly created skill. It contains a map of all classes and functions with their exact line ranges.

5. Targeted Reading: Use the map to perform surgical read_file calls on the files in the references/ directory of the new skill.

   • Example: "I see MyClass.my_method is in references/utils.py lines 120-145. I will read those lines now."

Core Principles

• Deterministic: The map is a direct reflection of the source code (AST-parsed). No LLM interpretation is involved in building the map.
• Coordinate System: Use the provided line ranges to avoid reading large files. Only grep exactly what you need.
• Grounding: If the package source is available, there is no excuse for API hallucinations.

Provider Compatibility

This skill is designed to work with any AI agent provider that can execute Python scripts. The output location is configurable for each provider:

Provider	Default skills path	Auto-detected via env var(s)
Claude	~/.claude/skills	ANTHROPIC_API_KEY, CLAUDE_API_KEY
Gemini	~/.gemini/skills	GEMINI_API_KEY, GOOGLE_GENERATIVEAI_API_KEY
Codex	~/.copilot/skills	CODEX_API_KEY, GITHUB_COPILOT_TOKEN
Cursor	~/.cursor/skills	—
OpenAI	~/.openai/skills	OPENAI_API_KEY
OpenClaw	~/.openclaw/skills	—
Cline	~/.cline/skills	—

Configuration priority (highest wins):

1. AGENT_SKILLS_PATH environment variable
2. skills_path in config.json
3. Provider-specific default (auto-detected or set via provider in config.json / AGENT_PROVIDER env var)
4. .skills/ in the current working directory

Example config.json for explicit provider selection:

{
  "provider": "gemini"
}

---

Note: This skill currently supports Python packages via PyPI.