skills/magnus919_agent-skills
1
0
Fork 0
mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-11 19:47:12 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: add AGENTS.md, LICENSE.md, curated README with installation sections

Browse Source 
README.md: curated skill index with descriptions for all 6 skills,
installation sections for Claude Code, OpenCode, Hermes Agent, Codex
CLI, GitHub Copilot, and generic frameworks.

LICENSE.md: standard MIT boilerplate.

AGENTS.md: agent loading guide with trigger table, progressive
disclosure rules, troubleshooting, and format compliance references.

Signed-off-by: Jasper <magnus@groktop.us>
This commit is contained in:
Magnus Hedemark
2026-05-21 22:53:03 -04:00
parent 0fd760b89c
commit c1d13b95c6
3 changed files with 233 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+96
View File
@@ -0,0 +1,96 @@
# 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](https://agentskills.io) — 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](https://agentskills.io/specification.md):
| 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.
```yaml
# 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:
1. [agent-skills/SKILL.md](agent-skills/SKILL.md) — The Agent Skills format reference. Read this first to understand the format.
2. [README.md](README.md) — Skill index with descriptions. Use to discover which skill to load.
3. Individual skill `SKILL.md` files 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](cli-builder/SKILL.md) |
| "debug this", "root cause", "why is this broken", "fix this bug" | [systematic-debugging](systematic-debugging/SKILL.md) |
| "weather", "forecast", "temperature", "is it raining", "Tempest" | [tempest-cli](tempest-cli/SKILL.md) |
| "reverse-engineer", "understand this codebase", "PRD from code", "architecture document" | [software-architecture-analysis](software-architecture-analysis/SKILL.md) |
| "data architecture", "data platform", "data strategy", "data mesh", "governance" | [data-architect](data-architect/SKILL.md) |
| "skill format", "how do I make a skill", "agentskills.io" | [agent-skills](agent-skills/SKILL.md) |
## 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 5 skills at session start (~2,000 lines, ~25KB) 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:
- `name` matches parent directory name
- `description` is 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.
LICENSE.md
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Magnus Hedemark
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
README.md
+116 -10
View File
@@ -1,27 +1,133 @@
# agent-skills
A collection of AI agent skills — reusable workflows, protocols, and knowledge packs for agentic systems.
This repo is being built incrementally. Skills will be added over time as they're curated, refined, and tested.
## What is a skill?
Each skill lives in its own directory with a `SKILL.md` as the entry point, optionally backed by `references/`, `templates/`, and `scripts/` for supporting material. Skills are designed to be loaded by AI agents (Hermes Agent, Claude Code, OpenCode, etc.) as procedural memory — giving them structured domain knowledge and proven approaches for specific tasks.
A collection of AI agent skills — reusable workflows, protocols, and knowledge packs for agentic systems. Skills follow the [Agent Skills open format](https://agentskills.io), making them compatible with any agent framework that supports the standard.
## Skills
### [cli-builder](cli-builder/SKILL.md)
Design and build CLI tools for AI agent consumption. 10 universal patterns (non-interactive, `--json`, `--dry-run`, idempotent, lazy auth, progressive help), an agent-compatibility test suite, and a bash scaffold template. Principles grounded in real failures from building 15+ agent-facing CLIs.
Build and refactor CLI tools for AI agent consumption. 10 universal patterns (non-interactive, `--json`, `--dry-run`, idempotent, lazy auth, progressive help), an agent-compatibility test suite, a Python API client pattern, and a bash scaffold template. Principles grounded in real failures from building 15+ agent-facing CLIs.
### [systematic-debugging](systematic-debugging/SKILL.md)
4-phase root cause debugging protocol: understand bugs before fixing. Covers schema/environment divergence, exception type specificity in fallback chains, progressive characterization grids for API/retrieval failures, dependency source detection (editable dev forks), macOS sandboxed application debugging, and the Rule of Three for recognizing architectural problems. Adapted from [obra/superpowers](https://github.com/obra/superpowers) (MIT) with significant expansion from real-world use.
### [tempest-cli](tempest-cli/SKILL.md)
Hyper-local weather from a WeatherFlow Tempest station. Query current conditions, 7-day forecast, historical observations, and real-time UDP broadcasts. A complete reference implementation of the cli-builder patterns in a working, testable project — including the CLI binary and full API field layout reference.
### [software-architecture-analysis](software-architecture-analysis/SKILL.md)
Reverse-engineer a software codebase to understand its architecture, data flow, privacy posture, and feature surface — then produce a clean-room design document, PRD, or migration plan under new constraints (local-first, privacy-first, self-hosted). Includes an interface extraction pattern for designing swappable storage provider abstractions.
### [data-architect](data-architect/SKILL.md)
A virtual data architect for teams who don't have one. Consult on architecture decisions, review data models and pipelines, evaluate tradeoffs (warehouse vs lakehouse, Kimball vs Inmon, batch vs streaming), assess governance maturity, and plan data strategy. Includes 8 reference files, a governance maturity assessment script, and an ADR template. Designed for data engineers working without a human architect — includes a QuickScan and proactive discovery flow for when you don't know where to start.
Act as a virtual data architect. Discover data assets, assess maturity, evaluate platforms, design architectures, establish governance, and create migration plans. Covers modern data patterns (data mesh, data lakehouse, streaming, real-time analytics) with vendor evaluation frameworks and maturity models.
### [agent-skills](agent-skills/SKILL.md)
Reference for the Agent Skills open format itself — directory structure, frontmatter schema, naming conventions, and progressive disclosure model. Use this meta-skill when creating or reviewing any other skill in this repository.
---
## Installation
Skills don't require installation in the traditional sense. They are loaded by your AI agent when triggered. The setup differs slightly by harness.
### Claude Code
Claude Code supports Agent Skills natively. Place skills in your project's `.claude/skills/` directory or in `~/.claude/skills/` for global access:
```bash
# Per-project (recommended)
mkdir -p .claude/skills
cp -r cli-builder .claude/skills/
# Or global for all projects
mkdir -p ~/.claude/skills
cp -r cli-builder ~/.claude/skills/
```
Claude Code automatically indexes skills at startup and loads them based on their `description` field matching the current task.
### OpenCode
OpenCode loads skills from the `skills/` directory in your project or from `~/.opencode/skills/`. Skills must follow the Agent Skills format with valid YAML frontmatter:
```bash
# Project-level
mkdir -p skills
cp -r cli-builder skills/
# Or global
mkdir -p ~/.opencode/skills
cp -r cli-builder ~/.opencode/skills/
```
OpenCode uses the `name` and `description` frontmatter fields for skill discovery. Ensure descriptions include trigger keywords matching your use cases.
### Hermes Agent
Hermes Agent loads skills from `~/.hermes/skills/`. Skills are organized by category subdirectory:
```bash
cp -r cli-builder ~/.hermes/skills/devops/
cp -r systematic-debugging ~/.hermes/skills/software-development/
cp -r tempest-cli ~/.hermes/skills/devops/
```
Hermes loads skill metadata at session start. Use the `/skills` command to list available skills, and `skill_view(name)` to load a specific skill's full instructions. Skills can also be pinned for persistent availability.
### Codex (OpenAI Codex CLI)
Codex CLI supports Agent Skills through its skill loading mechanism. Skills go in a `.claude/skills/` directory in your project root or in a configurable path:
```bash
mkdir -p .claude/skills
cp -r cli-builder .claude/skills/
```
Codex reads skills from the Agent Skills standard format. Ensure `SKILL.md` files have valid frontmatter and that the `name` field matches the parent directory name.
### GitHub Copilot
GitHub Copilot supports Agent Skills in editor and CLI modes. Place skills in `.github/skills/` in your repository root:
```bash
mkdir -p .github/skills
cp -r cli-builder .github/skills/
```
Copilot indexes skills from the repository and loads them based on task context. Skills can be version-controlled alongside your project code.
### Generic / Other Frameworks
Any agent framework that supports reading markdown files can use these skills. The format is intentionally simple:
1. Place the skill directory in your agent's accessible file path
2. The agent reads `SKILL.md` when triggered by keywords in the task
3. Supporting files in `references/`, `templates/`, and `scripts/` are loaded on demand
If your framework doesn't have built-in skill loading, you can:
- Instruct your agent to read specific `SKILL.md` files at session start
- Reference skills in your agent's system prompt or CLAUDE.md/AGENTS.md
- Use a startup script that pre-loads skill content into context
---
## Contributing
Skills follow the [Agent Skills specification](https://agentskills.io/specification.md). See the [agent-skills](agent-skills/SKILL.md) reference skill for format details, and `AGENTS.md` in this repo for agent-specific loading and compliance guidance.
Before submitting a new skill:
1. Ensure `SKILL.md` has valid YAML frontmatter (required: `name`, `description`)
2. The `name` field must match the parent directory name
3. Keep `SKILL.md` under 500 lines and 5,000 tokens
4. Move detailed reference material to `references/` for progressive disclosure
5. Validate with `skills-ref validate ./my-skill` if available
---
## License
MIT
MIT — see [LICENSE.md](LICENSE.md) for full terms.