Create and manage local Issue specs (specs/issues/) - individual work items with testable acceptance criteria. Use for "create issue", "new task", "list issues", "check issues", "pick issue". NOTE - For GitHub issues, use `gh issue` command directly.
npxskills add skilluse/skilluse--skill issueLoading…
Create and manage Issues with testable acceptance criteria.
project/
└── specs/
├── epics/
│ └── epic-name/
│ ├── epic.md
│ └── progress.md
└── issues/
├── 20250115-task01-auth-setup/
│ ├── issue.md # Issue requirements
│ └── feature.json # Testable acceptance criteria
└── 20250116-web01-landing-page/
├── issue.md
└── feature.json
An Issue is a single work item with testable acceptance criteria.
Components:
issue.md - Requirements and technical detailsfeature.json - Tracking work progress with pass/fail statusNaming convention: YYYYMMDD-issueID-short-description/
YYYYMMDDtaskNN, webNN, cfgNN, bugNN, etc.auth-setup, landing-page, etc.Before creating or updating any Issue, you MUST:
Read Epic Context First
# Read the related Epic's files
cat specs/epics/EPIC_NAME/epic.md # Understand goals and existing issues
cat specs/epics/EPIC_NAME/progress.md # Check current sprint status
ls specs/epics/EPIC_NAME/references/ # Review design docs and specs
After Creating/Updating Issue
epic.md - Add new issue to "Related Issues" tableprogress.md - Log the action takenThis ensures Issues are consistent with Epic's design and requirements.
# Identify the related Epic and read its context
cat specs/epics/EPIC_NAME/epic.md # Goals, existing issues
cat specs/epics/EPIC_NAME/progress.md # Current sprint status
cat specs/epics/EPIC_NAME/references/*.md # Design specs, requirements
mkdir -p specs/issues/YYYYMMDD-issueID-short-description
# [Issue Title]
## Overview
Brief description of what this issue accomplishes.
## Requirements
- Requirement 1
- Requirement 2
- Requirement 3
## Technical Details
### API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| POST | /api/xxx | Description |
### Data Models
Model { field1: type field2: type }
### Dependencies
- Library/package dependencies
- External service dependencies
## Acceptance Criteria
See `feature.json` for testable criteria.
## Issue Dependencies
- [ ] issueNN-xxx (must be completed first)
## Out of Scope
- What this issue does NOT include
{
"issue": "task01-auth-setup",
"title": "Authentication System Setup",
"epic": "cli",
"priority": 1,
"status": "pending",
"created_at": "2025-01-15",
"completed_at": null,
"dependencies": [],
"parallelizable": true,
"features": [
{
"id": "F001",
"category": "functional",
"description": "User can register with email and password",
"steps": [
"Step 1: Navigate to /register",
"Step 2: Fill in email and password",
"Step 3: Submit the form",
"Step 4: Verify success message"
],
"passes": false,
"notes": ""
}
],
"metadata": {
"estimated_sessions": 1,
"actual_sessions": 0,
"blockers": []
}
}
This step is mandatory. Update the Epic to reflect the new issue:
Update epic.md - Add to "Related Issues" table:
| Issue | Title | Status |
|-------|-------|--------|
| task01-auth-setup | Authentication Setup | pending |
Update progress.md - Log the creation:
[YYYY-MM-DD HH:MM] Created issue task01-auth-setup: Authentication Setup
git add specs/issues/YYYYMMDD-issueID-*/ specs/epics/EPIC_NAME/
git commit -m "feat: create issue task01-auth-setup"
# Always read Epic context before making changes
cat specs/epics/EPIC_NAME/epic.md
cat specs/epics/EPIC_NAME/progress.md
Add an "Updates" section to document changes:
## Updates (YYYY-MM-DD)
### Issue: [Brief description]
- **Problem**: What was wrong
- **Solution**: How it was fixed
- **Files**: Which files were modified
Mark completed features:
{
"id": "F001",
"description": "Feature description",
"passes": true,
"notes": "Fixed YYYY-MM-DD: Brief explanation"
}
Update issue status:
{
"status": "in-progress",
"completed_at": "2025-01-15"
}
This step is mandatory. Update both Epic files:
Update epic.md - Change issue status if needed:
| task01-auth-setup | Authentication Setup | completed |
Update progress.md - Log the changes:
[YYYY-MM-DD HH:MM] Updated issue-name: brief description
| Size | Features | Sessions | Example |
|---|---|---|---|
| Small | 2-4 | 1 | Add logout button |
| Medium | 5-8 | 1-2 | User authentication |
| Large | 8+ | Split it! | - |
If an issue has more than 8 features, split it into smaller issues.
The parallelizable field indicates if an issue can be worked on by a background AI agent.
parallelizable: true when:parallelizable: false when:issue.md and feature.json"passes": falseTemplate files:
references/feature.template.jsonreferences/issue.template.md
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).