The Problem

AI coding assistants (Claude Code, Gemini CLI, Codex) fail in predictable ways: they bulldoze through a wrong debugging theory, skip verification, and produce unstructured output. Teams lack a repeatable workflow that forces disciplined engineering practices into the agent loop.

What This Does

lich-skills is a collection of agent skills—markdown instructions plus supporting scripts—that encode engineering judgment into reusable workflows. The core is skills/spec-driven-dev/, a six-phase SDLC loop (Spec → Plan → Build → Test → Review → Ship) with explicit exit criteria per phase. skills/debug-hypothesis/ enforces scientific-method debugging: observe, hypothesize, experiment in max-5-line tests, conclude. skills/wiki-aggregate/ runs agentic research across N sources, producing a structured pack with path:line provenance.

Each skill lives in its own folder with a SKILL.md defining behavior. Supporting scripts include skills/tavily-search/scripts/search.py for web search and skills/nano-banana/scripts/generate_image.py for image generation. The repo also ships a spec-driven-dev-v2 variant with governance and task-linting shell scripts.

How It Is Wired

This is a configuration-and-docs repository, not an application. The only JavaScript file, index.js, is a stub. Execution starts when an agent loads a SKILL.md file; the skills then invoke their companion scripts. The measured call graph shows 6 code files, 0 import edges, and no circular dependencies—each script runs standalone.

  • skills/spec-driven-dev-v2/scripts/governance-check.sh — validates process adherence (49 branch points over 122 lines)
  • skills/spec-driven-dev-v2/scripts/task-lint.sh — lints task definitions
  • skills/tavily-search/scripts/search.py — performs web searches
  • skills/nano-banana/scripts/generate_image.py — generates images

The wiring between SKILL.md files and scripts is convention-based, not code-coupled. There is no runtime orchestration layer; the agent reads instructions and calls scripts as needed.

How To Use It

Setup: Clone the repository and point your agent at it:

git clone https://github.com/moses-y/lich-skills

Configuration: No environment variables or API keys are required for the core skills. skills/tavily-search/ requires a Tavily API key when used. The .claude-plugin/ directory contains marketplace metadata for Claude Code integration.

Running it: This is not a standalone application. Load the skills into Claude Code, Gemini CLI, or Codex by referencing the SKILL.md files. The docs/ folder (claude-code-setup.md, codex-setup.md, gemini-cli-setup.md) documents per-tool setup.

Real-World Use

A team using Claude Code for feature work loads the spec-driven-dev skill. The agent produces a spec, plan, and task breakdown before writing code. Each commit is atomic and references the task. The debug-hypothesis skill kicks in when tests fail—the agent must list 3-5 candidate causes with evidence before changing code, preventing the common failure of thrashing on one wrong theory.

Code Health & Issues

Static analysis found 5 issues (0 critical, 1 high, 3 medium, 1 low):

  • High — Third-party GitHub Actions pinned to tags (gitleaks/gitleaks-action@v2) instead of commit SHAs. Tags can be moved, risking secret exfiltration. Fix: pin to 40-character SHAs.
  • Medium — No permissions declared in .github/workflows/ci.yml, so GITHUB_TOKEN inherits repository defaults.
  • Medium — No Dependabot or Renovate configured; dependency updates are manual.
  • Medium — No dependency vulnerability scan in CI.
  • Low — No timeout-minutes on CI jobs; a wedged step runs to the 6-hour platform default.

The analysis also flagged generate_image.py for opening files without a context manager, and both shell scripts for high branching density.

The Bottom Line

A well-structured skills collection that codifies real engineering discipline—spec-first development, hypothesis-driven debugging, provenance-tracked research. The lack of runtime code means low maintenance overhead. Teams using Claude Code or Codex who want repeatable, enforced workflows should adopt this. The CI hygiene issues are worth fixing before relying on the GitHub Actions pipeline.