@avcodes/mi - npm Package Compare versions

Comparing version

1.5.0

1.5.1

+45

skills/new-skill/SKILL.md

		---
		name: new-skill
		description: Write a new SKILL.md to teach yourself a procedure for a recurring task. Use when asked to "write a skill", "create a skill", "add a skill", "remember how to X", "make a procedure for X", or when you notice a task pattern worth recalling in future sessions.
		---

		A skill is a SKILL.md with YAML frontmatter (`name`, `description`) and a procedural body. The harness lists every skill's description in the system prompt so the model can match user intent to a name; bodies load on demand via `skill({name})`.

		Write a skill only when the task recurs, the procedure is non-obvious, and a description can match unseen phrasings. For one-off work, just do it. `skill()` first — never duplicate an existing skill.

		## Where it goes

		Write to `~/.agents/skills/<name>/SKILL.md`. `<name>` is kebab-case, ideally one short word, and unique against the existing list (`skill()`).

		## Anatomy

		```
		---
		name: <kebab-case>
		description: <one line — pack with the user phrasings that should trigger this skill>
		---

		<terse procedural body: trigger condition, then steps, concrete commands>
		```

		The description is the only thing visible during skill selection. Include the verbs and phrases a user is likely to say ("write X", "fix Y", "check Z"), not an abstract summary. If it doesn't match the user's words, the skill never loads.

		The body is a procedure, not an essay. Lead with `Use when…` / `Skip if…`, then the steps. Aim for under 50 lines. Concrete bash commands beat prose. No preamble, no recap.

		## Procedure

		1. `skill()` to list — confirm nothing covers the task; read the closest match's body to be sure.
		2. Pick `<name>`.
		3. Write the file in one command:
		```
		mkdir -p ~/.agents/skills/<name> && cat > ~/.agents/skills/<name>/SKILL.md <<'EOF'
		---
		name: <name>
		description: <intent-rich one-liner>
		---

		<body>
		EOF
		```
		4. Verify: call `skill({name: '<name>'})` and check the body comes back. The harness reads disk on every call, so the new skill is loadable immediately. Do not skip this step — a typo in frontmatter silently breaks discovery.
		5. Auto-advertisement of the description in the system prompt only happens at `mi` startup — `/reset` keeps the existing system prompt. Restart `mi` to pick up new skills automatically; until then the model can still load it by explicit name.

+40

skills/self/SKILL.md

		---
		name: self
		description: Answer questions about how 'mi' (this agent) itself works — its source, config, skills layout, CLI flags, env vars, version — or modify its own behavior. Use for "how do you work", "where is your source/README", "what flags/env vars do you take", "edit yourself", or any introspection of the running harness.
		---

		You are `mi` — a single-file Node ESM agent (~29 LOC, one chat loop, two tools: `bash` and `skill`). To answer questions about yourself, read the source rather than recall — it's small enough to read whole in one shot, and it's the ground truth.

		## Where things live

		The harness sets `MI_PATH` to the running `index.mjs` at startup. From it you can derive everything else:

		- `$MI_PATH` — the source file (~29 lines).
		- `$(dirname $MI_PATH)` — the package root: `README.md`, `package.json`, `AGENTS.md`, `skills/`, `tests/`, `scripts/`.
		- `$(dirname $MI_PATH)/skills/<name>/SKILL.md` — bundled skills.
		- `~/.agents/skills/<name>/SKILL.md` — user skills (same format, optional).
		- `$PWD/AGENTS.md` — auto-appended to your system prompt at startup, when present. It's the per-repo context channel.

		## How you run

		- `mi` (REPL) · `mi -p '<prompt>'` (one-shot) · `mi -f <file>` (prepend file to system) · `mi -h` (help). Stdin pipes work: `echo ... \| mi`.
		- REPL command: `/reset` clears history (keeps system prompt).
		- Env: `OPENAI_API_KEY` (required), `MODEL` (default `gpt-5.4`), `OPENAI_BASE_URL` (default `https://api.openai.com`), `SYSTEM_PROMPT` (fully overrides built-in instructions; CWD/Date and skill descriptions still get appended).

		## Procedure

		1. Read the source first. `cat $MI_PATH` — it's 29 dense lines; the whole runtime is there. For a specific concern: `grep -n <keyword> $MI_PATH`.
		2. For the user-facing feature list / install / usage: `cat $(dirname $MI_PATH)/README.md`.
		3. For repo-specific invariants and editing rules: `cat $(dirname $MI_PATH)/AGENTS.md` — note the "29 loc is load-bearing" rule.
		4. To list available skills: call the `skill` tool with no `name` arg (returns `- name: description` bullets from both skill dirs).
		5. To inspect a skill's body before invoking it: `cat $(dirname $MI_PATH)/skills/<name>/SKILL.md` (or `~/.agents/skills/<name>/SKILL.md` for user skills).
		6. Version: `node -p "require('$(dirname $MI_PATH)/package.json').version"`.

		## Modifying yourself

		`index.mjs` is intentionally dense — every meaningful line is load-bearing for the "29 loc" identity claim (see `AGENTS.md`). Before editing:

		1. Read `AGENTS.md` and the current source.
		2. Make the change in-place; do not add new lines unless unavoidable. Prefer extending existing template literals, chaining expressions, or merging declarations.
		3. Verify with `cd $(dirname $MI_PATH) && npm run lines` — line count should not regress.
		4. Smoke-test with `node $MI_PATH -h` (loads the module without needing an API key).

+1

-1

index.mjs

		@@ -75,2 +75,2 @@ #!/usr/bin/env node

		readLine.on('close', () => process.exit(0)); while (true) { const input = await promptUser('\n> '); if (input === '/reset') { history.splice(1); continue; } if (input.trim()) { history.push({ role: 'user', content: input }); process.stdout.write('\x1b[90m─────\x1b[0m\n'); try { await run(history); } catch(e) { console.error('\x1b[31m✗ ' + e.message + '\x1b[0m'); history.pop(); } } }
		readLine.on('close', () => process.exit(0)); while (true) { const input = await promptUser('\n> '); if (input === '/reset') { history.splice(1); console.log('\x1b[90m✓ reset\x1b[0m'); continue; } if (input.trim()) { history.push({ role: 'user', content: input }); process.stdout.write('\x1b[90m─────\x1b[0m\n'); try { await run(history); } catch(e) { console.error('\x1b[31m✗ ' + e.message + '\x1b[0m'); history.pop(); } } }

+1

-1

package.json

		{
		"name": "@avcodes/mi",
		"version": "1.5.0",
		"version": "1.5.1",
		"description": "agentic coding in 29 loc. a loop, two tools, and an llm.",
		@@ -5,0 +5,0 @@ "type": "module",

+1

-1

README.md

		@@ -12,3 +12,3 @@ ![Splash image](./assets/splash.png)
		- `skill` tool loads `SKILL.md` playbooks from bundled `skills/` and `~/.agents/skills/` (descriptions auto-advertised in system prompt so the model matches tasks to skills)
		- bundled skills: `plan`, `tasks`, `delegate`, `verify`, `debug`, `tdd`
		- bundled skills: `plan`, `tasks`, `delegate`, `explore`, `refactor`, `review`, `verify`, `debug`, `tdd`, `new-skill`, `self`
		- accepts stdin via pipes (e.g. `echo "do this" \| mi`)
		@@ -15,0 +15,0 @@ - file context ingestion via `-f <file>` argument

@avcodes/mi - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics