What Is SkillNet?

skillnet-ai provides the Python SDK and CLI for SkillNet, with six operations for working with reusable agent skills:

• Search for skills by keyword or semantic intent.
• Download skill folders and their resources from GitHub.
• Create structured skill packages from prompts, execution traces, repositories, or documents.
• Evaluate skill quality across safety, completeness, executability, maintainability, and cost awareness.
• Analyze local skill capabilities, usage scenarios, and relationships to build a reusable graph.
• Route a task through a local skill Wiki and return up to k skills with selection reasons.

Search and public downloads need no API key. Create, evaluate, and analyze use an OpenAI-compatible Chat Completions endpoint. Analyze also needs an embedding endpoint; route uses that same embedding endpoint and a separately configured Claude or Codex Agent SDK.

For the full project overview, research context, integrations, and roadmap, see the main SkillNet repository.

Installation

Requires Python 3.10 or newer.

pip install skillnet-ai

Install optional dependencies for analysis and routing:

pip install "skillnet-ai[graph]"         # scenario analysis
pip install "skillnet-ai[graph,claude]"  # analysis and routing via Claude
pip install "skillnet-ai[graph,codex]"   # analysis and routing via Codex

Quick Start

from skillnet_ai import SkillNetClient

client = SkillNetClient()

results = client.search(q="pdf", limit=5)
for skill in results:
    print(skill.skill_name, skill.skill_url)

skill = next((item for item in results if item.skill_url), None)
if skill is not None:
    local_path = client.download(skill.skill_url, target_dir="./my_skills")
    print(local_path)

Equivalent CLI:

skillnet search "pdf" --limit 5
skillnet download <skill_url> -d ./my_skills

Feature Overview

Python SDK

Initialize

from skillnet_ai import SkillNetClient

client = SkillNetClient()

The client reads environment variables and saved settings. Configure model APIs before using create, evaluate, analyze, or route; see Configuration. You can override client settings with api_key, base_url, model, github_token, skillnet_api_url, and json_mode. Embedding and Explorer endpoints are configured separately.

Search

Query the hosted SkillNet catalog and return a list of skill records. Keyword search defaults to sorting by stars. Vector search uses the hosted service's embeddings; EMBEDDING_* settings apply to local analysis and routing.

results = client.search(
    q="analyze financial PDF reports",
    mode="vector",
    threshold=0.85,
    limit=10,
)

for skill in results:
    print(skill.skill_name, skill.stars, skill.skill_url)

Download

Download the skill folder and its resources, validate its structure, and return the installed directory path. Use overwrite=True to replace an existing folder.

local_path = client.download(
    url="https://github.com/anthropics/skills/tree/main/skills/pdf",
    target_dir="./my_skills",
)
print(f"Installed at: {local_path}")

A failed replacement keeps the previous installation. For private repositories, set GITHUB_TOKEN. mirror_url (CLI: --mirror) is a fallback for public file downloads and is disabled when a GitHub token is in use.

URLs containing a commit SHA or an encoded branch slash (feature%2Fcsv) can identify a specific revision when a branch name would otherwise be ambiguous.

Create

Choose one input source per call: a conversation or execution trace, GitHub repository, PDF/Word/PowerPoint document, or direct prompt. The returned list contains generated directory paths. Use evaluate for a model assessment of the result, or skillnet validate <skill_dir> to check its structure locally.

# From a conversation or execution trace
client.create(
    trajectory_content=(
        "User: Check orders.csv for missing values.\n"
        "Agent: Read the CSV without modifying it, counted blank cells per column, "
        "and wrote quality-report.json."
    ),
    output_dir="./my_skills",
)

# From a GitHub repository
client.create(
    github_url="https://github.com/zjunlp/DeepKE",
    output_dir="./my_skills",
)

# From an office document
client.create(
    office_file="./guide.pdf",
    output_dir="./my_skills",
)

# From a direct prompt
paths = client.create(
    prompt=(
        "Create a csv-quality-checker skill that checks CSV files for missing "
        "values and duplicate rows without modifying the input."
    ),
    output_dir="./my_skills",
)
print(paths)

Generated packages use the standard skill layout.

Evaluate

Assess a local skill directory or a GitHub skill URL. Each dimension contains a level (Good, Average, or Poor) and a reason. The SDK reviews instructions and supporting files without executing the skill's scripts.

report = client.evaluate("./my_skills/pdf")

print(report["safety"]["level"], report["safety"]["reason"])
print(report["maintainability"]["level"], report["maintainability"]["reason"])

