SKILL.make: Makefile Styled Skill file.
Specification and reference implementation for Makefile-styled Agent Skills.
What is this?
SKILL.make brings the declarative, dependency-driven paradigm of Makefiles to the Agent Skills format. It replaces fuzzy prose with structured logic, turning SKILL.md into a reproducible execution graph.
Why Makefile styled SKILL file?
-
Token Efficient: Optimized syntax reduces SKILL file size by ~15%, saving costs and context window space. With manual optimization, context size can be reduced by more than 30%.
-
Dependency Resolution: The harness resolves the DAG (Directed Acyclic Graph) automatically. No more relying on an LLM to "guess" the next logical step.Uses the Target: Dependency + Recipe model to ensure Agents follow a strict execution order without skipping steps.
-
Highly Composable: Modularize skills by calling targets across different files—just like a professional build system.
-
Auditability and evolution — Lays the groundwork for auditable and evolvable SKILL implementations.
Rule Definitions
| Prefix | Type | Description |
|---|---|---|
VAR = val |
Variable | Define constants to reduce repetition. |
@ cmd |
Shell | Direct command-line instructions for execution. |
$ tool |
Invocable | Explicit calls to agent-defined tools/functions. |
? prompt |
Reasoning | Free-form prompts where the Agent decides the action. |
ifeq |
Logic | Conditional branching based on state or env vars. |
multi-line string |
Code snippet | Define code snippets using multi-line strings in Makefile syntax. |
A Simple Example
Below is a typical code-review skill written in SKILL.make format:
--- name: code-review description: A full code review workflow. --- ```makefile # Variables CODE_DIR = src/ # Target: review — run a full code review review: lint test summary lint: @ cd $(CODE_DIR) && eslint . --format json test: @ cd $(CODE_DIR) && npm test summary: lint test ? Based on lint errors and test failures, write a review summary. ``` ### Addtional info is also OK.
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.make Change ---------------------------------------- ---------- ---------- -------- caveman 1916 1714 -10% design-an-interface 3366 2789 -17% domain-model 3512 3376 -3% edit-article 721 692 -4% git-guardrails-claude-code 2312 1861 -19% github-triage 10089 8697 -13% improve-codebase-architecture 5509 4913 -10% migrate-to-shoehorn 2795 1328 -52% obsidian-vault 1511 1233 -18% qa 4965 4781 -3% request-refactor-plan 2711 2626 -3% scaffold-exercises 3589 2744 -23% setup-pre-commit 2261 1703 -24% tdd 4211 3212 -23% to-issues 2737 2027 -25% to-prd 2460 2092 -14% triage-issue 3783 3160 -16% ubiquitous-language 4890 4560 -6% write-a-skill 3056 2879 -5% TOTAL 66394 56387 -15%
Status
This is a proof-of-concept specification. This specification is designed to be compatible with most Agent Harness implementations.