Importing skills

Before you can reference a skill in a profile or an inline run, it must be imported into Scope. Importing registers the skill, fetches its SKILL.md from GitHub, and stores an archive so runs get a reproducible snapshot.

Skills must conform to the Agent Skills specification. Each skill is a directory containing a SKILL.md file with YAML frontmatter and Markdown instructions. See Skill format reference at the bottom of this page for the full schema.

Where skills come from

A skill lives in a GitHub repository, inside a well-known directory. The repository can host many skills — each in its own sub-folder. Scope looks in these paths when resolving a skill:

• skills/
• .agents/skills/
• .github/skills/
• .claude/skills/
• .copilot/skills/
• .roo/skills/
• .cursor/skills/
• the repository root

A skill is identified by two parts:

| Part | Example | Description | | --- | --- | --- | | source | vercel-labs/agent-skills | The GitHub owner/repo that hosts the skill. | | skillName | vercel-react-best-practices | The directory name inside one of the well-known paths. |

Together they form the skill slug: vercel-labs/agent-skills/vercel-react-best-practices.

Import from the Portal

Search the skills registry

1. Open Skills in the Portal sidebar.
2. In the Import Skill card, type a search term (e.g. "react", "azure").
3. Results come from two sources — skills already imported into your Scope instance (marked internal) and the external skills.sh registry.
4. Click a result to import it.

Scope saves the skill record and automatically resolves the latest revision from GitHub. If auto-resolution fails (private repo, rate limit, etc.) the skill is still saved — you can retry later.

Add a skill manually

If the skill you need isn't in the registry, use the multi-step import wizard:

1. On the Skills page, click Import manually.
2. Enter the source repository (owner/repo) and submit. Scope scans the repository for all skills located in the well-known paths.
3. The wizard presents every skill found in the repo. Skills already imported into your instance are marked and show whether an upgrade is available.
4. Select the skills you want to import (or upgrade), then confirm. Scope creates the skill records and attempts auto-resolution from GitHub for each one.

Import via the REST API

curl

curl --request POST \
  --url https://your-scope.example.com/api/v1/skills \
  --header 'Content-Type: application/json' \
  --data '{
  "source": "vercel-labs/agent-skills",
  "skillName": "vercel-react-best-practices",
  "name": "React Best Practices",
  "origin": "manual"
}'

JS (fetch)

const url = 'https://your-scope.example.com/api/v1/skills';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"source":"vercel-labs/agent-skills","skillName":"vercel-react-best-practices","name":"React Best Practices","origin":"manual"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Python

import requests

url = "https://your-scope.example.com/api/v1/skills"

payload = {
    "source": "vercel-labs/agent-skills",
    "skillName": "vercel-react-best-practices",
    "name": "React Best Practices",
    "origin": "manual"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Go

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://your-scope.example.com/api/v1/skills"

  payload := strings.NewReader("{\n  \"source\": \"vercel-labs/agent-skills\",\n  \"skillName\": \"vercel-react-best-practices\",\n  \"name\": \"React Best Practices\",\n  \"origin\": \"manual\"\n}")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

Java

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"source\": \"vercel-labs/agent-skills\",\n  \"skillName\": \"vercel-react-best-practices\",\n  \"name\": \"React Best Practices\",\n  \"origin\": \"manual\"\n}");
Request request = new Request.Builder()
  .url("https://your-scope.example.com/api/v1/skills")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

C#

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Post,
    RequestUri = new Uri("https://your-scope.example.com/api/v1/skills"),
    Content = new StringContent("{\n  \"source\": \"vercel-labs/agent-skills\",\n  \"skillName\": \"vercel-react-best-practices\",\n  \"name\": \"React Best Practices\",\n  \"origin\": \"manual\"\n}")
    {
        Headers =
        {
            ContentType = new MediaTypeHeaderValue("application/json")
        }
    }
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

| Field | Type | Required | Description | | --- | --- | --- | --- | | source | string | yes | GitHub owner/repo. | | skillName | string | yes | Skill directory name in the repo. | | name | string | yes | Human-readable display name (1–64 chars). | | description | string | no | Free-form description. | | origin | string | yes | "manual" for hand-entered skills, "skills-sh" for imports from the registry. |

The API returns 201 for a new import or 200 if the skill already exists (upsert). After saving, Scope auto-resolves the latest revision from GitHub in the background.

What happens during resolution

When a skill is imported (or when you trigger resolution manually), Scope:

