skills/README.md

# Agentic Coding Skills

A unified repository for developing, testing, and deploying reusable skills for AI coding agents (Claude Code and OpenCode).

## Overview

This repository provides a structured framework for building **skills** - composable, reusable capabilities that enhance AI coding agents. Skills combine instructions, helper scripts, templates, and examples to enable agents to perform complex, multi-step workflows consistently.

**Why Skills?**
- **Consistency**: Standardized workflows across different projects
- **Reusability**: Write once, use everywhere
- **The Review Triad**: A robust 3-tier architecture (Verify -> Test-Review -> Code-Review) for guaranteed quality
- **Multi-Agent Support**: Same skills work with Claude, Gemini, Codex, and OpenCode

## Repository Structure

```
skills/
├── README.md                    # This file
├── WORKFLOW.md                  # Skill development workflow guide
├── skills/                      # Individual skill implementations
│   ├── worklog/                # Org-mode worklog generation
│   ├── update-spec-kit/        # Spec-kit ecosystem updates
│   └── template/               # Template for new skills
├── .specify/                    # Spec-kit framework (for developing this repo)
│   ├── templates/
│   ├── scripts/
│   └── memory/
└── .opencode/                   # OpenCode commands (for developing this repo)
    └── command/
```

## Skills Included

| Skill | Description | Status |
|-------|-------------|--------|
| **code-review** | **The Critic:** Multi-lens code review (bloat, smells, dead-code, redundancy, defense-in-depth). | Deployed |
| **test-review** | **The Auditor:** Audit test quality for flakiness, tautologies, and anti-patterns. | Deployed |
| **verify-work** | **The Gatekeeper:** Run project build/tests before claiming success. Enforces "The Iron Law". | Deployed |
| **niri-window-capture** | Invisibly capture screenshots of any window across workspaces using niri compositor. | Deployed |
| **orch** | Query multiple AI models for consensus decisions, second opinions, and devil's advocate analysis. | Deployed |
| **screenshot-latest** | Find and analyze the most recent screenshot without typing paths. | Deployed |
| **worklog** | Create comprehensive structured org-mode worklogs documenting work sessions. | Deployed |
| ai-tools-doctor | Check and sync AI tool versions against declared manifest. | Available |
| bd-issue-tracking | Track complex, multi-session work with dependency graphs using beads. | Available |
| doc-review | Lint markdown documentation for AI agent consumption using deterministic rules + LLM semantic checks. | Available |
| hq | Orchestrate multi-agent workflows using worker CLI and bd issue tracking. | Available |
| ops-review | Run multi-lens ops review on infrastructure files (Nix, shell, Docker, CI/CD). | Available |
| playwright-visit | Visit web pages using Playwright browser automation (screenshot, text, html, pdf). | Available |
| review-gate | Quality gate for cross-agent review enforcement. Blocks agent completion until approved. | Available |
| spec-review | Review spec-kit specifications using multi-model AI consensus before phase transitions. | Available |
| tufte-press | Generate Tufte-inspired study card JSON from conversation, build PDF, and print. | Available |
| update-opencode | Check for and apply OpenCode version updates in Nix-based dotfiles. | Available |
| update-spec-kit | Update spec-kit repository, CLI tool, and all project templates to latest. | Available |
| web-research | Conduct deep web research and produce structured reports. | Available |
| web-search | Search the web for information using Claude Code's subprocess capability. | Available |
| template | Template for creating new skills. | Development |

## Skill Structure

Each skill follows a standard structure:

```
skill-name/
├── SKILL.md                    # Primary skill definition
│   ├── Frontmatter metadata (name, description)
│   ├── When to Use section
│   ├── Process/Instructions section
│   └── Requirements section
├── README.md                   # User-facing documentation
├── scripts/                    # Helper scripts
│   ├── script1.sh
│   └── script2.sh
├── templates/                  # File templates
│   └── template-file.ext
└── examples/                   # Example outputs
    └── example-output.ext
```

### SKILL.md Format

