From fa2165ac01a9a9a09f2424aa1d20fa8f72346422 Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Thu, 15 Jan 2026 17:28:06 +0100 Subject: [PATCH] chore: move agents and skills to old2 folder Co-Authored-By: Claude Opus 4.5 --- .../backlog-builder => old2/agents}/AGENT.md | 0 .../agents}/capability-extractor/AGENT.md | 0 .../agents}/code-reviewer/AGENT.md | 0 .../agents}/context-mapper/AGENT.md | 0 .../agents}/domain-modeler/AGENT.md | 0 {agents => old2/agents}/issue-worker/AGENT.md | 0 .../agents}/milestone-planner/AGENT.md | 0 {agents => old2/agents}/pr-fixer/AGENT.md | 0 .../agents}/problem-space-analyst/AGENT.md | 0 {skills/gitea => old2/skills}/SKILL.md | 0 .../reference => old2/skills}/actions-ci.md | 0 .../skills}/best-practices.md | 0 .../skills}/create-capability/SKILL.md | 0 .../skills}/create-milestones/SKILL.md | 0 {skills => old2/skills}/dashboard/SKILL.md | 0 .../dashboard/scripts/generate-dashboard.sh | 0 {skills => old2/skills}/ddd/SKILL.md | 0 .../examples/progressive-disclosure.md | 0 .../skills}/examples/simple-workflow.md | 0 .../skills}/examples/with-scripts.md | 0 .../skills}/issue-writing/SKILL.md | 0 .../skills}/milestone-planning/SKILL.md | 0 .../skills}/product-strategy/SKILL.md | 0 .../skills}/reference/anti-patterns.md | 0 .../skills}/reference/frontmatter-fields.md | 0 .../skills}/reference/model-selection.md | 0 .../gitea/reference => old2/skills}/setup.md | 0 {skills => old2/skills}/spawn-issues/SKILL.md | 0 .../skills}/spawn-pr-fixers/SKILL.md | 0 .../skills}/spawn-pr-reviews/SKILL.md | 0 .../skills}/templates/agent.md | 0 .../skills}/templates/background-skill.md | 0 .../skills}/templates/helper-script.sh | 0 .../skills}/templates/user-invocable-skill.md | 0 .../skills}/vision-to-backlog/SKILL.md | 0 {skills => old2/skills}/worktrees/SKILL.md | 0 .../worktrees/scripts/cleanup-worktrees.sh | 0 .../worktrees/scripts/create-worktree.sh | 0 .../worktrees/scripts/list-worktrees.sh | 0 skills/capability-writing/SKILL.md | 358 ------------------ 40 files changed, 358 deletions(-) rename {agents/backlog-builder => old2/agents}/AGENT.md (100%) rename {agents => old2/agents}/capability-extractor/AGENT.md (100%) rename {agents => old2/agents}/code-reviewer/AGENT.md (100%) rename {agents => old2/agents}/context-mapper/AGENT.md (100%) rename {agents => old2/agents}/domain-modeler/AGENT.md (100%) rename {agents => old2/agents}/issue-worker/AGENT.md (100%) rename {agents => old2/agents}/milestone-planner/AGENT.md (100%) rename {agents => old2/agents}/pr-fixer/AGENT.md (100%) rename {agents => old2/agents}/problem-space-analyst/AGENT.md (100%) rename {skills/gitea => old2/skills}/SKILL.md (100%) rename {skills/gitea/reference => old2/skills}/actions-ci.md (100%) rename {skills/capability-writing => old2/skills}/best-practices.md (100%) rename {skills => old2/skills}/create-capability/SKILL.md (100%) rename {skills => old2/skills}/create-milestones/SKILL.md (100%) rename {skills => old2/skills}/dashboard/SKILL.md (100%) rename {skills => old2/skills}/dashboard/scripts/generate-dashboard.sh (100%) rename {skills => old2/skills}/ddd/SKILL.md (100%) rename {skills/capability-writing => old2/skills}/examples/progressive-disclosure.md (100%) rename {skills/capability-writing => old2/skills}/examples/simple-workflow.md (100%) rename {skills/capability-writing => old2/skills}/examples/with-scripts.md (100%) rename {skills => old2/skills}/issue-writing/SKILL.md (100%) rename {skills => old2/skills}/milestone-planning/SKILL.md (100%) rename {skills => old2/skills}/product-strategy/SKILL.md (100%) rename {skills/capability-writing => old2/skills}/reference/anti-patterns.md (100%) rename {skills/capability-writing => old2/skills}/reference/frontmatter-fields.md (100%) rename {skills/capability-writing => old2/skills}/reference/model-selection.md (100%) rename {skills/gitea/reference => old2/skills}/setup.md (100%) rename {skills => old2/skills}/spawn-issues/SKILL.md (100%) rename {skills => old2/skills}/spawn-pr-fixers/SKILL.md (100%) rename {skills => old2/skills}/spawn-pr-reviews/SKILL.md (100%) rename {skills/capability-writing => old2/skills}/templates/agent.md (100%) rename {skills/capability-writing => old2/skills}/templates/background-skill.md (100%) rename {skills/capability-writing => old2/skills}/templates/helper-script.sh (100%) rename {skills/capability-writing => old2/skills}/templates/user-invocable-skill.md (100%) rename {skills => old2/skills}/vision-to-backlog/SKILL.md (100%) rename {skills => old2/skills}/worktrees/SKILL.md (100%) rename {skills => old2/skills}/worktrees/scripts/cleanup-worktrees.sh (100%) rename {skills => old2/skills}/worktrees/scripts/create-worktree.sh (100%) rename {skills => old2/skills}/worktrees/scripts/list-worktrees.sh (100%) delete mode 100644 skills/capability-writing/SKILL.md diff --git a/agents/backlog-builder/AGENT.md b/old2/agents/AGENT.md similarity index 100% rename from agents/backlog-builder/AGENT.md rename to old2/agents/AGENT.md diff --git a/agents/capability-extractor/AGENT.md b/old2/agents/capability-extractor/AGENT.md similarity index 100% rename from agents/capability-extractor/AGENT.md rename to old2/agents/capability-extractor/AGENT.md diff --git a/agents/code-reviewer/AGENT.md b/old2/agents/code-reviewer/AGENT.md similarity index 100% rename from agents/code-reviewer/AGENT.md rename to old2/agents/code-reviewer/AGENT.md diff --git a/agents/context-mapper/AGENT.md b/old2/agents/context-mapper/AGENT.md similarity index 100% rename from agents/context-mapper/AGENT.md rename to old2/agents/context-mapper/AGENT.md diff --git a/agents/domain-modeler/AGENT.md b/old2/agents/domain-modeler/AGENT.md similarity index 100% rename from agents/domain-modeler/AGENT.md rename to old2/agents/domain-modeler/AGENT.md diff --git a/agents/issue-worker/AGENT.md b/old2/agents/issue-worker/AGENT.md similarity index 100% rename from agents/issue-worker/AGENT.md rename to old2/agents/issue-worker/AGENT.md diff --git a/agents/milestone-planner/AGENT.md b/old2/agents/milestone-planner/AGENT.md similarity index 100% rename from agents/milestone-planner/AGENT.md rename to old2/agents/milestone-planner/AGENT.md diff --git a/agents/pr-fixer/AGENT.md b/old2/agents/pr-fixer/AGENT.md similarity index 100% rename from agents/pr-fixer/AGENT.md rename to old2/agents/pr-fixer/AGENT.md diff --git a/agents/problem-space-analyst/AGENT.md b/old2/agents/problem-space-analyst/AGENT.md similarity index 100% rename from agents/problem-space-analyst/AGENT.md rename to old2/agents/problem-space-analyst/AGENT.md diff --git a/skills/gitea/SKILL.md b/old2/skills/SKILL.md similarity index 100% rename from skills/gitea/SKILL.md rename to old2/skills/SKILL.md diff --git a/skills/gitea/reference/actions-ci.md b/old2/skills/actions-ci.md similarity index 100% rename from skills/gitea/reference/actions-ci.md rename to old2/skills/actions-ci.md diff --git a/skills/capability-writing/best-practices.md b/old2/skills/best-practices.md similarity index 100% rename from skills/capability-writing/best-practices.md rename to old2/skills/best-practices.md diff --git a/skills/create-capability/SKILL.md b/old2/skills/create-capability/SKILL.md similarity index 100% rename from skills/create-capability/SKILL.md rename to old2/skills/create-capability/SKILL.md diff --git a/skills/create-milestones/SKILL.md b/old2/skills/create-milestones/SKILL.md similarity index 100% rename from skills/create-milestones/SKILL.md rename to old2/skills/create-milestones/SKILL.md diff --git a/skills/dashboard/SKILL.md b/old2/skills/dashboard/SKILL.md similarity index 100% rename from skills/dashboard/SKILL.md rename to old2/skills/dashboard/SKILL.md diff --git a/skills/dashboard/scripts/generate-dashboard.sh b/old2/skills/dashboard/scripts/generate-dashboard.sh similarity index 100% rename from skills/dashboard/scripts/generate-dashboard.sh rename to old2/skills/dashboard/scripts/generate-dashboard.sh diff --git a/skills/ddd/SKILL.md b/old2/skills/ddd/SKILL.md similarity index 100% rename from skills/ddd/SKILL.md rename to old2/skills/ddd/SKILL.md diff --git a/skills/capability-writing/examples/progressive-disclosure.md b/old2/skills/examples/progressive-disclosure.md similarity index 100% rename from skills/capability-writing/examples/progressive-disclosure.md rename to old2/skills/examples/progressive-disclosure.md diff --git a/skills/capability-writing/examples/simple-workflow.md b/old2/skills/examples/simple-workflow.md similarity index 100% rename from skills/capability-writing/examples/simple-workflow.md rename to old2/skills/examples/simple-workflow.md diff --git a/skills/capability-writing/examples/with-scripts.md b/old2/skills/examples/with-scripts.md similarity index 100% rename from skills/capability-writing/examples/with-scripts.md rename to old2/skills/examples/with-scripts.md diff --git a/skills/issue-writing/SKILL.md b/old2/skills/issue-writing/SKILL.md similarity index 100% rename from skills/issue-writing/SKILL.md rename to old2/skills/issue-writing/SKILL.md diff --git a/skills/milestone-planning/SKILL.md b/old2/skills/milestone-planning/SKILL.md similarity index 100% rename from skills/milestone-planning/SKILL.md rename to old2/skills/milestone-planning/SKILL.md diff --git a/skills/product-strategy/SKILL.md b/old2/skills/product-strategy/SKILL.md similarity index 100% rename from skills/product-strategy/SKILL.md rename to old2/skills/product-strategy/SKILL.md diff --git a/skills/capability-writing/reference/anti-patterns.md b/old2/skills/reference/anti-patterns.md similarity index 100% rename from skills/capability-writing/reference/anti-patterns.md rename to old2/skills/reference/anti-patterns.md diff --git a/skills/capability-writing/reference/frontmatter-fields.md b/old2/skills/reference/frontmatter-fields.md similarity index 100% rename from skills/capability-writing/reference/frontmatter-fields.md rename to old2/skills/reference/frontmatter-fields.md diff --git a/skills/capability-writing/reference/model-selection.md b/old2/skills/reference/model-selection.md similarity index 100% rename from skills/capability-writing/reference/model-selection.md rename to old2/skills/reference/model-selection.md diff --git a/skills/gitea/reference/setup.md b/old2/skills/setup.md similarity index 100% rename from skills/gitea/reference/setup.md rename to old2/skills/setup.md diff --git a/skills/spawn-issues/SKILL.md b/old2/skills/spawn-issues/SKILL.md similarity index 100% rename from skills/spawn-issues/SKILL.md rename to old2/skills/spawn-issues/SKILL.md diff --git a/skills/spawn-pr-fixers/SKILL.md b/old2/skills/spawn-pr-fixers/SKILL.md similarity index 100% rename from skills/spawn-pr-fixers/SKILL.md rename to old2/skills/spawn-pr-fixers/SKILL.md diff --git a/skills/spawn-pr-reviews/SKILL.md b/old2/skills/spawn-pr-reviews/SKILL.md similarity index 100% rename from skills/spawn-pr-reviews/SKILL.md rename to old2/skills/spawn-pr-reviews/SKILL.md diff --git a/skills/capability-writing/templates/agent.md b/old2/skills/templates/agent.md similarity index 100% rename from skills/capability-writing/templates/agent.md rename to old2/skills/templates/agent.md diff --git a/skills/capability-writing/templates/background-skill.md b/old2/skills/templates/background-skill.md similarity index 100% rename from skills/capability-writing/templates/background-skill.md rename to old2/skills/templates/background-skill.md diff --git a/skills/capability-writing/templates/helper-script.sh b/old2/skills/templates/helper-script.sh similarity index 100% rename from skills/capability-writing/templates/helper-script.sh rename to old2/skills/templates/helper-script.sh diff --git a/skills/capability-writing/templates/user-invocable-skill.md b/old2/skills/templates/user-invocable-skill.md similarity index 100% rename from skills/capability-writing/templates/user-invocable-skill.md rename to old2/skills/templates/user-invocable-skill.md diff --git a/skills/vision-to-backlog/SKILL.md b/old2/skills/vision-to-backlog/SKILL.md similarity index 100% rename from skills/vision-to-backlog/SKILL.md rename to old2/skills/vision-to-backlog/SKILL.md diff --git a/skills/worktrees/SKILL.md b/old2/skills/worktrees/SKILL.md similarity index 100% rename from skills/worktrees/SKILL.md rename to old2/skills/worktrees/SKILL.md diff --git a/skills/worktrees/scripts/cleanup-worktrees.sh b/old2/skills/worktrees/scripts/cleanup-worktrees.sh similarity index 100% rename from skills/worktrees/scripts/cleanup-worktrees.sh rename to old2/skills/worktrees/scripts/cleanup-worktrees.sh diff --git a/skills/worktrees/scripts/create-worktree.sh b/old2/skills/worktrees/scripts/create-worktree.sh similarity index 100% rename from skills/worktrees/scripts/create-worktree.sh rename to old2/skills/worktrees/scripts/create-worktree.sh diff --git a/skills/worktrees/scripts/list-worktrees.sh b/old2/skills/worktrees/scripts/list-worktrees.sh similarity index 100% rename from skills/worktrees/scripts/list-worktrees.sh rename to old2/skills/worktrees/scripts/list-worktrees.sh diff --git a/skills/capability-writing/SKILL.md b/skills/capability-writing/SKILL.md deleted file mode 100644 index 5fc3f1b..0000000 --- a/skills/capability-writing/SKILL.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -name: capability-writing -description: > - Guide for designing and creating capabilities for the architecture repository. - A capability is a cohesive set of components (skill + agent). - Use when creating new skills, agents, or extending the - AI workflow system. Includes templates, design guidance, and conventions. -user-invocable: false ---- - -# Capability Writing - -How to design and create capabilities for the architecture repository using Anthropic's latest best practices (January 2025). - -## Core Principles (NEW) - -### 1. Conciseness is Critical - -**Default assumption: Claude already knows.** - -- Don't explain git, tea, standard CLI tools -- Don't explain concepts Claude understands -- Only add domain-specific context -- Keep main SKILL.md under 500 lines - -**Bad:** "Git is a version control system. The commit command saves changes..." -**Good:** "`git commit -m 'feat: add feature'`" - -### 2. Progressive Disclosure - -Skills can bundle reference files and scripts that load/execute on-demand: - -``` -skill-name/ -├── SKILL.md # Main workflow (200-500 lines) -├── best-practices.md # Detailed guidance (loaded when referenced) -├── examples/ -│ ├── example1.md -│ └── example2.md -├── reference/ -│ ├── api-docs.md -│ └── checklists.md -└── scripts/ # Bundled with this skill - ├── validate.sh # Executed, not loaded into context - └── process.sh -``` - -**Benefits:** -- Main SKILL.md stays concise -- Reference files load only when Claude references them -- Scripts execute without consuming context tokens -- Each skill is self-contained - -### 3. Script Bundling - -Bundle error-prone bash operations as scripts within the skill: - -**Instead of inline bash:** -```markdown -5. Create PR: `tea pulls create --title "..." --description "..."` -``` - -**Bundle a script:** -```markdown -5. **Create PR**: `./scripts/create-pr.sh $issue "$title"` -``` - -```bash -# In skill-name/scripts/create-pr.sh -#!/bin/bash -set -e -# Script handles errors, retries, validation -``` - -**When to bundle scripts:** -- Operations with complex error handling -- Operations that need retries -- Operations with multiple validation steps -- Fragile bash operations - -### 4. Degrees of Freedom - -Match instruction style to task fragility: - -| Degree | When | Example | -|--------|------|---------| -| **High** (text) | Multiple valid approaches | "Review code quality and suggest improvements" | -| **Medium** (template) | Preferred pattern with variation | "Use this template, customize as needed" | -| **Low** (script) | Fragile operation, exact sequence | "Run: `./scripts/validate.sh`" | - -### 5. Model Selection (UPDATED) - -**New guidance:** Default to Haiku, justify if not. - -| Model | Use When | Cost vs Haiku | -|-------|----------|---------------| -| **Haiku** | Simple workflows, validated steps, with scripts | Baseline | -| **Sonnet** | When Haiku testing shows <80% success rate | 12x more expensive | -| **Opus** | Deep reasoning, architectural judgment | 60x more expensive | - -**Haiku works well when:** -- Steps are simple and validated -- Instructions are concise -- Error-prone operations use scripts -- Outputs have structured templates - -**Test with Haiku first.** Only upgrade if needed. - -## Component Overview - -| Component | Location | Purpose | Example | -|-----------|----------|---------|---------| -| **User-invocable Skill** | `skills/name/SKILL.md` | Workflow users trigger with `/name` | /work-issue, /dashboard | -| **Background Skill** | `skills/name/SKILL.md` | Knowledge auto-loaded when needed | gitea, issue-writing | -| **Agent** | `agents/name/AGENT.md` | Isolated subtask handler | code-reviewer | - -## When to Use Each Component - -### Decision Tree - -``` -Start here: What do you need? - | - +--> Just knowledge to apply automatically? - | --> Background skill (user-invocable: false) - | - +--> User-initiated workflow? - | --> User-invocable skill (user-invocable: true) - | - +--> Complex isolated work needing focused context? - | --> User-invocable skill + Agent - | - +--> New domain expertise + workflow + isolated work? - --> Full capability (background skill + user-invocable skill + agent) -``` - -**Detailed decision criteria:** See [best-practices.md](best-practices.md) - -## Component Templates - -### User-Invocable Skill Template - -```yaml ---- -name: skill-name -description: > - What this skill does and when to use it. - Use when [trigger conditions] or when user says /skill-name. -model: haiku -argument-hint: [optional] -user-invocable: true ---- - -# Skill Title - -@~/.claude/skills/relevant-skill/SKILL.md - -Brief intro if needed. - -1. **First step**: What to do -2. **Second step**: What to do next -3. **Ask for approval** before significant actions -4. **Execute** the approved actions -5. **Present results** with links and summary -``` - -**Complete template with all fields:** See [templates/user-invocable-skill.md](templates/user-invocable-skill.md) - -### Background Skill Template - -```yaml ---- -name: skill-name -description: > - What this skill teaches and when to use it. - Include trigger conditions in description. -user-invocable: false ---- - -# Skill Name - -Brief description of what this skill covers. - -## Core Concepts -## Patterns and Templates -## Guidelines -## Examples -``` - -**Complete template:** See [templates/background-skill.md](templates/background-skill.md) - -### Agent Template - -```yaml ---- -name: agent-name -description: What this agent does and when to spawn it -model: haiku -skills: skill1, skill2 -disallowedTools: - - Edit # For read-only agents - - Write ---- - -You are a [role] specialist that [primary function]. - -## When Invoked -1. **Gather context** -2. **Analyze** -3. **Act** -4. **Report** -``` - -**Complete template:** See [templates/agent.md](templates/agent.md) - -**Helper script template:** See [templates/helper-script.sh](templates/helper-script.sh) - -## Structure Examples - -### Simple Skill (< 300 lines, no scripts) -``` -skills/simple-skill/ -└── SKILL.md -``` - -### Progressive Disclosure (with reference files) -``` -skills/complex-skill/ -├── SKILL.md (~200 lines) -├── reference/ -│ ├── detailed-guide.md -│ └── api-reference.md -└── examples/ - └── usage-examples.md -``` - -### With Bundled Scripts -``` -skills/skill-with-scripts/ -├── SKILL.md -├── reference/ -│ └── error-handling.md -└── scripts/ - ├── validate.sh - └── process.sh -``` - -**Detailed examples:** See [examples/](examples/) folder - -## Referencing Skills - -### In User-Invocable Skills - -Use `@` file reference syntax to guarantee background skill content is loaded: - -```markdown -@~/.claude/skills/gitea/SKILL.md -@~/.claude/skills/issue-writing/SKILL.md -``` - -**Important:** Do NOT use phrases like "Use the gitea skill" - file references guarantee the content is available. - -### In Agents - -List skill names in frontmatter (not paths): - -```yaml ---- -name: product-manager -skills: gitea, issue-writing, backlog-grooming ---- -``` - -## Common Patterns - -### Approval Workflow -```markdown -4. **Present plan** for approval -5. **If approved**, create the issues -6. **Present summary** with links -``` - -### Conditional Behavior -```markdown -## If issue number provided ($1): -1. Fetch specific issue -2. Process it - -## If no argument (batch mode): -1. List all issues -2. Process each -``` - -### Spawning Agents -```markdown -9. **Auto-review**: Spawn the `code-reviewer` agent with the PR number -``` - -### Read-Only Agents -```yaml ---- -name: code-reviewer -disallowedTools: - - Edit - - Write ---- -``` - -## Quick Reference - -**Frontmatter fields:** See [reference/frontmatter-fields.md](reference/frontmatter-fields.md) -**Model selection:** See [reference/model-selection.md](reference/model-selection.md) -**Anti-patterns:** See [reference/anti-patterns.md](reference/anti-patterns.md) -**Best practices:** See [best-practices.md](best-practices.md) - -## Naming Conventions - -| Component | Convention | Examples | -|-----------|------------|----------| -| Skill folder | kebab-case | `software-architecture`, `work-issue` | -| Skill file | UPPERCASE | `SKILL.md` | -| Agent folder | kebab-case | `code-reviewer`, `issue-worker` | -| Agent file | UPPERCASE | `AGENT.md` | - -**Skills:** Name after domain/action (good: `gitea`, `work-issue`; bad: `utils`, `helpers`) -**Agents:** Name by role/persona (good: `code-reviewer`; bad: `helper`, `agent1`) - -## Checklists - -### Before Creating a User-Invocable Skill - -- [ ] Workflow is used multiple times -- [ ] User explicitly triggers it (not automatic) -- [ ] Clear start and end points -- [ ] Frontmatter has `user-invocable: true` -- [ ] Description includes "Use when... or when user says /skill-name" -- [ ] Background skills referenced via `@~/.claude/skills//SKILL.md` -- [ ] Approval checkpoints before significant actions -- [ ] File at `skills//SKILL.md` -- [ ] **Model defaults to `haiku`** unless justified - -### Before Creating a Background Skill - -- [ ] Knowledge is used in multiple places (not just once) -- [ ] Existing skills do not already cover this domain -- [ ] Content is specific and actionable (not generic) -- [ ] Frontmatter has `user-invocable: false` -- [ ] Description includes trigger terms -- [ ] File at `skills//SKILL.md` - -### Before Creating an Agent - -- [ ] Built-in agents (Explore, Plan) are not sufficient -- [ ] Context isolation or skill composition is needed -- [ ] Clear role/persona emerges -- [ ] `model` selection is deliberate (default to `haiku`) -- [ ] `skills` list is right-sized (not too many) -- [ ] File at `agents//AGENT.md`