# 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`)