261 lines
8.6 KiB
Markdown
261 lines
8.6 KiB
Markdown
# 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
|
|
- **Composability**: Skills can call other skills
|
|
- **Version Control**: Track and evolve capabilities over time
|
|
- **Multi-Agent Support**: Same skills work with both Claude Code 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** | Multi-lens code review (bloat, smells, dead-code, redundancy). Interactive issue filing. | 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 coding 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.
|