Turn Your CLI Into Agent Skills: What I Learned Shipping 9 Installable Skills

Documentation is written for people who already decided to care. A skill is written for an agent that just got asked a question.

ZensInk ships 22 zero-dependency Python tools — keyword discovery, SERP-based difficulty, site audits, GEO readiness. The README documents every one of them. And still, the most common support question has always been some version of “which tool do I run for X?” Humans read docs top to bottom; agents don’t read them at all unless something tells them to.

So this week I restructured the package into 9 installable agent skills. Not 22 — nine jobs.

Skills are keyed to jobs, not tools

Nobody asks an agent to “run kgr_auto”. They ask “find low-competition keywords for my niche without paying for Ahrefs”. That sentence is the interface. So the grouping looks like this:

• keyword-research — discovery + clustering + volume + KGR scoring (5 tools, one job)
• keyword-difficulty — SERP structure analysis with a go/no-go call
• search-intent — keyword-based and SERP-based, cross-validated
• site-audit — technical audit on dist/ + on-page scoring + draft QC
• competitor-gap — sitemap diff into a prioritized content matrix
• rank-tracking — SQLite rank history + GSC performance + DR lookups
• reddit-keywords — blue-ocean demand mining
• geo-readiness — robots AI-policy audit + llms.txt generation + Query Fan-out planning
• zens-ink — the whole toolkit plus the MCP server, for agents that want everything

Each SKILL.md has the same skeleton: when to use it, when NOT to use it, setup, exact commands with real output, decision rules for reading that output, and the next skill to reach for. The playbook layer is the part that takes an afternoon and is the part nobody can copy by wrapping your CLI — they’d have to know how the output should be interpreted.

Field note 1: a root SKILL.md hides your other skills

First push, first test:

$ npx skills add ZensInk/zens-ink-seo-package --list
◇  Found 1 skill
│    zens-ink

One skill. I’d just shipped nine.

The skills CLI scans a repo, and if it finds a SKILL.md at the repo root, it treats the whole repository as that single skill and returns — nested skills are never scanned unless the user knows to pass --full-depth. Reading the CLI source confirmed it: parse root skill, if found and no full-depth flag, return skills.

The fix: move the root SKILL.md into the tree (skills/zens-ink/SKILL.md). Now the default scan walks the skills/ container three levels deep and finds all nine. Most repos with a root SKILL.md and a skills/ folder are silently shipping one skill and hiding the rest.

Field note 2: frontmatter typos drop skills silently

After the restructure, the listing showed eight of nine. The missing one was keyword-research — the flagship.

The cause was one leading space:

---
name: keyword-research
 description: >-     # ← that space

The YAML parser fails, the skill is skipped, and the CLI reports nothing. Eight skills, no error, no warning. If you ship skills, diff the listing count against the folder count every time — it’s the only check that catches this class of bug.

Field note 3: metadata.source is a citation surface

Every skill’s frontmatter carries:

metadata:
  version: 1.0.0
  author: ZensInk
  source: https://zens.ink/skills/#keyword-research
  license: MIT

That source line travels with every installed copy. When someone’s agent loads the skill mid-session, the URL is right there in the context — the agent cites it, the human sees it, and neither of them had to find us through a search engine first.

This matters more than it looks. We run a weekly GEO probe on zens.ink: 15 buyer questions against a live LLM search stack, plus the same set against Google’s top 10. Current baseline: 0/15 AI citations, 0/15 SERP. The plumbing is complete — llms.txt, llms-full.txt, MCP manifest, permissive ai-input robots policy — and it doesn’t matter, because AI engines mostly cite what retrieval feeds them, and a young domain doesn’t get retrieved.

Skills route around the retrieval bottleneck. The content rides into the agent session directly, carried by an installer instead of a SERP. It’s the same bet the 394-star skills repos are making: the agent ecosystem is a distribution channel that doesn’t check your domain rating at the door.

The real install session

$ npx skills add ZensInk/zens-ink-seo-package --skill keyword-research

◇  Source: https://github.com/ZensInk/zens-ink-seo-package.git
◇  Repository cloned
◇  Found 9 skills
└  Done!

$ python3 -m zens_ink.keyword_research "ai seo tools"

============================================================
  Keyword: ai seo tools  (en)
============================================================

  In autocomplete : YES
  Activity level  : high-activity (10 variants)

  Suggestions:
    ai seo tools
    ai seo tools for small business
    ai seo tools free
    ...

One command, one job, zero explanation needed from the human. That’s the entire point.

If you maintain a CLI

The pattern generalizes to any CLI toolchain:

1. List the sentences users actually say when they need your tools (“audit my build”, “how hard is this keyword”).
2. One skill per sentence; bundle every tool that sentence needs.
3. Write the interpretation rules, not just the commands — KGR under 0.25 means write it, a DR gap over 20 means don’t bother.
4. Put the skills in a skills/ container, and make sure no SKILL.md sits at the repo root.
5. Diff the installer’s listing count against your folder count before you announce.
6. Carry metadata.source in every frontmatter — it’s the one line that turns distribution into citation surface.

The tools were always the hard part. The skills layer took a day, and it’s the day that made the tools reachable by something other than a motivated human.

FAQ

What is an agent skill, exactly?

A folder with a SKILL.md file that follows the Agent Skills spec (agentskills.io). The frontmatter carries a name and a trigger-rich description; the body is instructions. Coding agents (Claude Code, Cursor, Codex, OpenClaw) read installed skills automatically and invoke them when the user's request matches the description. Installers like the Vercel skills CLI (npx skills add owner/repo) fetch them from GitHub, so a normal repository becomes a distribution channel.

Why group skills by job instead of by tool?

Because users describe jobs, not tools. Nobody asks an agent to 'run kgr_auto' — they ask 'find low-competition keywords without paid tools'. A skill keyed to that phrasing bundles every tool the job needs (discovery, clustering, volume, KGR scoring) plus the decision rules for reading the output. The tool list stays in the package; the skill is the interface.

Does shipping skills actually help AI-search visibility?

It builds retrieval surface that classic SEO cannot when your domain is young. Our weekly GEO probe shows zens.ink at 0/15 AI citations despite full plumbing (llms.txt, MCP manifest, AI-crawler policy) — because AI engines mostly cite what search retrieves, and a DR-21 domain doesn't get retrieved. Skills route around that: every installed SKILL.md carries metadata.source pointing at your site, and agents ingest the content directly instead of waiting for a search engine to rank it.