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.
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.
Here we use the Web Search SKILL as an example to compare the two formats. Web Search is frequently used and sufficiently representative.
---
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 <num>` - Number of results (default: 5, max: 20)
- `--content` - Fetch and include page content as markdown
- `--country <code>` - Two-letter country code (default: US)
- `--freshness <period>` - 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
---
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 <num>` - Number of results (default: 5, max: 20)
`--content` - Fetch and include page content as markdown
`--country <code>` - Two-letter country code (default: US)
`--freshness <period>` - 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 ---
...| Aspect | SKILL.md | SKILL.mk |
|---|---|---|
| Full Load | Loaded all at once, 2165 characters | Loaded all at once, only 2014 characters — 7% reduction |
| On-Demand Load * | Not supported | Probe-load readme only, 313 characters — 85% reduction |
| Auditability * | Entire file as unit, no decomposition | Recipe-level invocation tracking, individual success rates |
* Requires a dedicated Agent tool. Without such tooling support, SKILL.mk can also serve as a drop-in replacement for SKILL.md files.
| # | Rule | Description |
|---|---|---|
| 1 | On-Demand Loading | target = [] means full load; target = ['readme'] means load only readme and its dependencies |
| 2 | Recipe Definition | A recipe is multi-line text where each line starts with \t; the target name must be a string without spaces |
| 3 | Recipe Loading | Full loading form: name:[dep1 dep2]\n\tline1\n\tline2\n; recipes are loaded in definition order |
| 4 | Other | Aside from recipe loading, no other content from the SKILL.mk file is loaded |
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%This is a proof-of-concept specification. It is designed to be compatible with most Agent Harness implementations.