feat: installable agent skill for coding agents#25
Merged
Merged
Conversation
SKILL.md router plus four markdown domains (observations, revisions, catalog, dataframes), each README patterns + SHARP-EDGES with dated, evidence-tagged pitfalls from the corpus and live dogfooding, gated by tests/test_skill_content.py (structure, links, and behavioral pinning of every python snippet against corpus fixtures).
Copy-only installer for the agent skill: resolve_roots/install/uninstall/ status over documented per-agent skill-discovery roots (claude, codex, copilot, cursor, gemini, pi; user and project scopes), ownership-checked via the SKILL.md frontmatter name so a directory fredq does not own is never replaced or removed, and version-stamped at install time (surfaced as current/stale by status()). Ported from yoghurt's reviewed implementation.
fredq skills install/uninstall/list with --agent (comma-separable named targets), --project scope, and --to PATH; dispatches before client construction so it works with no API key; human-readable output carved out of the raw-JSON contract in AGENTS.md as packaging/installer surface.
Extend the existing wheel-membership gate so a wheel that silently drops the agent skill (SKILL.md, a domain doc, or the installer module) fails this test instead of shipping broken.
Add a README "Agent skill" section (right after Install) covering `fredq skills install/list/uninstall`, named agent targets, --project/--to, and the copy-only/ownership-safe install model; add the matching CHANGELOG Added entries under Unreleased.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ships an Agent Skills–standard skill teaching coding agents fredq's library and CLI, plus a
fredq skills {install,uninstall,list}CLI group to install it.src/fredq/skills/content/): aSKILL.mdrouter plus four task-oriented domains —observations(fetching series data: windows, units transforms, frequency aggregation, missing values),revisions(ALFRED: realtime windows, vintage dates, revision analysis),catalog(search, category tree, releases, sources, tags),dataframes(Frame vocabulary, the pandas extra, parquet, joining mixed frequencies). Each domain carries aSHARP-EDGES.mdof corpus- and dogfood-dated pitfalls (12 total), e.g.: revision cadence varies wildly by series (RSAFS/INDPRO heavy churn, PAYEMS prior-2-months, GDP estimate-rounds only, UNRATE/CPIAUCSL annual-only — live-measured 2026-07-07); inner joins across vintages silently drop new-in-newer-vintage rows;UNRATEfor month M publishes early in M+1 (look-ahead risk); FRED's"."missing-value sentinel decodes toNone, neverNaN; empty results are a valid response shape, not an error; an unknown tag name is a 400, not an empty result; every 400 surfaces as oneFredApiErrorshape by design (noNotFoundError);geofredwas removed in 0.4.0 and agents with stale training data may still reach for it.src/fredq/skills/_install.py): copy-only install/uninstall/status against a documented table of six agents' skill-discovery roots —claude,codex,copilot,cursor,gemini,pi— at both user and project scope. Installs stamp the installing fredq version intoSKILL.md's frontmatter;list/statusreports each location as current/stale/absent by reading that stamp back. Ownership is checked by frontmattername:before any overwrite or removal, so a directory fredq didn't create is never touched.fredq skills install|uninstall|list):--agent NAME[,NAME...]for named targets,--projectfor repo-relative roots instead of user-level ones,--to PATHas an escape hatch. Dispatches before any FRED client construction —fredq skills listworks with no API key. README "Agent skill" section and CHANGELOG entries added.This ports yoghurt PR #25's reviewed installer/CLI design (squash
5187bcb) near-verbatim; the skill content and sharp edges are authored fresh from fredq's own corpus and dogfooding.Gates
tests/test_skill_content.py): frontmattername == fredq+ description ≤1024 chars, exact tree shape, every domain linked fromSKILL.md, relative links resolve,SHARP-EDGES.mdfixed shape (Severity + Evidence lines per entry), and — the important one — every fenced Python snippet across the skill is extracted verbatim and executed offline against corpus fixtures via fredq's existing_core._get_clientmonkeypatch seam, so a snippet that doesn't actually run can't ship.tests/test_skills_install.py): the six agent paths are pinned against the documented table (not name-derived), version stamping, ownership refusal, and that a refused target never blocks the rest of a batch install.tests/test_cli_skills.py): exit codes,--agentCSV usage-error semantics (empty item = usage error, matching fredq's existing CSV convention), output line formats, and that noFredClientis ever constructed for anyskillssubcommand.tests/test_packaging.py, extended in this PR): the built wheel is asserted to containfredq/skills/content/SKILL.md,fredq/skills/content/observations/README.md, andfredq/skills/_install.py.ruff check,ruff format --check,black --check,pyright(0 errors),pytest -q,npx cspell . --no-gitignore(0 issues) all clean. Live round-trip smoke:fredq skills install --to <tmp>writes a version-stampedSKILL.md+ 4 domains to disk,fredq skills listreports every named target,fredq skills uninstall --to <tmp>removes the installed directory — verified on disk at each step.🤖 Generated with Claude Code