The five dimensions are safety, completeness, executability, maintainability, and cost awareness. Ratings are model judgments about the supplied materials.

Analyze

Extract scenarios and capabilities from local skills, then build a reusable relationship graph, retrieval index and Wiki for routing.

analysis = client.analyze("./my_skills", output_dir="./skillnet_index")
print(analysis.index_dir)
print(analysis.skill_count, analysis.relation_counts)

compose_with is directed: A's output or established state can support B's next operation in a stated scenario. similar_to is undirected: two skills offer comparable capabilities for a task or subtask, subject to their own constraints.

Place each skill in a direct child folder containing a YAML-frontmatter SKILL.md. Folder names are stable IDs; display names may repeat. Analysis reads the full SKILL.md but does not execute or automatically inspect linked scripts/references. The graph extra provides NumPy; BM25 requires SQLite FTS5. See endpoint configuration for the analysis model and embedding settings.

Pass budgets through options=AnalysisOptions(...), imported from skillnet_ai.

AnalysisResult contains index_dir, skill_count, relation_counts, and cache_hits. Output defaults to <skills_dir>/.skillnet; use output_dir to choose a location. Rerun analysis after editing skills. Valid cached results are reused; force=True (CLI: --force) recomputes them.

Route

Select up to k skills for a task using an index created by analyze. Hybrid search combines BM25 and vector rankings, then graph expansion adds related candidates. A Claude or Codex Agent SDK compares them in a task Wiki containing skill profiles, relationships, and source text.

result = client.route(
    "Extract tables from my PDF report and check the resulting CSV "
    "for missing values and duplicate rows.",
    index_dir="./skillnet_index",
    k=5,
)
for skill in result.skills:
    print(skill.skill_id, skill.name, skill.path, skill.reason)

Relations guide candidate exploration; the task and each skill's constraints determine the final selection. Agent SDK extras are loaded only for routing; install skillnet-ai[graph,claude] or skillnet-ai[graph,codex]. See endpoint configuration for the Explorer and embedding settings.

Pass budgets through options=RouteOptions(...), imported from skillnet_ai.

RouteResult contains skills and usage. Each skill has a skill_id, name, local path, and selection reason. Usage comes from the Agent SDK and is None when unavailable; it does not include the query embedding request.

k defaults to 5 and sets an upper limit. The result can contain fewer skills, including none, and may cover only part of a task. Dataset, format, and environment constraints affect the selection. Related skills are candidates, not mandatory selections. The result is a skill set: routing neither executes the task nor specifies an execution order.

Routing uses the latest successful analysis snapshot and generates a temporary task Wiki. It requires the same embedding endpoint and model used for analysis, with compatible vector dimensions. Edit the original skills and rerun analyze to update the index; editing generated Wiki pages does not update routing.

Invalid model responses, damaged indexes, and SDK timeouts raise errors. A failed Explorer call does not return a substitute selection based on retrieval rank.

CLI

The CLI is installed with the package. You can also invoke it as python -m skillnet_ai:

skillnet --help
skillnet <command> --help

Commands

Search

skillnet search "pdf"
skillnet search "analyze financial reports" --mode vector --threshold 0.85
skillnet search "visualization" --category "Development" --sort-by stars --limit 10

Download

skillnet download https://github.com/anthropics/skills/tree/main/skills/algorithmic-art
skillnet download <url> -d ./my_agent/skills
# With GITHUB_TOKEN already configured:
skillnet download <private_url>
skillnet download <url> --mirror https://ghfast.top/

Create

skillnet create ./logs/trajectory.txt -d ./my_skills
skillnet create --github https://github.com/owner/repo
skillnet create --office ./docs/guide.pdf
skillnet create --prompt "A skill for table extraction"
skillnet create --office report.pdf --model gpt-4o

create requires exactly one source and checks the generated package structure. Add --evaluate to run a model assessment after creation. If that assessment fails, the command returns a nonzero exit code and retains the generated files for inspection or reevaluation. A Poor rating is a valid result, not a command failure.

Evaluate

skillnet evaluate ./my_skills/pdf
skillnet evaluate https://github.com/anthropics/skills/tree/main/skills/algorithmic-art
skillnet evaluate ./my_skill --category "Development" --model gpt-4o

Analyze

skillnet analyze ./my_skills --output-dir ./skillnet_index --json

Route

skillnet route "Check my CSV for missing values and duplicate rows" --index-dir ./skillnet_index --k 5 --json

All six commands accept --json. Command results use one {ok, data, error} JSON object on stdout; logs go to stderr. Use this mode when calling the CLI from scripts or agents. See the output contract for details.

