Back to search
SKILL.mk
SkillGitHub
Specification and Tools for Makefile-formatted Agent Skills.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/teaonly--skill-mk)HTML
<a href="/listings/teaonly--skill-mk"><img src="/api/listings/teaonly--skill-mk/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 227 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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
- ````markdown
- ---
- 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
- ````
- ### SKILL.mk Format
- ````makefile
- ---
- 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 ---
- ...
- ````
- ### Comparison
- | 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.
- ## 1.0 Specification
- | # | 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 |
- ## 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:
- ```txt
- 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](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.