Agentic.Skill.Service (agentic v0.2.2)

Copy Markdown

Workspace-scoped skill management.

Skills are folders in workspace/skills/<name>/ containing a SKILL.md file (YAML frontmatter + markdown body) and optional scripts/, references/, and assets/ directories.

Supports installing skills from GitHub repos in owner/repo or owner/repo/subpath format, and searching via the GitHub code search API.

GitHub Authentication

GitHub API calls work without authentication for public repos (with lower rate limits). To use authenticated requests, pass a :get_secret callback in opts:

Service.search("query", get_secret: fn service, key -> {:ok, token} end)

The callback receives ("github", "api_key") and should return {:ok, token} or :error.

Summary

Functions

analyze_model_tier(workspace_root, skill_name, opts \\ [])

Analyze a skill's model tier requirements.

info(repo_spec, opts \\ [])

Fetch detailed information about a skill from GitHub without installing it.

install(workspace_root, repo_spec, opts \\ [])

Install a skill from a GitHub repository into the workspace.

list(workspace_root, opts \\ [])

List installed skills with name and description summaries.

read(workspace_root, skill_name, opts \\ [])

Read the full parsed SKILL.md content for an installed skill.

remove(workspace_root, skill_name, opts \\ [])

Remove an installed skill from the workspace.

search(query, opts \\ [])

Search for skills using the skills CLI (bun x skills find).

Functions

analyze_model_tier(workspace_root, skill_name, opts \\ [])

@spec analyze_model_tier(String.t(), String.t(), keyword()) ::
  {:ok, %{tier: atom(), reasons: [String.t()]}} | {:error, String.t()}

Analyze a skill's model tier requirements.

If the skill already has model_tier in frontmatter, returns that. Otherwise runs static analysis and returns the recommended tier with reasons.

Options:

  • :storage — a %Storage.Context{}

info(repo_spec, opts \\ [])

@spec info(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, String.t()}

Fetch detailed information about a skill from GitHub without installing it.

The repo_spec can be:

  • "owner/repo" — looks for SKILL.md at root
  • "owner/repo/path/to/skill" — skill in a subdirectory

Returns skill metadata (name, description, license, compatibility), full instructions, GitHub repo stats (stars, description, last push date, license, language), and the skills.sh audit URL.

Options:

  • :get_secret — callback for GitHub API authentication
  • Other options forwarded to Req for testing.

install(workspace_root, repo_spec, opts \\ [])

@spec install(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, String.t()}

Install a skill from a GitHub repository into the workspace.

The repo_spec can be:

  • "owner/repo" — installs from repo root (expects SKILL.md at root)
  • "owner/repo/path/to/skill" — installs from a subdirectory

Options:

  • :storage — a %Storage.Context{}
  • :get_secret — callback for GitHub API authentication
  • Other options forwarded to Req for testing.

list(workspace_root, opts \\ [])

@spec list(
  String.t(),
  keyword()
) :: {:ok, [%{name: String.t(), description: String.t()}]}

List installed skills with name and description summaries.

Options:

  • :storage — a %Storage.Context{} (default: local backend for workspace_root)

read(workspace_root, skill_name, opts \\ [])

@spec read(String.t(), String.t(), keyword()) ::
  {:ok, Agentic.Skill.Parser.parsed_skill()} | {:error, String.t()}

Read the full parsed SKILL.md content for an installed skill.

Options:

  • :storage — a %Storage.Context{}

remove(workspace_root, skill_name, opts \\ [])

@spec remove(String.t(), String.t(), keyword()) :: :ok | {:error, String.t()}

Remove an installed skill from the workspace.

Options:

  • :storage — a %Storage.Context{}

search(query, opts \\ [])

@spec search(
  String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, String.t()}

Search for skills using the skills CLI (bun x skills find).

Falls back to GitHub code search API if bun is not available. The skills CLI does not require authentication.

Options:

  • :get_secret — callback fn(service, key) -> {:ok, token} | :error end for GitHub API authentication. Falls back to GITHUB_TOKEN env var.

  • Other options forwarded to Req for testing.