Skip to content
Back to search

SKILL.mk

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/teaonly--skill-mk/badge.svg)](/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)

  1. # SKILL.mk — A Makefile-Format SKILL Document
  2. 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.
  3. ## Why Makefile Format
  4. Makefile-format SKILL documents have the following advantages, making them well-suited for integration into Agent frameworks:
  5. - **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.
  6. - **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.
  7. - **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.
  8. - **Easy Integration**: Makefile is a battle-tested format. Makefile parsing tools are readily available and can be easily integrated into existing Agent frameworks.
  9. ## Example: Web Search SKILL
  10. Here we use the Web Search SKILL as an example to compare the two formats. Web Search is frequently used and sufficiently representative.
  11. ### Standard SKILL.md Format
  12. ````markdown
  13. ---
  14. name: brave-search
  15. description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content. Lightweight, no browser required.
  16. ---
  17. # Brave Search
  18. Web search and content extraction using the official Brave Search API. No browser required.
  19. ## Setup
  20. 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).
  21. 1. Create an account at https://api-dashboard.search.brave.com/register
  22. 2. Create a "Free AI" subscription
  23. 3. Create an API key for the subscription
  24. 4. Add to your shell profile (`~/.profile` or `~/.zprofile` for zsh):
  25. ```bash
  26. export BRAVE_API_KEY="your-api-key-here"
  27. ```
  28. 5. Install dependencies (run once):
  29. ```bash
  30. cd {baseDir}
  31. npm install
  32. ```
  33. ## Search
  34. ```bash
  35. {baseDir}/search.js "query" # Basic search (5 results)
  36. {baseDir}/search.js "query" -n 10 # More results (max 20)
  37. {baseDir}/search.js "query" --content # Include page content as markdown
  38. {baseDir}/search.js "query" --freshness pw # Results from last week
  39. {baseDir}/search.js "query" --freshness 2024-01-01to2024-06-30 # Date range
  40. {baseDir}/search.js "query" --country DE # Results from Germany
  41. {baseDir}/search.js "query" -n 3 --content # Combined options
  42. ```
  43. ### Options
  44. - `-n <num>` - Number of results (default: 5, max: 20)
  45. - `--content` - Fetch and include page content as markdown
  46. - `--country <code>` - Two-letter country code (default: US)
  47. - `--freshness <period>` - Filter by time:
  48. - `pd` - Past day (24 hours)
  49. - `pw` - Past week
  50. - `pm` - Past month
  51. - `py` - Past year
  52. - `YYYY-MM-DDtoYYYY-MM-DD` - Custom date range
  53. ## Extract Page Content
  54. ```bash
  55. {baseDir}/content.js https://example.com/article
  56. ```
  57. Fetches a URL and extracts readable content as markdown.
  58. ## Output Format
  59. ```
  60. --- Result 1 ---
  61. Title: Page Title
  62. Link: https://example.com/page
  63. Age: 2 days ago
  64. Snippet: Description from search results
  65. Content: (if --content flag used)
  66. Markdown content extracted from the page...
  67. --- Result 2 ---
  68. ...
  69. ```
  70. ## When to Use
  71. - Searching for documentation or API references
  72. - Looking up facts or current information
  73. - Fetching content from specific URLs
  74. - Any task requiring web search without interactive browsing
  75. ````
  76. ### SKILL.mk Format
  77. ````makefile
  78. ---
  79. name: brave-search
  80. description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content. Lightweight, no browser required.
  81. target: when-to-use setup query
  82. ---
  83. when-to-use:
  84. Web search and content extraction using the official Brave Search API. No browser required.
  85. - Searching for documentation or API references
  86. - Looking up facts or current information
  87. - Fetching content from specific URLs
  88. - Any task requiring web search without interactive browsing
  89. setup: when-to-use
  90. 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).
  91. 1. Create an account at https://api-dashboard.search.brave.com/register
  92. 2. Create a "Free AI" subscription
  93. 3. Create an API key for the subscription
  94. 4. Add to your shell profile (`~/.profile` or `~/.zprofile` for zsh):
  95. @export BRAVE_API_KEY="your-api-key-here"
  96. 5. Install dependencies (run once):
  97. @cd {baseDir}
  98. @npm install
  99. query: when-to-use setup options output_format
  100. @{baseDir}/search.js "query" # Basic search (5 results)
  101. @{baseDir}/search.js "query" -n 10 # More results (max 20)
  102. @{baseDir}/search.js "query" --content # Include page content as markdown
  103. @{baseDir}/search.js "query" --freshness pw # Results from last week
  104. @{baseDir}/search.js "query" --freshness 2024-01-01to2024-06-30 # Date range
  105. @{baseDir}/search.js "query" --country DE # Results from Germany
  106. @{baseDir}/search.js "query" -n 3 --content # Combined options
  107. @{baseDir}/content.js https://example.com/article # Fetches a URL and extracts readable content as markdown.
  108. options:
  109. `-n <num>` - Number of results (default: 5, max: 20)
  110. `--content` - Fetch and include page content as markdown
  111. `--country <code>` - Two-letter country code (default: US)
  112. `--freshness <period>` - Filter by time:
  113. - `pd` - Past day (24 hours)
  114. - `pw` - Past week
  115. - `pm` - Past month
  116. - `py` - Past year
  117. `YYYY-MM-DDtoYYYY-MM-DD` - Custom date range
  118. output_format:
  119. --- Result 1 ---
  120. Title: Page Title
  121. Link: https://example.com/page
  122. Age: 2 days ago
  123. Snippet: Description from search results
  124. Content: (if --content flag used)
  125. Markdown content extracted from the page...
  126. --- Result 2 ---
  127. ...
  128. ````
  129. ### Comparison
  130. | Aspect | SKILL.md | SKILL.mk |
  131. | ------ | -------- | -------- |
  132. | Full Load | Loaded all at once, 2165 characters | Loaded all at once, only 2014 characters — 7% reduction |
  133. | On-Demand Load * | Not supported | Probe-load `readme` only, 313 characters — 85% reduction |
  134. | Auditability * | Entire file as unit, no decomposition | Recipe-level invocation tracking, individual success rates |
  135. \* Requires a dedicated Agent tool. Without such tooling support, SKILL.mk can also serve as a drop-in replacement for SKILL.md files.
  136. ## 1.0 Specification
  137. | # | Rule | Description |
  138. | - | ---- | ----------- |
  139. | 1 | On-Demand Loading | `target = []` means full load; `target = ['readme']` means load only `readme` and its dependencies |
  140. | 2 | Recipe Definition | A recipe is multi-line text where each line starts with `\t`; the target name must be a string without spaces |
  141. | 3 | Recipe Loading | Full loading form: `name:[dep1 dep2]\n\tline1\n\tline2\n`; recipes are loaded in definition order |
  142. | 4 | Other | Aside from recipe loading, no other content from the SKILL.mk file is loaded |
  143. ## Format Comparison
  144. 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.
  145. You can use `convert.sh` to reproduce this conversion. The comparison statistics are as follows:
  146. ```txt
  147. File SKILL.md SKILL.mk Change
  148. ---------------------------------------- ---------- ---------- --------
  149. caveman 1916 1982 +3%
  150. design-an-interface 3366 2681 -20%
  151. domain-model 3512 2902 -17%
  152. edit-article 721 660 -8%
  153. git-guardrails-claude-code 2312 2162 -6%
  154. github-triage 10089 9299 -7%
  155. improve-codebase-architecture 5509 4232 -23%
  156. migrate-to-shoehorn 2795 1279 -54%
  157. obsidian-vault 1511 1423 -5%
  158. qa 4965 4686 -5%
  159. request-refactor-plan 2711 2806 +3%
  160. scaffold-exercises 3589 2768 -22%
  161. setup-pre-commit 2261 2599 +14%
  162. tdd 4211 3006 -28%
  163. to-issues 2737 2536 -7%
  164. to-prd 2460 2417 -1%
  165. triage-issue 3783 3738 -1%
  166. ubiquitous-language 4890 2515 -48%
  167. write-a-skill 3056 2760 -9%
  168. TOTAL 66394 56451 -14%
  169. ```
  170. ## Status
  171. This is a **proof-of-concept** specification. It is designed to be compatible with most Agent Harness implementations.
  172. ## License
  173. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.