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.

License

MIT