developer-assistant-template

A retrieval-first personal skill library for AI agents: your agents search a growing library of validated scripts + instructions BEFORE writing anything new, and every successful task can be crystallized back into the library. Models and harnesses stay swappable; the library is the asset that compounds.

Works with any MCP-capable harness (Claude Code, Cursor, Hermes Agent, ...), follows the agentskills.io SKILL.md convention, and ships three vendored public skill libraries (395+ skills) you update with one script.

The loop

1. Library-first. Before doing work, the agent calls search_library.
2. Write-on-miss. No hit: do the task normally.
3. Crystallize-on-success. Distill the completed task into a parameterized script + SKILL.md + test, and register_skill it. Registration is gated on the test passing.
4. Librarian pass (cron, cheap model): dedup, generalize, smoke-test, deprecate breakage.

Why: a frontier model authors a script once; a cheap model (or no model) executes it forever. Token spend becomes a durable asset instead of a recurring cost.

Quick start (standalone)

git clone --recurse-submodules https://github.com/dylanjamessnow/developer-assistant-template
cd developer-assistant-template
python3 lib/cli.py index          # build the search index (stdlib only)
python3 lib/cli.py search "profile a csv"
python3 lib/cli.py run csv-profile -- /path/to/file.csv
python3 lib/cli.py test --all

MCP server (requires pip install fastmcp) — add to your harness config, e.g. Claude Code .mcp.json:

{
  "mcpServers": {
    "skills": {
      "command": "python3",
      "args": ["/path/to/developer-assistant-template/mcp/server.py"]
    }
  }
}

Then add the harness rule to your CLAUDE.md / system prompt:

Before writing a script or doing mechanical multi-step work, call search_library first. If a skill covers it, run_script. If not, do the task, then distill it into a skill and register_skill with a passing test.

Recommended setup: private wrapper repo

Keep this template as a submodule of a private repo that owns YOUR skills — you get template updates with git pull, and your library stays private:

developer-assistant-you/          (private)
  template/                       (this repo, as a submodule)
  skills/                         (your skills -- register_skill writes here)
  taps.yaml                       (your roots first, template's after)
  .mcp.json

mkdir developer-assistant-you && cd developer-assistant-you && git init
git submodule add https://github.com/dylanjamessnow/developer-assistant-template template
git -C template submodule update --init
mkdir skills
cat > taps.yaml <<'EOF'
roots:
  - skills
  - template/skills
  - template/vendor/anthropic-skills
  - template/vendor/superpowers-skills
  - template/vendor/business-skills
EOF
python3 template/lib/cli.py index   # resolves your taps.yaml from cwd

The engine finds your taps.yaml by walking up from the working directory (or set SKILLS_HOME=/path/to/wrapper explicitly, e.g. in the MCP server's env). The first root listed is where new skills are registered. Add more roots for per-company/per-project overlays -- first root wins collisions.

Layout

skills/<name>/SKILL.md        # frontmatter (name, description, tags) + usage
skills/<name>/scripts/main.py # entrypoint; args in, stdout out, exit 0/1
skills/<name>/test.py         # smoke test; exit 0 = pass (doubles as health check)
lib/skills_lib.py             # index (SQLite FTS5), search, run, register
lib/cli.py                    # index|search|show|run|test  (zero deps)
mcp/server.py                 # FastMCP server: 5 meta-tools
vendor/                       # pinned upstream skill libraries (submodules)
scripts/update-vendors.sh     # bump vendors + reindex + test + review gate
docs/VENDORING.md             # vendoring mechanism, trust policy
taps.yaml                     # skill roots

Design rules

• Meta-tools, not one-tool-per-script. search_library, inspect_skill, run_script, register_skill, deprecate_skill. Thousands of skills never touch model context; only search hits do.
• Descriptions are the retrieval index. One line, verb-first, says when to use it. Bad descriptions = invisible skills.
• Scripts are stdlib-first. Declare third-party deps in frontmatter (deps:). Prefer none.
• No secrets in skills, ever. Scripts read credentials from environment variables; SKILL.md documents which ones.
• Vendor skills are third-party content. Search results carry a source label; treat non-core scripts as untrusted (see docs/VENDORING.md).

Security

• run_script executes with a timeout, cwd-isolated to the skill directory. For untrusted or vendored skills, run the whole MCP server inside Docker.
• Registration runs the submitted test before accepting; that is a correctness gate, not a security gate.

License

MIT for the template code. Vendored libraries under vendor/ keep their own licenses (see each submodule).