AGENTS.md

Agent Skills Repository

Amolith's collection of Agent Skills—markdown-based documentation that extends AI agent capabilities through a standardized format.

Repository Structure

Each directory under skills/ is a skill. A skill's directory name must match its name frontmatter field.

skills/skill-name/
├── SKILL.md          # Required: YAML frontmatter + markdown instructions
├── references/       # Optional: additional documentation loaded on-demand
├── scripts/          # Optional: executable code
└── assets/           # Optional: templates, resources

Creating/Editing Skills

The skills/authoring-skills/ directory has the necessary info for, well, authoring skills.

Listing Skills in README.md

When adding a new skill, include an entry in the "Available Skills" section of README.md. Entries should be:

  • Third-person present tense: "Writes", "Creates", "Queries" — describes what the skill does
  • Concise: Tight paragraph that conveys the capability
  • Human-oriented: A human can read it and understand what the skill will make the agent do

Example pattern:

  • "Creates commits following Conventional Commits format via git-format."

Sort entries alphabetically by skill name.

Naming Convention

Two categories of skills exist:

  • Generic capability skills (formatting-commits): Use specific tools to accomplish general tasks. Tool name omitted from skill name.
  • Service workflow skills (creating-tasks-through-lunatask): Workflows for specific proprietary services. Service name included via -through-{service} suffix.

Vendored Skills

Some skills under skills/ are symlinks into vendor/. These come from external repos via git subtree --squash. Don't edit them directly — changes will be overwritten on the next pull.

  • Manifest: vendor/sources lists each vendored repo (tab-separated: name, URL, branch)
  • Update all: scripts/vendor-update.fish
  • Update one: scripts/vendor-update.fish REPONAME
  • Add a new vendor: git subtree add --prefix=vendor/REPONAME URL BRANCH --squash, add a line to vendor/sources, symlink desired skill directories into skills/

Design Principles

  1. Progressive disclosure: Frontmatter loads at startup; SKILL.md body loads on activation; references/ load on-demand
  2. Conciseness over completeness: Every token competes for context window space
  3. Appropriate freedom: Match instruction specificity to task fragility (see skills/authoring-skills/references/patterns.md)