DOCSEARCHbyAlgolia
Submit Docs

lich-skills

repository·main·Indexed 42 days ago

https://github.com/lichamnesia/lich-skills

A collection of engineering-focused mental models and utility skills for AI coding agents including Claude Code, Gemini CLI, and OpenAI Codex. It provides structured loops for spec-driven development, scientific-method debugging (debug-hypothesis), research aggregation (wiki-aggregate), and a 'go-no-go' decision-making framework to prevent sunk cost fallacy. Version 0.1.0 includes specialized tools for Tavily search, GA4 analysis, and Nano Banana image generation.

Tokens
37.3K
Snippets
68
Records
145
Agent score
50%

What's inside lich-skills

  1. Overview of available lich-skills

    main

    The lich-skills repository provides a collection of specialized workflows and tools for AI agents.

    Core Workflow Skills

    • skills-map: The router. Maps skills to work phases (Decide → Spec → Build → etc.) and helps pick the right skill.
    • go-no-go: Stage 0 gate. Decides if a project should start based on 5 framework gates (Differentiation, Audience-Market Fit, etc.).
    • spec-driven-dev: Full SDLC workflow (Spec → Plan → Build → Test → Review → Ship).
    • debug-hypothesis: Scientific-method debugging (Observe → Hypothesize → Experiment → Conclude).
    • build-until-pass: A bounded self-correcting loop that runs build/test commands and applies fixes until an exit code 0 is achieved (max 10 attempts).

    Research & Data Skills

    • wiki-aggregate: Aggregates $N \ge 3$ research artifacts into a structured pack with provenance.
    • tavily-search: Web search and content extraction via the Tavily API.
    • google-analytics: Analyzes GA4 data and generates SEO daily reports. Requires GOOGLE_ANALYTICS_PROPERTY_ID and a service-account JSON.

    Specialized Agentic Skills

    • subagent-brief: Disciplined prompt compression for spawning subagents (target $\le 200$ words).
    • nano-banana: Text-to-image and image editing via Google's Nano Banana 2.
    • frontend-design: Production-grade frontend interface construction.

    Note: All skills read credentials from environment variables (e.g., TAVILY_API_KEY, GEMINI_API_KEY) and never use hardcoded secrets.

  2. Overview of lich-skills capabilities

    main

    The lich-skills repository provides a collection of high-leverage engineering skills designed for AI agents like Claude Code, Gemini CLI, and OpenAI Codex. These skills focus on engineering judgment and structured workflows.

    Core Workflows

    • spec-driven-dev: A full software development lifecycle (Spec → Plan → Build → Test → Review → Ship).
    • debug-hypothesis: A scientific debugging loop (Observe → Hypothesize → Experiment → Conclude) designed to prevent AI from making blind, unguided changes.
    • wiki-aggregate: An agentic aggregation protocol for researching $N$ sources and producing a structured pack where every claim includes a path:line_number for traceability.

    Available Skills

    SkillPurpose
    skills-mapThe router. Use this to find the right skill for your current task stage.
    spec-driven-devFull SDLC management.
    debug-hypothesisScientific debugging with a mandatory DEBUG.md evidence chain.
    wiki-aggregateAggregates $N \ge 3$ sources into a structured pack with traceability.
    tavily-searchWeb search and content extraction via Tavily API.
    nano-bananaImage generation and editing using Google Nano Banana 2.
    frontend-designProduction-grade UI design guidance.
    google-analyticsGA4 data analysis and automated SEO reporting.
    build-until-passA self-correction loop that runs build/test commands until an exit code 0 is achieved or a limit is reached.

    Note: All skills retrieve credentials from environment variables (e.g., TAVILY_API_KEY, GEMINI_API_KEY) and never hardcode them.

  4. What is the wiki-aggregate skill and when to use it

    main

    The wiki-aggregate skill is a protocol for agentic aggregation of long-horizon research material. Instead of concatenating all sources into a single prompt (which causes token explosion and attention collapse), it treats $N$ source files as a queryable environment that a lite agent navigates using tools like inspect, search, and synthesize.

    When to Use

    • You have 3 to 30 raw research artifacts (notes, transcripts, research dumps) on a single topic.
    • You require claims with exact path:line provenance.
    • You need to surface cross-source contradictions explicitly.

    When NOT to Use

    • $N < 3$: The protocol overhead is too high; summarize manually instead.
    • $N > 30$: The tool call budget will likely be exhausted; narrow the scope or batch by sub-topic.
    • Sources are not yet collected: This is a synthesis tool, not a research tool.
    • One-shot Q&A is sufficient: Use a reactive wiki-ask-style skill instead.

  5. What is skills-map and how does it route tasks?

    main

    The skills-map is a meta-skill that acts as a router and decision tree for the lich-skills collection. Instead of performing work directly, it solves the 'discovery problem' by mapping every available skill to a specific work phase. It determines which skill should be used for a given task and provides the correct ordering when a task requires a chain of multiple skills.

    It is triggered:

    • At the start of any non-trivial task, before tools are selected.
    • When explicitly queried with commands like /skills-map, "which skill should I use", or "what skills do I have".
    • Whenever the selection of a specific skill is in doubt.

  6. How the go-no-go decision process works

    main

    The go-no-go skill follows an eight-step rigorous process to validate a project idea:

    1. Step 0: Pre-flight Memory Check (MANDATORY): The skill searches your memory store (default: ~/.go-no-go/journal.md) for similar past attempts. If found, you must provide a structural reason why this time is different (e.g., a new asset or partner), not just a personal one (e.g., "I'll try harder").
    2. Step 1: Hypothesis with Confidence Number: The skill states its understanding of your intent and assigns a confidence percentage.
    3. Step 2: One Question at a Time: The skill asks one question at a time, providing a GUESS for your answer to speed up the process.
    4. Step 3: Listen for "want vs. should-want": The skill probes for buzzwords to find your actual motivation.
    5. Step 4: The Five Mandatory Framework Checks: You must pass all five (Differentiation, Audience–Market Fit, Acquisition Channel, Capacity, and 7-Factor Wedge). Any failure results in an automatic NO-GO unless a structural override is provided.
    6. Step 5: Enthusiasm Detector: If high enthusiasm is detected, a 24-hour PATTERN INTERRUPT is triggered, forcing a cooldown period.
    7. Step 6: Write the Commitment Doc: A public artifact is generated containing kill criteria (D14/D30/D60/D90 review gates) and pre-mortemed failure modes.
    8. Step 7: Final Confirmation: You must explicitly type GO to proceed.

    Handoff:

    • GO: Proceed to /spec (Stage 1).
    • NO-GO: The reasoning is saved to your journal for future memory checks.
    • PAUSED: Wait for the 24-hour cooldown to expire.

  7. Configure rule enforcement mechanisms

    main

    The enforcement field in the RULE.md frontmatter determines how a rule is validated within the project. Choose one of the following three modes:

    • doc: The rule is documented only. This is a temporary state for new rules; they should graduate to a more formal enforcement mode or be retired within 2 sprints.
    • review_checklist: The rule is added to templates/review/REVIEW.md §A.9. Reviewers are required to explicitly mark the rule as pass, fail, or n-a during code reviews.
    • lint: The rule is automated. This MUST be accompanied by a lint_rule pointer in the frontmatter that resolves to a concrete rule file. The governance-check.sh script is used to verify that this pointer is valid.

    When using enforcement: lint, you must provide the path to the rule implementation and a command that demonstrates the rule catching a violation.

    enforcement: lint