```markdown
---
name: skill-name
description: One-line description of what this skill does
---

# Skill Name

Detailed description of the skill.

## When to Use

Explicit triggers and use cases for invoking this skill.

## Process

Step-by-step instructions for the agent to follow.

## Requirements

- Dependency 1
- Dependency 2
```

## Quick Start

### Using Skills

**Claude Code:**
Skills in `~/.claude/skills/` are automatically available. The agent will invoke them when appropriate based on the `description` and `When to Use` sections.

**OpenCode:**
Skills in `~/.config/opencode/skills/` are discovered by the `opencode-skills` plugin. Ensure the plugin is installed and configured.

### Developing Skills

1. **Create a new skill branch**:
   ```bash
   git checkout -b feature/new-skill-name
   ```

2. **Copy the template**:
   ```bash
   cp -r skills/template skills/your-skill-name
   ```

3. **Edit SKILL.md** with your skill definition

4. **Add scripts/templates** as needed

5. **Test locally** by deploying to `~/.claude/skills/` or `~/.config/opencode/skills/`

6. **Document in README.md** for users

See [WORKFLOW.md](./WORKFLOW.md) for detailed development workflow.

## Deployment

### Claude Code Deployment

**Manual deployment:**
```bash
# Link skill to Claude Code skills directory
ln -s $(pwd)/skills/your-skill-name ~/.claude/skills/your-skill-name
```

**Nix Home Manager deployment:**
```nix
# In your home.nix or equivalent
home.file.".claude/skills/your-skill-name" = {
  source = /path/to/skills/skills/your-skill-name;
  recursive = true;
};
```

### OpenCode Deployment

**Manual deployment:**
```bash
# Link skill to OpenCode skills directory
ln -s $(pwd)/skills/your-skill-name ~/.config/opencode/skills/your-skill-name
```

**Nix Home Manager deployment:**
```nix
# In your home.nix or equivalent
home.file.".config/opencode/skills/your-skill-name" = {
  source = /path/to/skills/skills/your-skill-name;
  recursive = true;
};
```

**Enable opencode-skills plugin:**
```json
// ~/.config/opencode/config.json
{
  "plugin": ["opencode-skills"]
}
```

## Design Principles

### 1. Agent-First Design
Skills are written for AI agents, not humans. Instructions should be:
- Explicit and unambiguous
- Procedural (step-by-step)
- Include decision criteria
- Reference specific files/commands

### 2. Self-Contained
Each skill should:
- Include all necessary scripts
- Document all dependencies
- Provide templates for generated content
- Include examples of expected output

### 3. Composable
Skills can invoke other skills, but should:
- Declare skill dependencies explicitly
- Handle missing dependencies gracefully
- Avoid circular dependencies

### 4. Testable
Skills should be testable by:
- Providing example inputs
- Defining expected outputs
- Including validation criteria
- Supporting dry-run modes where applicable

### 5. Version Controlled
All skill components should be:
- Tracked in git
- Documented with clear commit messages
- Tagged when significant changes occur
- Backward compatible when possible

## Contributing

### Adding a New Skill

1. Use the skill template as starting point
2. Follow the standard skill structure
3. Test with both Claude Code and OpenCode
4. Document in main README.md
5. Submit PR with comprehensive description

### Modifying Existing Skills

1. Create feature branch
2. Update SKILL.md and associated files
3. Test changes with real-world usage
4. Update version/changelog if significant
5. Submit PR explaining changes and impact

## Integration with Spec-Kit

This repository uses spec-kit for its own development workflow. The `.specify/` and `.opencode/` directories contain the spec-kit framework that enables structured feature development.

**To develop a new skill using spec-kit:**
```bash
# In OpenCode or Claude Code
/speckit.specify "Add a new skill for [description]"
```

This will guide you through the structured development process.

## License

MIT

## Related Projects

- [Claude Code](https://github.com/anthropics/claude-code) - Anthropic's official CLI for Claude
- [OpenCode](https://github.com/sst/opencode) - Open source AI coding agent
- [spec-kit](https://github.com/github/spec-kit) - Specification-driven development framework
- [opencode-skills](https://github.com/opencode-ai/opencode-skills) - OpenCode skills plugin

## Support

For issues, questions, or contributions, please open an issue in this repository.