Magnus Hedemark
b864a312c7
A skill wrapping the lastfm-cli tool for the Last.fm music data API: user listening history, artist/album/track metadata, collaborative filtering-based similar music discovery, global/per-country charts, search, tags, and scrobble/love/now-playing write operations. Includes a Music Discovery Pipeline section for turning liked tracks into recommendations via Last.fm's collaborative filtering graph.
6.2 KiB
AGENTS.md — Agent Guide for agent-skills
This file tells AI agents how to load and use skills from this repository. Skills in this repo follow the Agent Skills open format — a standardized way to give agents new capabilities through structured markdown files.
Format Compliance
Every skill in this repository conforms to the Agent Skills specification:
| Requirement | Rule |
|---|---|
| Directory | Each skill in its own directory named by the skill |
| Entry point | SKILL.md with YAML frontmatter + markdown body |
name field |
Lowercase, hyphens only, matches parent directory name |
description field |
Trigger-oriented, describes what and when |
| Progressive disclosure | Core instructions in SKILL.md (< 500 lines, < 5,000 tokens), supporting material in references/, templates/, scripts/ |
| File references | Relative paths from skill root, one level deep |
How to Load Skills
Skills are loaded progressively in three stages:
Stage 1 — Metadata
At session start, read each skill's name and description from frontmatter. This takes ~100 tokens per skill and lets you know what's available without loading full content.
# Example metadata (from cli-builder/SKILL.md)
name: cli-builder
description: >-
Build or refactor CLI tools designed for AI agent consumption: non-interactive,
flag-driven, idempotent, with --json output and --dry-run preview.
Stage 2 — Full Instructions
When a user's request matches a skill's description keywords, load the full SKILL.md. The body contains step-by-step instructions, examples, and gotchas. Do not load skills preemptively — only load when triggered.
Stage 3 — Supporting Files
Reference files (references/, templates/, scripts/) are loaded on demand. The SKILL.md tells you when to read each one. Do not load all references at activation time — following the triggers preserves context.
Reading Order
If this is your first session with this repo, read these in order:
- agent-skills/SKILL.md — The Agent Skills format reference. Read this first to understand the format.
- README.md — Skill index with descriptions. Use to discover which skill to load.
- Individual skill
SKILL.mdfiles as triggered by the user's task.
Skill Loading by Trigger
When the user mentions these keywords, load the corresponding skill:
| User says... | Load skill |
|---|---|
| "build a CLI", "make a CLI tool", "agent-friendly CLI", "add --json flag" | cli-builder |
| "debug this", "root cause", "why is this broken", "fix this bug" | systematic-debugging |
| "epub", "ebook", "EPUB file", "ebook format", "read epub", "write epub", "create ebook", "extract from epub", "epub to text", "edit epub", "repair epub", "convert epub2", "epub images", "batch epub", "ebook metadata" | epub |
| "weather", "forecast", "temperature", "is it raining", "Tempest" | tempest-cli |
| "reverse-engineer", "understand this codebase", "PRD from code", "architecture document" | software-architecture-analysis |
| "data architecture", "data platform", "data strategy", "data mesh", "governance" | |
| "statistical analysis", "experimental design", "A/B test", "hypothesis test", "power analysis", "causal inference", "regression", "Bayesian", "p-value", "effect size", "model selection", "machine learning methodology" | |
| "brand identity", "brand guidelines", "style guide", "brand card", "brand strategy", "visual identity", "brand documentation", "color palette", "brand book" | |
| "kanban", "WIP", "cycle time", "flow metrics", "Scrum to Kanban", "multi-portfolio", "throughput", "classes of service" | |
| "skill format", "how do I make a skill", "agentskills.io" | |
Best Practices
Do Load by Trigger
The description field is the trigger mechanism. If the user's request contains keywords matching a skill's description, load that skill. If multiple skills match, load the most specific one.
Don't Load Everything at Startup
Loading all 14 skills at session start (~6,000 lines, ~75KB) wastes context. Let the conversation trigger loading. Skills load in ~100 tokens (metadata) and only expand when needed.
Follow Progressive Disclosure
When a skill body tells you to read a reference file only under specific conditions ("Read this if the API returns a 500"), do not read it proactively. Reference files are for specific edge cases, not general instruction.
Validate Your Output
When creating or modifying a skill in this repo, validate against the format:
namematches parent directory namedescriptionis 1-1024 chars, non-empty- Body under 500 lines and 5,000 tokens
- All file references use relative paths from skill root
- Frontmatter YAML is valid
Respect Attribution
Some skills in this repo are adapted from other open-source projects. Attribution is maintained in the source field. Do not remove or modify attribution.
Troubleshooting
Skill not loading when expected: The description field may need trigger keyword updates. Check that the user's phrasing overlaps with the skill's description vocabulary.
Skill body too large: The agent's context window may be full. The spec recommends under 5,000 tokens per skill. If a skill is exceeding this, its content can be further split into references.
Reference file not found: All file references use relative paths from the skill's directory root. If a reference is missing, check that the file exists at the path specified.