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
- **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

### worklog
Creates comprehensive structured org-mode worklogs documenting work sessions.

**When to use**: After completing significant work that should be documented for future reference.

**What it does**:
- Gathers git context (commits, changes, status)
- Extracts session metrics
- Generates comprehensive org-mode worklog with standardized sections
- Saves to `docs/worklogs/YYYY-MM-DD-descriptive-topic.org`

**Dependencies**: Git repository, bash

### update-spec-kit
Updates the spec-kit ecosystem to latest versions across repository, CLI, and all projects.

**When to use**: When you want to ensure spec-kit is current across your entire development environment.

**What it does**:
- Updates spec-kit repository from upstream
- Upgrades specify CLI tool via uv
- Updates all projects using spec-kit to latest templates
- Preserves user work (specs, code, settings)

**Dependencies**: git, uv, spec-kit installation

## 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.