1. Searches the GitHub repository for the skill directory in the well-known paths listed above.
2. Finds the latest commit that touched that directory.
3. Downloads SKILL.md and any supporting files.
4. Parses the YAML frontmatter (name, description, license, compatibility, allowedTools).
5. Packages the files into a .tar.gz archive and uploads it to blob storage.
6. Stores a skill revision record keyed by source/skillName@commitHash.

The commit hash makes the revision immutable — the same ref always points to the same code.

Retry failed resolution

If auto-resolution failed at import time you can retry from the Portal (click Resolve on the skill detail page) or via the API:

curl

curl --request POST \
  --url https://your-scope.example.com/api/v1/skills/vercel-labs/agent-skills/vercel-react-best-practices/resolve

JS (fetch)

const url = 'https://your-scope.example.com/api/v1/skills/vercel-labs/agent-skills/vercel-react-best-practices/resolve';
const options = {method: 'POST'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Python

import requests

url = "https://your-scope.example.com/api/v1/skills/vercel-labs/agent-skills/vercel-react-best-practices/resolve"

response = requests.post(url)

print(response.json())

Go

package main

import (
  "fmt"
  "net/http"
  "io"
)

func main() {

  url := "https://your-scope.example.com/api/v1/skills/vercel-labs/agent-skills/vercel-react-best-practices/resolve"

  req, _ := http.NewRequest("POST", url, nil)

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

Java

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://your-scope.example.com/api/v1/skills/vercel-labs/agent-skills/vercel-react-best-practices/resolve")
  .post(null)
  .build();

Response response = client.newCall(request).execute();

C#

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Post,
    RequestUri = new Uri("https://your-scope.example.com/api/v1/skills/vercel-labs/agent-skills/vercel-react-best-practices/resolve"),
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

Using an imported skill

Once imported, the skill appears in the skill picker wherever you configure a profile or submit a run. You can select it and optionally pin a specific revision (commit hash).

In JSON payloads, reference it in the skillRevisions array:

{
  "skillRevisions": [
    "vercel-labs/agent-skills/vercel-react-best-practices"
  ]
}

Unpinned references are resolved to the latest commit at profile-version or run-creation time and stored in their pinned form (slug@commitHash). See Using MCP servers, skills & extensions → Skills for details on pinning and delivery.

Deleting a skill

From the Portal, click the delete icon on the Skills list. Via the API:

curl

curl --request DELETE \
  --url https://your-scope.example.com/api/v1/skills/vercel-labs/agent-skills/vercel-react-best-practices

JS (fetch)

const url = 'https://your-scope.example.com/api/v1/skills/vercel-labs/agent-skills/vercel-react-best-practices';
const options = {method: 'DELETE'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Python

import requests

url = "https://your-scope.example.com/api/v1/skills/vercel-labs/agent-skills/vercel-react-best-practices"

response = requests.delete(url)

print(response.json())

Go

package main

import (
  "fmt"
  "net/http"
  "io"
)

func main() {

  url := "https://your-scope.example.com/api/v1/skills/vercel-labs/agent-skills/vercel-react-best-practices"

  req, _ := http.NewRequest("DELETE", url, nil)

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

Java

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://your-scope.example.com/api/v1/skills/vercel-labs/agent-skills/vercel-react-best-practices")
  .delete(null)
  .build();

Response response = client.newCall(request).execute();

C#

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Delete,
    RequestUri = new Uri("https://your-scope.example.com/api/v1/skills/vercel-labs/agent-skills/vercel-react-best-practices"),
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

Deletion is a soft delete (HTTP 204). The skill and its revisions are hidden but not destroyed. Existing runs that used the skill are unaffected.

Skill format reference

Scope supports the Agent Skills specification. A skill is a directory whose name matches the skill name, containing at minimum a SKILL.md file:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...

SKILL.md

The file starts with YAML frontmatter followed by a Markdown body containing the agent instructions:

---
name: my-skill
description: What this skill does and when to use it.
---

Step-by-step instructions for the agent.

Required fields:

| Field | Constraints | | --- | --- | | name | 1–64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens. Must match the parent directory name. | | description | 1–1 024 chars. Describes what the skill does and when to activate it. |

Optional fields:

| Field | Constraints | | --- | --- | | license | License name or reference to a bundled license file. | | compatibility | 1–500 chars. Environment requirements (intended product, system packages, network access). | | metadata | Arbitrary string key-value map for additional properties. | | allowed-tools | Space-separated tool names the skill may use (experimental). |

The Markdown body after the frontmatter is loaded when the agent activates the skill. Keep it under 500 lines; move detailed reference material into files under references/.

For the complete specification — including progressive disclosure, file referencing, and validation — see agentskills.io/specification.

See also

• Using MCP servers, skills & extensions
• Defining profiles
• Profile schema → skillRevisions