harus-skills

Portable agent skills for durable work state, evidence-backed lessons, and practical tooling.

_{Three skills. One graph for memory. One toolbelt for the terminal. Zero runtime code — just markdown an agent reads.}

✨ Skills

Skills support the current task and its authorization. They resolve routine uncertainty through evidence, keep task state separate from durable lessons, and verify results in proportion to risk. Current user and project instructions override portable defaults or recalled preferences. Tool availability is checked on the actual machine.

Asobi discovers configuration in ancestor directories, so a nested repository can share its parent's graph. Task dispatch records ownership; the agent still reads relevant lessons and starts any delegated work. Workspaces with a [skills] declaration in asobi.toml use asobi skills sync to reconcile installed skills, including removals.

🧰 What's in the toolbelt

Modern OSS CLIs, reached for by default over the classic Unix tools:

• Search & edit — rg/fd (text/file), ast-grep (AST-aware structural search & rewrite), sd (find/replace), difftastic (syntax-aware diffs), typos (source spell-check)
• View & inspect — eza/bat/dust, procs (ps), doggo (dig), hexyl (hex), tailspin (log highlight)
• HTTP & data — xh (curl), dasel (YAML/TOML/XML/CSV), duckdb, miller (CSV/TSV), hyperfine/oha (benchmarks)
• Runtimes — uv/uvx (Python), bun/bunx (JS/TS)

📦 Installation

Prerequisites

• A supported agent host (Claude Code, Codex, or Antigravity)
• asobi CLI for the /asobi skill (cargo install asobi)

Claude Code — Marketplace Plugin

/plugin marketplace add azusachino/harus-skills
/plugin install harus-skills

Restart Claude Code after installing.

Antigravity (agy) — Plugin

agy plugin install https://github.com/azusachino/harus-skills
# or for local development:
agy plugin link /path/to/harus-skills

Codex

codex plugin install https://github.com/azusachino/harus-skills

🛠️ Development

This repository currently uses a Nix devShell and Nix-based CI. The portable tooling default is Mise; migrating this repository's development setup is tracked in the harus-kb remediation plan.

nix develop          # Enter dev shell (provides all tools)
make fmt             # Format JSON/YAML (not markdown)
make check           # Run all checks (format + verify)
make validate        # PR gate: check + plugin manifest validation
make verify          # Verify repository structure
make list-skills     # List all available skills

Run checks explicitly: the current hook installer assumes a directory-backed .git and restages files, so it is unsuitable for vendored submodules or partial staging. Manifest validation proves JSON validity and aligned versions; it does not exercise installation in each agent host.

🗂️ Skill Structure

Each skill follows the Agent Skills Standard format as a flat directory under skills/:

skills/
  asobi/
    SKILL.md          # Skill definition with YAML frontmatter
  revise/
    SKILL.md
  toolbelt/
    SKILL.md

🤝 Contributing

1. Create a new directory directly under skills/
2. Add a SKILL.md with YAML frontmatter (name, description, metadata.version)
3. Run make check before submitting
4. Open a pull request

🙏 Credits & inspiration

Design decisions are recorded as ADRs. The skills stand on the shoulders of the OSS agent-skill community:

• asobi — the knowledge-graph CLI that backs /asobi
• Agent Skills Standard — the SKILL.md format every skill targets
• ponytail — reuse existing capabilities and keep solutions small
• karpathy-guidelines — surgical changes and goal-driven verification

📚 Resources

• Agent Skills Standard
• Claude Code Documentation