Use with Agents

The SkillNet skill gives compatible agents access to the same CLI and SDK. Install the complete skill directory with its scripts and references; see installation and configuration and agent-specific setup.

Use skillnet validate <skill_dir> --json to check a skill's structure locally, and skillnet doctor --json to inspect the environment visible to the agent.

Configuration

Settings resolve in this order: explicit arguments → environment variables → ~/.skillnet/config.json → defaults. Use SKILLNET_CONFIG to select another configuration file. The SDK does not load .env files automatically; load them into your process environment before creating the client.

search and public download require no credentials.

Linux / macOS:

export API_KEY="your-api-key"
export BASE_URL="https://api.openai.com/v1"
export SKILLNET_MODEL="gpt-4o"

Windows PowerShell:

$env:API_KEY = "your-api-key"
$env:BASE_URL = "https://api.openai.com/v1"
$env:SKILLNET_MODEL = "gpt-4o"

For an interactive setup, run skillnet configure --interactive. It saves settings for subsequent SDK and CLI calls. Configuration may contain API keys in plaintext; keep it outside version control.

skillnet doctor --json inspects configuration and installed dependencies locally. Add --check-network to check search and GitHub connectivity, --check-llm for a model request, or --check-explorer for an Agent SDK exploration check. The latter two use your configured model services and may incur charges.

Analysis and routing endpoints

Analysis, embeddings, and the Explorer have separate endpoint settings. The commands below read secrets from existing environment variables named MY_CHAT_KEY, MY_EMBEDDING_KEY, and MY_AGENT_KEY; replace the example URLs and model names with those supplied by your providers:

skillnet configure --base-url https://chat.example/v1 --model analysis-model \
  --api-key-env MY_CHAT_KEY
skillnet configure --embedding-base-url https://embedding.example/v1 \
  --embedding-model embedding-model --embedding-api-key-env MY_EMBEDDING_KEY
skillnet configure --explorer-backend claude --explorer-base-url https://agent.example \
  --explorer-model explorer-model --explorer-api-key-env MY_AGENT_KEY
skillnet doctor --json

Analysis uses Chat Completions; embeddings use the embeddings API. The Explorer gateway must support the selected SDK's protocol, tool calls, and structured output. A Chat Completions endpoint alone does not establish SDK compatibility. Set all three endpoint configurations explicitly, even when one provider serves them all. The default backend is claude; select Codex with client.route(..., backend="codex") or skillnet route ... --backend codex.

For per-call configuration, pass Endpoint(api_key=..., base_url=..., model=...) as embedding or explorer; import Endpoint from skillnet_ai. The analyze model keyword changes only the analysis model, retaining the client's URL and key.

Skill Package Layout

A skill package has a SKILL.md entry point and optional supporting directories:

skill-name/
├── SKILL.md          # required metadata and instructions
├── scripts/          # optional executable helpers
├── references/       # optional reference material
└── assets/           # optional templates, examples, or media

Keep the name, description, and usage instructions in SKILL.md. Put executable helpers in scripts/, detailed guidance in references/, and templates or other resources in assets/. Analysis reads SKILL.md; agents can load supporting files when they use the selected skill.

Contributing

Contributions are welcome. Open an issue for bugs, feature requests, or documentation improvements, and submit pull requests for focused changes.

The top level contains the main capabilities: searcher.py, downloader.py, creator.py, evaluator.py and analyzer.py. Analysis owns source extraction, relationship construction and model-result caching. router/ contains the routing flow (router.py), index construction/loading/retrieval (index.py), Wiki rendering (wiki.py) and both Agent SDK implementations (explorer.py).

core/ contains data contracts, prompts, model requests, configuration, validation and the existing injection scanner. It does not import the business modules. interfaces/client.py and interfaces/cli.py expose the Python and CLI entry points. The public Python entry point is from skillnet_ai import SkillNetClient; the CLI entry point is skillnet_ai.interfaces.cli:app.

When changing extraction or relation schemas/semantics, increment the explicit versions in src/skillnet_ai/core/prompts.py to invalidate obsolete cached results.

From the skillnet-ai/ directory:

pip install -e ".[graph,dev,claude,codex]"
pytest -q
mypy
python -m build

Use Ruff to check and format the Python modules you change, with the settings in pyproject.toml. The test suite uses offline model and Agent SDK fixtures; it does not require model credentials. Live routing quality needs a separate check with real skills and your configured providers.

License

SkillNet is licensed under MIT. Skills from external repositories retain their own licenses.