Stringing Skills Together: A Field Guide to Jeffrey's Skills.md (jsm)

What jsm Actually Is (and What It's Not)

Let me be direct: jsm (Jeffrey's Skills) is a CLI package manager for agent instructions, wrapped around a progressive disclosure file structure. That's the whole thing. The value proposition is not the markdown—it's the packaging, the versioning, and the discipline the structure imposes on both the agent and the developer who writes the prompts.

Here's how I'd frame it against what most people are doing today. A .cursorrules file is a flat text blob that gets dumped into the context window on every single turn. It's like reading the entire manual before you know what page you need. Enterprise registries like PromptLayer or Portkey solve a different problem entirely—they're for API developers who need observability, versioning, and A/B testing across models in production backend systems. That's not what a coding agent needs. It needs to know how to audit a codebase, not how to route inference requests with telemetry.

jsm sits in a third camp: structured, versioned, executable instruction packages for local agent workflows.

The architecture is the interesting part:

premium-skill/
├── SKILL.md
├── references/
└── assets/

SKILL.md is the front door—a scannable index that tells the agent what this skill is for, and crucially, when to pull deeper. The /references/ directory holds the actual recipes, the detailed procedures, the edge cases. /assets/ has templates and supporting files. The agent reads the front door first, and only loads what it actually needs.

Here's the execution flow:

flowchart TD
    A[Agent loads SKILL.md index] --> B{Does task need more detail?}
    B -->|Yes| C[Agent reads specific references/ files]
    B -->|No| D[Agent proceeds with SKILL.md guidance alone]
    C --> E{Need templates or artifacts?}
    E -->|Yes| F[Agent pulls necessary assets/ files]
    E -->|No| G[Agent proceeds with references loaded]
    F --> H[Self-test scripts and hooks execute]
    G --> H
    H --> I[Subagents dispatched for specific subtasks]
    I --> J[Final output validated against golden outputs]
    J --> K{Validation passed?}
    K -->|Yes| L[Task complete]
    K -->|No| M[Agent iterates or rolls back]

Now, the elephant in the room: this is a $20/month subscription. The markdown itself is not magic. Nothing about the file structure is proprietary. You can clone this exact pattern in your own private git repository with a simple shell script for the CLI behavior. The actual moat (I'd argue it's the only real moat) is the quality and maintenance of Jeffrey's curated workflows. The optimization loop, the bug hunting protocols, the auditing dispatchers—those are genuinely well-engineered instruction sets. But the packaging is trivially replicable.

What I'd watch for: procedural drift on lighter models. The workflows are densely nested—golden outputs, profiling formulas, multi-pass audits. A frontier model tracks those constraints reliably. A Flash-tier model running the same skill might skip the baselining step and jump straight to patching. The structure doesn't save you from model capability limits.

Progressive Disclosure: Why It Matters for Token Budgets

The mechanics are simple: you don't pay for context you don't use.

Here's the math. If a skill has five reference files at roughly 2,000 tokens each, and the agent only needs one of them to complete a task, you've saved about 8,000 tokens per invocation. Multiply that across a long session with many skill activations, and the savings compound. On a model like Gemini Flash where token costs are already low, this might not be the difference between viable and not viable—but on a frontier model at higher rates, it absolutely is.

But there's a failure mode I've seen repeatedly: the lazy agent problem. If SKILL.md is too abstract, or lacks explicit trigger phrases, the agent will try to guess the procedure instead of spending a tool call to read the actual recipe. It "knows" roughly what a codebase audit involves, so it improvises. The result is a degraded workflow that looks like it's following the skill but isn't.

My rule of thumb: every trigger phrase in SKILL.md should map to a specific reference file. If the agent encounters "hotspot profiling" it should know, unambiguously, to load references/profiling.md. If it encounters "golden output capture" it should load references/golden-outputs.md. No ambiguity, no guessing.

The other trap is context inflation across iterations. The hierarchy prevents blowout on step one, but as the agent ingests multiple deep files during a complex task—say, three references and two assets—the active context window fills up fast. Now you've got a problem: earlier system constraints and project guidelines start getting squeezed out. The agent loses track of the original requirements and starts improvising again, this time because it literally can't see the instructions anymore.

Here's how the approaches compare on the two axes that matter:

Approach	Token Efficiency	Maintainability Across Iterations
Flat prompt files (.cursorrules)	Poor—entire file loaded every turn, no lazy loading	Difficult—editing one rule means rewriting the blob, no versioning, no rollback
Enterprise registries (PromptLayer)	Variable—depends on API routing, not designed for context window management	Strong—versioning, observability, visual debugging, but built for backend API developers
jsm progressive disclosure	Strong—SKILL.md index first, references loaded on demand, assets only when needed	Strong—deterministic hashing, CLI sync, self-testing scripts verify workflows still work after edits

The best practices for writing your own skills are straightforward: keep SKILL.md scannable, make triggers explicit, and write each reference file to be self-contained so the agent can load it independently without needing to re-read the index. If the agent has to read two files to understand one procedure, you've recreated the monolithic prompt problem.

The Empirical Optimization Loop: What It Forces the Agent to Do

This is where jsm's real value lives, in my view. The "Extreme Software Optimization" workflow isn't a prompt that says "make the code faster." It's a forced empirical loop that constrains the agent to a specific sequence of operations before it's allowed to touch code.

sequenceDiagram
    participant Agent
    participant Codebase
    participant Benchmark

    Agent->>Codebase: Capture baseline (p95 latency, throughput)
    Agent->>Codebase: Profile hotspots, rank by impact × confidence ÷ effort
    Agent->>Codebase: Generate golden outputs from current behavior
    Agent->>Codebase: Apply single-variable change
    Agent->>Benchmark: Re-measure performance
    Benchmark-->>Agent: New metrics (p95, throughput)
    Agent->>Agent: Compare against baseline + golden outputs
    alt Speedup confirmed, no regressions
        Agent->>Codebase: Keep change, iterate on next hotspot
    else Regression detected
        Agent->>Codebase: Roll back or adjust, re-verify
    end

The first step—baseline capture—is what most agents skip. They see a function, think "this loop is slow," and start optimizing based on intuition. The loop forces measurement first. The p95 and throughput numbers exist before any edit is made, so "faster" has a concrete referent.

Then the ranking formula: $\text{impact} \times \text{confidence} \div \text{effort}$. That's not a sophisticated heuristic—it's a priority filter. The agent has to estimate the payoff of touching each hotspot against the cost of doing so, and work through the list in ranked order. This prevents the classic failure mode of optimizing a cold path that doesn't affect real performance.

The golden outputs are the piece I'd emphasize. The agent captures the behavioral contract before any edits. Whether that's response JSON, rendered HTML, or a specific function's return value for a given input—those outputs become the regression suite. The agent must demonstrate that the change didn't alter behavior, only performance.

Here's where it breaks down in practice: noisy benchmarking environments. On a shared developer laptop, p95 latency swings wildly based on what else is running. The agent "proves" a speedup that's actually just a quieter moment in the OS scheduler. Or it rejects a valid optimization because the baseline was measured during a background indexing job.

The fix is isolation. Pinned CPU/RAM, dedicated containers, benchmark runs with no competing processes. If you're running this workflow in CI, you need dedicated runners that aren't doing anything else.

And then there's the non-determinism problem. Golden output comparisons fail immediately on code that generates UUIDs, embeds timestamps, or serializes maps in nondeterministic order. The agent sees a "regression" that's actually just a different random seed. The solution is to tell the agent explicitly: mock the randomness, seed the PRNG, normalize the output before comparison. That's the kind of thing that has to go in the skill itself, not be left to the agent's judgment.

Multi-Pass Bug Hunting: How to Make It More Than a Listing

The bug hunting suite—multi-pass-bug-hunting, ubs (Ultimate Bug Scanner), and codebase-audit—is where jsm's workflow discipline either pays off or collapses into noise. The key insight is that these aren't three tools doing similar things. They're three lenses applied sequentially, each one filtering the codebase through a different concern.

Here's how multi-pass actually works in practice. The first pass looks for security vulnerabilities—untrusted input flows, injection points, missing auth checks. The second pass shifts to concurrency—race conditions, shared mutable state, lock ordering. The third pass examines logic—branch coverage, error handling, edge cases. Each pass produces a distinct finding set because each pass asks a fundamentally different question. The agent isn't re-reading the same file with the same eyes; it's re-reading with a completely different analytical frame.

That's the theory. Here's where it breaks: subagent orchestration is the entire value, and it's the easiest thing to get wrong.

If you dispatch a subagent for each pass, you need those subagents to receive distinct instructions. Not "audit the codebase" three times with different headers—actual different analytical criteria. Without that, you get what I'd call the convergence problem: all three subagents converge on the same obvious findings because they're all doing the same generic "look for bugs" task. You end up with three reports that are 80% identical, and the unique findings from each lens never surface.

The fix is to make each subagent's charter explicit and non-overlapping. Pass one gets: "Find security vulnerabilities only. Do not report style issues, performance concerns, or logic bugs. If a finding isn't a security issue, skip it." Pass two gets: "Find concurrency issues only. Ignore security. Ignore performance." Pass three gets: "Find logic and correctness issues only." The separation is what makes the multi-pass approach work.

The other thing I'd insist on: have the subagents write to a shared file rather than returning findings inline. If each subagent reports back through the conversation, you get interleaved reasoning, context pollution, and the main agent losing track of which findings came from which pass. Instead, dispatch the subagents via hooks with a shared output file. Each subagent appends its findings to findings-pass-security.md, findings-pass-concurrency.md, findings-pass-logic.md. The main agent then reads all three files and does the aggregation and deduplication in one clean pass.

That aggregation step is where the real value is. A list of bugs from three separate scans is just a list. The synthesis—"these two findings from the security and concurrency passes are actually the same root cause"—is what makes the multi-pass approach worth the token cost. Without that synthesis, you're just running three separate scanners and throwing their outputs into a file.

The failure mode I'd watch for is subagent under-training. Subagents are cheaper to run, but they're also less capable. If the skill hands them a complex audit procedure without enough scaffolding, they'll produce shallow findings and the main agent will have to redo the work anyway. Write the subagent prompts to be self-contained—each one should carry its full analytical criteria in its context, not depend on the main agent's accumulated context to understand the task.

Comparing jsm to the Open-Source Alternatives

Here's the landscape laid out across the dimensions that actually matter when you're deciding whether to pay for a skill manager or roll your own:

Dimension	jsm (Jeffrey's Skills)	Flat Prompt Files (.cursorrules)	Community Hubs (Cursor Directory, awesome-cursorrules)	Agent Harnesses (Aider, Devin Playbooks)	Enterprise Registries (PromptLayer, Portkey)
Token Efficiency	Strong—progressive disclosure loads references on demand	Poor—entire file loaded every turn, no lazy loading	Variable—depends on the prompt author's structure; most are monolithic	Moderate—harnesses often inject framework code alongside instructions	Not designed for context management—routes API requests instead
Validation	Built-in—self-testing scripts verify workflows still function	None—no execution checks, only text	None—no validation beyond copy-paste correctness	Strong—harnesses enforce execution loops and tool-use contracts	Strong—evaluation frameworks and regression testing for prompts in production
Versioning	Deterministic SHA-256 hashing, explicit version pins	None—file edits are implicit, no rollback mechanism	Weak—community repos use git, but no content-level verification	Moderate—harness versions are locked, but prompt changes aren't tracked separately	Strong—versioned prompt releases, rollback, and audit trails
Distribution	CLI binary with OAuth auth, browser-based sync, searchable local index	Manual copy-paste or git clone	Web browsing + copy-paste, no automation	Tied to specific harness platform or execution environment	Web dashboard + API, requires integration for local CLI workflows
Model Portability	Model-agnostic architecture but hooks and subagent syntax vary across harnesses	Fully portable—pure text, no execution dependencies	Portable—pure markdown, no tool-specific syntax	Poor—locked to specific harness execution primitives	Portable at the API level but not designed for local agent workflows
Cost	$20/mo individual, $300/mo team	Free	Free	Varies—Aider is free, Devin is subscription-based	Typically per-seat or usage-based enterprise pricing
Open-Source Viability	Closed-source binary, but the structure is trivially replicable	Fully open, just markdown files	Fully open, community-maintained	Mixed—Aider is open source, Devin is not	Closed-source SaaS platforms

Now the verdict. jsm wins decisively on CLI ergonomics and workflow rigor. The ability to jsm install a skill with deterministic hashing, sync it across machines, and have it self-test is genuinely better than browsing cursor.directory and pasting a prompt. The empirical optimization loop and multi-pass bug hunting algorithms are curated, tested instruction sets—not generic "be thorough" advice.

But the $20/month is hard to justify when you can replicate the entire structural pattern in a private Git repo. I've said this before and I'll say it again: the markdown hierarchy is not the moat. If you're a solo developer who's technically comfortable, you can build a skills/ directory with SKILL.md + references/, write a thirty-line shell script to sync it, and get 80% of the value for free.

The remaining 20%—the curated optimization and bug-hunting algorithms—is what you're actually paying for. That's not a toggle. That's genuinely thoughtful engineering. If those workflows save you an hour a week, the individual tier pays for itself. If you're already deep in agent coding and care about the quality of your instruction sets, it's worth it.

For teams, the $300/month enterprise tier needs a different lens. SSO, RBAC, and centralized skill governance are real features. But a Git-based internal registry with branch protection and code review on skill changes gets you most of that governance for zero subscription cost. I'd pay for the enterprise tier only if you're already all-in on jsm skills and need the compliance overhead—not as a first move.

Production Checklists: What I'd Put in a Skills Registry

Adopting jsm in a team context has less to do with the tool itself and more with the discipline you build around it. The first thing I'd do is set up an internal registry, whether that's a private repo with the skills directory structure or a curated collection of vetted skills from your subscription. Each skill should carry metadata—a description, relevant tags, and an explicit version number. That metadata is what makes the skills searchable and auditable, not just a pile of markdown files.

For team adoption, the enterprise tier at $300/month with SSO and RBAC is the easy answer. But I'd push back on that as a default. A Git-based internal registry with branch protection and code review on skill changes gives you the same governance with more flexibility, and it keeps your repositories in one place. You can pin hashes in a lock file to ensure deterministic behavior that matches what you validated, preventing a weekly upstream update from silently altering how your agents operate in the middle of a sprint.

The validation layer is critical. Each skill should have a self-testing script that runs in CI. That's how you know the skill still works after you edit a reference file, or after your agent harness upgrades to a new version with different hook syntax. Without that, you're shipping changes to agent behavior without any regression checks—the same problem you're trying to solve in your codebase, but now applied to your prompt infrastructure.

Here's a concrete project idea that follows this pattern: build your own skill registry with Git hooks and Tantivy. Create a repo with a skills/ directory where each skill contains a SKILL.md and its references. Use Git submodules or a simple script to pull updates, and write a small CLI to search locally via Tantivy. That gives you jsm's packaging and local search without the subscription. The pitfall to watch for is token bloat—keep your SKILL.md files concise, and use explicit trigger phrases so the agent doesn't lazy-load the wrong reference. A skill index that's dense enough to be scannable but specific enough to route the agent to the right file is the whole game.

For the golden output step specifically, I'd build a harness that normalizes non-deterministic output—sort maps, strip timestamps, mock UUIDs—and captures golden files for any optimization skill you use. That connects the optimization loop's behavioral-preservation step to your CI/CD pipeline, and it works best with seeded PRNGs and deterministic mocks. But run this in a container or dedicated CI runner with pinned CPU and RAM. A noisy developer laptop will produce false positives, and you'll waste time chasing phantom regressions.

Finally, test on your actual target model before relying on autonomous edits. If you're on Flash-tier agents, wrap your premium skills in a model-specific adapter. Flatten the references/ into a single file with explicit step-by-step instructions, and override any hooks or subagent calls to match your agent's syntax. Then test that the model actually follows the verification loops—you may need to add forced "measure before edit" prompts to prevent procedural drift before you let it run unsupervised.

Resources

• Jeffrey's Skills.md
• Documentation | Jeffrey's Skills.md
• Pricing | Jeffrey's Skills.md