---
slug: "nunchuck"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/JordanGunn/nunchuck@master/README.md"
repo: "https://github.com/JordanGunn/nunchuck"
source_file: "README.md"
branch: "master"
---
# Nunchuck

> **Deprecation Notice**
> 
> This repository is being deprecated in favour of more focused skill repositories. The creation of this repository is what led to the first draft of the ASI (Agent Skills Interface) governance specification, the OASR (Open Agent Skills Registry) CLI, and the AUx (Agentic Unix) skills. While the nunchuck skills were strong in spirit, **all of them will be reworked and significantly improved by applying techniques I have learned during early skills development.** Each of them will moved to dedicated repositories.
> I will leave this repository in the meantime since people seem to he using it. This notice will be updated with the new and improved skill repos as I develop them. Cheers! 

A rigorously structured collection of agent skills designed to reduce drift, enforce determinism, and make agentic work auditable. Built on the [Open Agent-Skill Specification](https://github.com/JordanGunn/agent-skill-spec) and extended with internal specifications that define canonical structures, execution patterns, and epistemic guardrails.

---

## Documentation

- **[Quickstart Guide](https://github.com/JordanGunn/nunchuck/blob/HEAD/docs/QUICKSTART.md)** — Getting started
- **[Skills Reference](https://github.com/JordanGunn/nunchuck/blob/HEAD/docs/SKILLS.md)** — Browse all available skills
- **[Contributing](https://github.com/JordanGunn/nunchuck/blob/HEAD/CONTRIBUTING.md)** — Add your own skills

---

## Design Philosophy

This repository treats language as inherently ambiguous and builds systems that succeed *despite* that ambiguity. Three principles guide all skill design:

- **Determinism First, Subjectivity Last** — Subjective reasoning must never compensate for missing deterministic outputs. If evidence is incomplete, return to earlier execution phases rather than explaining around gaps.

- **Artifacts as Completion Signals** — Success is mechanically verifiable. Skills declare what they produce; validation checks existence. Missing artifacts redirect execution to producing steps.

- **Professional Skepticism** — Agents interpret, clarify, and challenge rather than blindly comply. User input is valuable but not authoritative truth. Responsibility for correctness cannot be outsourced.

These principles are formalized in the [Design Documentation](https://github.com/JordanGunn/nunchuck/blob/HEAD/docs/design/.INDEX.md), which includes epistemic tenets, interaction tenets, and a determinism framework.

---

## Specification Compliance

### Open Agent-Skill Spec

All skills conform to the [Open Agent-Skill Specification](https://github.com/JordanGunn/agent-skill-spec), ensuring portability across agent platforms. Each `SKILL.md` contains frontmatter-only definitions with explicit metadata for references, scripts, and keywords.

### Internal Specifications

Beyond the open spec, this repository enforces internal specifications that define:

- **[SKILL.md Structure](https://github.com/JordanGunn/nunchuck/blob/HEAD/docs/design/specs/skillmd/.INDEX.md)** — Frontmatter schema, body constraints, validation rules
- **[References Structure](https://github.com/JordanGunn/nunchuck/blob/HEAD/docs/design/specs/references/.INDEX.md)** — Canonical 7-file reference set (`00_ROUTER` through `06_FAILURES`)
- **[Scripts Structure](https://github.com/JordanGunn/nunchuck/blob/HEAD/docs/design/specs/scripts/.INDEX.md)** — Cross-platform script requirements and naming

These specifications ensure consistency across all skills and enable tooling to validate compliance.

---

## Skills

All skills live in the `skills/` directory. Browse them directly or use the reference documentation:

- **[Skills Reference](https://github.com/JordanGunn/nunchuck/blob/HEAD/docs/SKILLS.md)** — Complete list of skills with descriptions and keywords

---

## Usage

See the **[Quickstart Guide](https://github.com/JordanGunn/nunchuck/blob/HEAD/docs/QUICKSTART.md)** for installation, IDE integration, and first steps.

---

## Scripts

Utility scripts provide thin integration layers without duplicating skill content. Skills remain spec-compliant so they transfer cleanly when IDEs adopt agent skills natively.

### IDE Adapters

Generate IDE-specific configurations that reference skills without copying them:

```bash
# Windsurf: generates .windsurf/workflows/
bash scripts/adapters/windsurf/run.sh --skills-root skills --output-root .

# Cursor: generates .cursor/commands/
bash scripts/adapters/cursor/run.sh --skills-root skills --output-root .
```

Windows (PowerShell):

```powershell
.\scripts\adapters\windsurf\run.ps1 --skills-root skills --output-root .
.\scripts\adapters\cursor\run.ps1 --skills-root skills --output-root .
```

### Index Generator

---

## Changelog

See [CHANGELOG.md](https://github.com/JordanGunn/nunchuck/blob/HEAD/CHANGELOG.md) for release history.

## License

See [LICENSE](https://github.com/JordanGunn/nunchuck/tree/HEAD/LICENSE) for details.