mkskill

README

Overview

The problem: every project keeps a README.md, an AGENTS.md and a SKILL.md, and they all repeat the same core — overview, usage, rules. The same content over and over, drifting apart.

The cure: write the content once as markdown under _mkskill/, and let mkskill compose every view from it.

mkskill dogfoods the convention: this very file is generated from _mkskill/src/. README, AGENTS.md and SKILL.md all come from the same sections; the engine's per-section directives ride the namespaced mkskill: front matter key and are stripped on compose.

Install

go get github.com/ot4go/mkskill    # library
go install github.com/ot4go/mkskill/cmd/mkskill@latest    # CLI

The _mkskill/ folder

Every unit carries a _mkskill/ folder — the single place its docs are assembled from. The leading _ keeps the Go toolchain out (./..., go build, go vet, go mod tidy): the project stays clean and does not depend on mkskill.

_mkskill/
  mkskill.config.xml   # the unit tree: projects, meta, embed, preserve
  src/*.md             # the content sections — what compose reads
  alt/
    files/             # preserved destinations: mkskill's version, mirrored
    tips/              # starter recipes (mkskill tips)
    debug/             # scan radiography (-debug)
README.md              # ← generated
AGENTS.md              # ← generated
.claude/skills/<name>/SKILL.md   # ← generated
cmd/<x>/_mkskill/      # a nested unit per thing-with-docs (a CLI, …)

A unit is any folder with a _mkskill/: the project root and each nested unit the config declares (<child-project path="./cmd/x">). The root's views pull the children in with include: — the parent's document is the global one.

Using mkskill

Two ways: as a tool — the mkskill CLI deploys any repo's docs — and as a host face — a binary carries its composed docs and acts in its own name.

The tool:

mkskill build      # scan → prepare → resolve → deploy: write every artifact
mkskill check      # dry look: warnings, conflicts, section order
mkskill tips       # starter recipes by project-type → _mkskill/alt/tips/
mkskill -C . -generate-claude-skill -global   # this repo's skill → ~/.claude/skills/

-C <dir> points at another project; with a generate command the pointed repo speaks for itself, composed on the fly — no binary needed (a JS project installs its skill the same way).

The host wiring — <embed> generates MkskillSpec, the main checks it first:

if err, done := MkskillSpec.CheckParams(); done {
    return
} else if err != nil {
    fmt.Fprintf(os.Stderr, "error: %v\n", err)
    os.Exit(1)
}
// …not a mkskill command: the host's own argument handling…

Then mytool -generate-claude-skill -global installs the skill with no mkskill around, and MkskillSpec.Usage(true) lends the commands to the host's own help — no import of its own: the generated embed already brings everything.

The CLI

mkskill (the CLI)

The mkskill binary barely parses the command line and calls the compiler — the engine lives in github.com/ot4go/mkskill/compiler. It speaks with two voices:

• Its own: the generate commands act on mkskill's embedded docs — mkskill -generate-claude-skill -global installs mkskill's own skill.
• Any repo's: with -C <dir> the pointed repo speaks for itself, composed on the fly — no binary needed: mkskill -C . -generate-claude-skill -global installs a pure library's (or a JavaScript project's) skill just the same.

And as the deployer it builds the repo it stands in (or the one at -C): every artifact, from the _mkskill/ sources.

Commands

Deployer commands — the repo at -C, or the current folder:

build      scan + prepare + resolve + deploy: write every artifact
check      scan + resolve without writing: warnings, conflicts, order
scan       collect the sources only
prepare    materialize the collected sources into _mkskill/src
tips       write the starter recipes to _mkskill/alt/tips/ (by project-type)
version    print the version

The generate family is not hand-written: this table is the macro msk.skill.usage.full, expanded at compose time — in sync by construction:

-generate-claude-skill  [-dst f] [-global] [-force]
    write the Claude Code SKILL.md (-global installs ~/.claude/skills/<name>/SKILL.md)
-generate-agent-docs    [-dst f] [-force]
    write the agent-agnostic AGENTS.md
-generate-readme        [-dst f] [-force]
    write the README.md

Flags, anywhere on the line:

-C <dir>   act on that repo; with a generate command the repo speaks for itself
-log <f>   the run's record to a file (- for stdout, the default)
-debug     save the scan radiography to _mkskill/alt/debug/
-pretty    reformat the saved config (with -debug)
-q         silence the record

Wiring go generate

Go can't write source-tree files during go build; the hook is go generate. A unit regenerates its docs with the external tool — it never imports mkskill nor lists it in go.mod:

//go:generate go run github.com/ot4go/mkskill/cmd/mkskill@latest build

-generate-claude-skill -global stays a manual, per-machine act — it writes to your home, never to the repo.

License

MIT — see LICENSE.

Documentation

Overview

Package mkskill is the minimal face a host application imports: its docs come already composed (the compiler package renders them at build time and the generated embed carries them in the binary); this package only handles the parameters — recognizing the generate commands on the host's command line, writing or installing the documents, and lending the usage text for the host's own help.

Index

• type Spec
  • func (s Spec) CheckParams() (err error, done bool)
  • func (s Spec) Dispatch(cmd string, args []string) (handled bool, err error)
  • func (s Spec) RunGenerateAgentDocs(args []string) error
  • func (s Spec) RunGenerateClaudeSkill(args []string) error
  • func (s Spec) RunGenerateReadme(args []string) error
  • func (s *Spec) Usage(detail bool) string

Types

type Spec

type Spec struct {
	Name        string // skill name; also the skill directory name
	Description string // the trigger text Claude uses to decide when to load the skill
	Readme      string // the composed README.md
	Agents      string // the composed AGENTS.md
	Skill       string // the composed SKILL.md, wrapper included
}

Spec is everything the host carries: its name, the trigger description, and the composed documents — ready to write, never rendered here.

func (Spec) CheckParams

func (s Spec) CheckParams() (err error, done bool)

CheckParams is the one-call host integration: it inspects os.Args and runs a generate command if the program was invoked as one. It returns done=true when a generate command ran successfully (the host should stop), err!=nil when a generate command was recognised but failed, and both zero when os.Args is not a generate command (so the host falls through to its own argument handling):

if err, done := Skill.CheckParams(); done {
	return
} else if err != nil {
	fmt.Fprintf(os.Stderr, "error: %v\n", err)
	os.Exit(1)
}
// …not a mkskill command: the host handles os.Args itself…

func (Spec) Dispatch

func (s Spec) Dispatch(cmd string, args []string) (handled bool, err error)

Dispatch routes the generate commands. They are flag-shaped (-generate-claude-skill, one or two dashes) so they never collide with the host's own subcommands; the bare form is accepted too. It returns handled=false for anything else so a host CLI can fall through to its own commands:

if ok, err := spec.Dispatch(cmd, args); ok { return err }

func (Spec) RunGenerateAgentDocs

func (s Spec) RunGenerateAgentDocs(args []string) error

RunGenerateAgentDocs parses [-dst f] [-force] and writes the composed AGENTS.md (default destination AGENTS.md).

func (Spec) RunGenerateClaudeSkill

func (s Spec) RunGenerateClaudeSkill(args []string) error

RunGenerateClaudeSkill parses [-dst f] [-global] [-force] and writes the composed SKILL.md. Default destination is the project-local .claude/skills/<name>/SKILL.md; -global writes ~/.claude/skills/<name>/SKILL.md (available from every project, no elevation — it is under the user's own home); -global and -dst are mutually exclusive.

func (Spec) RunGenerateReadme

func (s Spec) RunGenerateReadme(args []string) error

RunGenerateReadme parses [-dst f] [-force] and writes the composed README.md (default destination README.md).

func (*Spec) Usage

func (s *Spec) Usage(detail bool) string

Usage returns mkskill's command help for a host to embed in its own help, so it stays in sync as mkskill gains commands or flags. detail=false is the compact header (one aligned "name flags" line per command); detail=true adds a description line under each. Both have no leading indent or trailing newline — the host positions them. It is a method of Spec so a host's main needs no mkskill import of its own: the generated embed already brings the type, and MkskillSpec.Usage(true) just works.