SKILL.mk — A Makefile-Format SKILL Document

This project proposes a specification for SKILL documents in Makefile format. These documents offer clear logical chains, low token consumption (on-demand loading), verifiability, and auditability.

Why Makefile Format

Makefile-format SKILL documents have the following advantages, making them well-suited for integration into Agent frameworks:

• Built-in Logical DAG: Most SKILLs implicitly contain a logical DAG, which is essentially a Plan Mode. Describing it with an explicit DAG not only reduces the token cost of descriptions, but also improves Agent execution accuracy and lowers error rates.

• On-Demand Loading: The meta information in SKILL.mk provides a keyword list, where each keyword directly corresponds to a Makefile target. Through a dedicated SKILL.mk loader tool, only the relevant Recipe context is loaded on demand. This effectively reduces token costs at Agent runtime.

• Strong Verifiability: SKILL.mk itself is verifiable and runnable, and also supports auditability (git tracking, invocation statistics, etc.). It is well-suited for self-evolution, especially since individual Recipes can be optimized independently.

• Easy Integration: Makefile is a battle-tested format. Makefile parsing tools are readily available and can be easily integrated into existing Agent frameworks.

Example: Web Search SKILL

Here we use the Web Search SKILL as an example to compare the two formats. Web Search is frequently used and sufficiently representative.

Standard SKILL.md Format

---
name: brave-search
description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content. Lightweight, no browser required.
---

# Brave Search

Web search and content extraction using the official Brave Search API. No browser required.

## Setup

Requires a Brave Search API account with a free subscription. A credit card is required to create the free subscription (you won't be charged).

1. Create an account at https://api-dashboard.search.brave.com/register
2. Create a "Free AI" subscription
3. Create an API key for the subscription
4. Add to your shell profile (`~/.profile` or `~/.zprofile` for zsh):
   ```bash
   export BRAVE_API_KEY="your-api-key-here"
   ```
5. Install dependencies (run once):
   ```bash
   cd {baseDir}
   npm install
   ```

## Search

```bash
{baseDir}/search.js "query"                         # Basic search (5 results)
{baseDir}/search.js "query" -n 10                   # More results (max 20)
{baseDir}/search.js "query" --content               # Include page content as markdown
{baseDir}/search.js "query" --freshness pw          # Results from last week
{baseDir}/search.js "query" --freshness 2024-01-01to2024-06-30  # Date range
{baseDir}/search.js "query" --country DE            # Results from Germany
{baseDir}/search.js "query" -n 3 --content          # Combined options
```

### Options

- `-n ` - Number of results (default: 5, max: 20)
- `--content` - Fetch and include page content as markdown
- `--country ` - Two-letter country code (default: US)
- `--freshness ` - Filter by time:
- `pd` - Past day (24 hours)
- `pw` - Past week
- `pm` - Past month
- `py` - Past year
- `YYYY-MM-DDtoYYYY-MM-DD` - Custom date range

## Extract Page Content

```bash
{baseDir}/content.js https://example.com/article
```

Fetches a URL and extracts readable content as markdown.

## Output Format

```
--- Result 1 ---
Title: Page Title
Link: https://example.com/page
Age: 2 days ago
Snippet: Description from search results
Content: (if --content flag used)
  Markdown content extracted from the page...

--- Result 2 ---
...
```

## When to Use

- Searching for documentation or API references
- Looking up facts or current information
- Fetching content from specific URLs
- Any task requiring web search without interactive browsing

SKILL.mk Format

---
name: brave-search
description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content. Lightweight, no browser required.
target: when-to-use setup query
---

when-to-use:
    Web search and content extraction using the official Brave Search API. No browser required.
    - Searching for documentation or API references
    - Looking up facts or current information
    - Fetching content from specific URLs
    - Any task requiring web search without interactive browsing

setup: when-to-use
    Requires a Brave Search API account with a free subscription. A credit card is required to create the free subscription (you won't be charged).
    1. Create an account at https://api-dashboard.search.brave.com/register
    2. Create a "Free AI" subscription
    3. Create an API key for the subscription

    4. Add to your shell profile (`~/.profile` or `~/.zprofile` for zsh):
    @export BRAVE_API_KEY="your-api-key-here"

    5. Install dependencies (run once):
    @cd {baseDir}
    @npm install

query: when-to-use setup options output_format
    @{baseDir}/search.js "query"                         # Basic search (5 results)
    @{baseDir}/search.js "query" -n 10                   # More results (max 20)
    @{baseDir}/search.js "query" --content               # Include page content as markdown
    @{baseDir}/search.js "query" --freshness pw          # Results from last week
    @{baseDir}/search.js "query" --freshness 2024-01-01to2024-06-30  # Date range
    @{baseDir}/search.js "query" --country DE            # Results from Germany
    @{baseDir}/search.js "query" -n 3 --content          # Combined options
    @{baseDir}/content.js https://example.com/article    # Fetches a URL and extracts readable content as markdown.

options:
    `-n ` - Number of results (default: 5, max: 20)
    `--content` - Fetch and include page content as markdown
    `--country ` - Two-letter country code (default: US)
    `--freshness ` - Filter by time:
    - `pd` - Past day (24 hours)
    - `pw` - Past week
    - `pm` - Past month
    - `py` - Past year
    `YYYY-MM-DDtoYYYY-MM-DD` - Custom date range

output_format:
    --- Result 1 ---
    Title: Page Title
    Link: https://example.com/page
    Age: 2 days ago
    Snippet: Description from search results
    Content: (if --content flag used)
    Markdown content extracted from the page...
    --- Result 2 ---
    ...

Comparison

* Requires a dedicated Agent tool. Without such tooling support, SKILL.mk can also serve as a drop-in replacement for SKILL.md files.

1.0 Specification

Format Comparison

We tested a complete SKILL collection (from the well-known “Skills for Real Engineers” — https://github.com/mattpocock/skills) using the Makefile format. It not only improves logical structure and readability, but more importantly, these SKILL.make files are well-suited for auditing (git tracking, invocation statistics) and lay a solid foundation for Evolution Engineering.

You can use convert.sh to reproduce this conversion. The comparison statistics are as follows:

File                                       SKILL.md   SKILL.mk   Change
---------------------------------------- ---------- ---------- --------
caveman                                        1916       1982      +3%
design-an-interface                            3366       2681     -20%
domain-model                                   3512       2902     -17%
edit-article                                    721        660      -8%
git-guardrails-claude-code                     2312       2162      -6%
github-triage                                 10089       9299      -7%
improve-codebase-architecture                  5509       4232     -23%
migrate-to-shoehorn                            2795       1279     -54%
obsidian-vault                                 1511       1423      -5%
qa                                             4965       4686      -5%
request-refactor-plan                          2711       2806      +3%
scaffold-exercises                             3589       2768     -22%
setup-pre-commit                               2261       2599     +14%
tdd                                            4211       3006     -28%
to-issues                                      2737       2536      -7%
to-prd                                         2460       2417      -1%
triage-issue                                   3783       3738      -1%
ubiquitous-language                            4890       2515     -48%
write-a-skill                                  3056       2760      -9%

TOTAL                                         66394      56451     -14%

Status

This is a proof-of-concept specification. It is designed to be compatible with most Agent Harness implementations.

License

MIT