lint_rule: "scripts/lint/no-l0-to-l2.mjs"

  8. How Spec-Driven Development v2 differs from v1

    main

    Spec-Driven Development v2 is an evolution of v1 designed to support multi-day, multi-session execution. While v1 focuses on the core mechanics of development, v2 adds a structural wrapper to ensure continuity and governance over longer periods.

    What remains from v1:

    • The five-axis review process.
    • Rationalization tables.
    • Scope discipline.

    What v2 adds:

    • A hierarchical structure (Project $\rightarrow$ Sprint $\rightarrow$ Task $\rightarrow$ Review).
    • Formalized state management via STATE.json files.
    • An Artifact Registry for captured rules.
    • Governance and Orchestrator contracts to prevent project collapse.

    If a project is small enough to be completed in a single session, v2 effectively functions as v1 with additional documentation overhead, which acts as insurance against scope creep and loss of context.

  10. How the build-until-pass loop works

    main

    The build-until-pass skill enforces a disciplined, minimal-change loop for fixing build errors and prevents agents from performing massive, speculative rewrites.

    The Workflow:

    1. RUN CHECK: Execute the check.
    2. IF SUCCESS (exit 0): DONE.
    3. IF FAILURE (red):
      • Read the first error verbatim (including file:line).
      • Fix the smallest possible area (minimal diff).
      • Re-run.
      • Report using a one-line report format.

    Safety Mechanisms:

    • Max Attempts: If attempts exceed MAX (default 10), the agent must STOP, report what remains, and hand over to a human.
    • No Faking: The agent is strictly forbidden from 'faking green' (e.g., using @ts-ignore, deleting tests, or appending || true).

    For more details, see skills/build-until-pass/.

  11. How the spec-driven-dev loop works

    main

    The spec-driven-dev loop is a six-phase pipeline for executing a skill, acting as Stage 1 of the development process. Each phase has explicit exit criteria:

    1. DEFINE: Create Spec/PRD.
    2. PLAN: Define Tasks.
    3. BUILD: Implementation.
    4. TEST: Verification.
    5. REVIEW: Gate review.
    6. SHIP: Tagging.

    The loop includes a feedback/regression path from the Ship phase back to the Define phase.

    For more details, see skills/spec-driven-dev/.

  12. Adhere to the review round budget

    main

    To prevent infinite loops or unproductive grinding, each task has a soft budget of 5 rounds.

    If a task exceeds 5 rounds (current_round > 5):

    1. The Orchestrator MUST stop the process and surface the task to a human.
    2. Do not attempt to continue automated rounds. Instead, investigate if the task spec is incorrect, the scope is too large, or if the reviewer is incorrectly flagging non-critical style issues as Critical.