Prioritized P0–P3 Action Roadmap for llm-skills

Direct, actionable initiatives derived from combining empirical benchmarks with the codebase audit of /home/mason/repos/llm-skills.

3-Tier Progressive Disclosure & Architecture Specification

The open standard (agentskills.io) and Antigravity Customization engine enforce lazy-loading across three discrete tiers to protect model attention and avoid the "Composition Cliff":

flowchart LR
    subgraph T1["Tier 1: Catalog (Session Start)"]
        direction TB
        M["YAML Frontmatter: name + description"]
        T["~50-100 tokens / skill"]
    end
    subgraph T2["Tier 2: Instructions (On Activation)"]
        direction TB
        B["SKILL.md Body"]
        L["< 500 lines / < 5,000 tokens\n<= 3 focused modules"]
    end
    subgraph T3["Tier 3: Resources (On-Demand 1-Hop)"]
        direction TB
        R["./references/*.md (Manuals)"]
        S["./scripts/*.{mjs,py} (CLI)"]
        A["./resources/* (Templates)"]
    end
    T1 -->|"Semantic Match"| T2
    T2 -->|"Single-Hop Relative Link"| T3
        

Empirical Evaluation & Automated Skill Training

Key conclusions from 2026 empirical studies testing agent skills across hundreds of real-world software engineering and tool-use tasks:

Converting Local benchmark-models into agy-skill-bench

The existing prod/benchmark-models harness (written in Python with SQLite and Jujutsu jj sandboxing) already computes non-dominated Pareto frontiers over pass_rate, avg_duration, and avg_cost_per_task. By adding a skill_variant parameter and paired A/B trial execution, it becomes a complete continuous skill evaluation harness for the local repository.

Comprehensive Local Codebase Audit (24 Skills)

Systematic static analysis of /home/mason/repos/llm-skills identified several high-leverage refactoring opportunities:

Adversarial Red-Team: Four Falsified Myths

Empirical evidence refutes common intuitive shortcuts in skill authoring and maintenance:

Security Architecture & Shared CLI Runtime (common/)

Because .gitignore globally excludes lib/, a shared runtime at /home/mason/repos/llm-skills/common/ establishes a robust foundation across Python and Node.js skills:

flowchart TD
    A["Skill Invocation (CLI / Agent)"] --> B["getSecret(KEY)"]
    B --> C{"Check Hierarchy"}
    C -->|"1"| D["CLI Flag (--api-key)"]
    C -->|"2"| E["Process Environment (process.env)"]
    C -->|"3"| F["~/.config/llm-skills/credentials.env (mode 0600)"]
    C -->|"4"| G["OS Keyring (secret-tool / D-Bus)"]
    F --> H["Return Decrypted Token"]
    G --> H
    D --> H
    E --> H
    H --> I["Pass into Child Process via env{} (NEVER in argv)"]
        

Standardized CLI Runtime Contract

• --json: Clean, unbuffered JSON stream on stdout (diagnostics to stderr).
• --dry-run: Simulates mutations without making external API calls or writes.
• doctor: Healthcheck command verifying credentials, file permissions, and API latency.
• Atomic writes: Always write to ${file}.tmp.${pid} and renameSync with mode 0600.

3-Layer Citation Audit & Verified Evidence Blackboard

Every citation in this research underwent a 3-layer audit: HTTP 200 verification (zero soft-404s/bot walls), NLI entailment, and verbatim quote verification: