Skill Pointer (SKILL.md)

A SKILL.md file is a structured markdown document with YAML frontmatter that describes a skill to an AI agent. There are two types: the core skill (platform entry point) and integration skills (per-service documentation).

Core skill

Installed by skillett login. This is the entry point that tells agents Skillett is available:

---
name: skillett
description: Skillett agent skills platform — run `skillett help` to discover available commands.
user-invocable: false
---

# Skillett

Skillett is installed. Run CLI commands to discover and execute agent skills.

    skillett help          # see all commands
    skillett skills        # list available integrations
    skillett run ...       # execute an endpoint

Frontmatter fields

Field	Type	Description
name	string	Skill identifier
description	string	One-line description for agent context
user-invocable	boolean	Whether the user can invoke directly (false for core)

Integration skills

Downloaded by skillett pull <integration>. These provide complete offline documentation:

---
name: skillett-github
version: 1.0.0
description: >
  GitHub integration — create and manage issues, pull requests, repositories,
  commits, and workflows.
argument-hint: "[repo] [action]"
user-invocable: true
disable-model-invocation: false
allowed-tools: Bash, Read, Grep, Glob
---

# GitHub

## Execution

POST https://api.skillett.dev/v1/github/{action_name}
Authorization: Bearer $SKILLETT_API_KEY

## Endpoints

| Resource | Folder | Actions |
|---|---|---|
| Issues | endpoints/issues/ | create_issue, list_issues_for_repo, ... |
| Pull Requests | endpoints/pull-requests/ | create_pull, list_pull, ... |

## Guides
- Authentication and scopes
- Pagination patterns
- Error handling
- Rate limits

## Workflows
- Triage New Issues
- PR Review Checklist

Integration frontmatter fields

Field	Type	Description
name	string	Skill identifier (e.g., skillett-github)
version	string	Semantic version
description	string	Multi-line description for agent context
argument-hint	string	Usage hint shown to agents
user-invocable	boolean	Whether the user can invoke directly
disable-model-invocation	boolean	Prevent automatic model invocation
allowed-tools	string	Tools the agent may use when executing

Endpoint files

Each endpoint has its own markdown file under endpoints/<category>/:

---
name: create_issue
method: POST
path: /repos/{owner}/{repo}/issues
param_mapping:
  repo: owner/repo → {owner}, {repo}
---

# Create Issue

Create an issue in a GitHub repository.

## Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| repo | string | Yes | Repository in owner/repo format |
| title | string | Yes | Issue title |

## Errors

| Code | Cause | Fix |
|---|---|---|
| 404 | Not Found | Verify repository exists |

The frontmatter is the single source of truth for the proxy layer — it defines the HTTP mapping and parameter transformations.