Agent skill

Skill Issues

by nyldn in nyldn/claude-octopus

Track project blockers, bugs, and gaps across sessions — use when issues pile up or need triage

MITAuto-check passedProductivity & Automation

Install Skill Issues

skills CLI
$ npx skills add nyldn/claude-octopus --skill skill-issues -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install nyldn/claude-octopus skill-issues --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/nyldn/claude-octopus.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/skill-issues .claude/skills/skill-issues && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
skill-issues
GitHub stars
4.2k
Used in
1 other repo
Token cost
~2.7k tokens
SKILL.md length
599 words
Files
2
Skills in repo
62
Repo updated
First seen
Licence
MIT

At a glance

Track project blockers, bugs, and gaps across sessions — use when issues pile up or need triage

  • Works in 7 steps: List Issues (Default) → Add Issue → Resolve Issue → …
  • Productivity & Automation work in your project
  • SKILL.md covers Overview, When to Use, Subcommands and File Management, plus 8 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Skill Issues is an agent skill from nyldn/claude-octopus. Track project blockers, bugs, and gaps across sessions — use when issues pile up or need triage

Its SKILL.md is about 2.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files (for example `agents/openai.yaml`).

It sits in Productivity & Automation. The repository describes itself as: Run multiple AI models against the same research, design, or coding task. Surface disagreements before you ship. The licence is MIT.

When your agent uses it

  • Productivity & Automation work in your project

Example prompts

  • “/skill-issues”

Workflow steps

7 steps, taken from the step headings in SKILL.md.

  1. List Issues (Default)
  2. Add Issue
  3. Resolve Issue
  4. Show Issue Details
  5. Clear Descriptions
  6. Appropriate Severity
  7. Resolution Notes

What it can do on your machine

Read from SKILL.md and the folder at commit 18b66ca. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown, bash and javascript).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Skill Issues loads about 2.7k tokens when it runs. Until then it costs about 27 tokens; SKILL.md has 599 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~27
When it runs · the whole SKILL.md, loaded when a task matches
~2.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from nyldn/claude-octopus at commit 18b66ca, republished under its MIT licence (© nyldn). 599 words, ~2,717 tokens.

Download SKILL.mdSave it as .claude/skills/skill-issues/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
skill-issues
description
Track project blockers, bugs, and gaps across sessions — use when issues pile up or need triage
disable-model-invocation
true

Host: Codex CLI — This skill was designed for Claude Code and adapted for Codex. Cross-reference commands use installed skill names in Codex rather than /octo:* slash commands. Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. For host tool equivalents, see skills/blocks/codex-host-adapter.md.

Issue Tracking

Overview

Cross-session issue tracking for persistent problem management. Issues are stored in .octo/ISSUES.md and survive across Claude Code sessions.

Core principle: Track → Resolve → Learn.

When to Use

Use this skill when user wants to:

  • Track a problem or blocker for later
  • Record issues discovered during development
  • Review open issues across sessions
  • Mark issues as resolved
  • View details of specific issues

Do NOT use for:

  • GitHub issue management (use gh CLI)
  • Git-tracked issues (use git commands)
  • Temporary todos (use task plan tool)

Subcommands

1. List Issues (Default)

Trigger: /octo:issues or /octo:issues list

Show all open issues in table format:

markdown
## Open Issues

| ID | Severity | Category | Description | Created | Phase |
|----|----------|----------|-------------|---------|-------|
| ISS-20260203-001 | high | integration | Auth not working | 2026-02-03 | Develop |
| ISS-20260203-002 | medium | performance | Slow query performance | 2026-02-03 | Deliver |

Pattern Detection: After listing, check if 3+ open issues share the same category. If so, alert:

text
⚠ Pattern detected: 3 open issues in category "integration" — may indicate a systemic problem.

Implementation:

  1. Check if .octo/ISSUES.md exists
  2. If not, initialize from template
  3. Read and parse Open Issues section
  4. Display in table format
2. Add Issue

Trigger: /octo:issues add <description>

Add new issue with auto-generated ID.

Flow:

Step 1: Gather Information

Use AskUserQuestion with two questions:

javascript
AskUserQuestion({
  questions: [
    {
      question: "What severity is this issue?",
      header: "Severity",
      multiSelect: false,
      options: [
        {label: "critical", description: "Blocks all progress"},
        {label: "high", description: "Significant impact"},
        {label: "medium", description: "Should address"},
        {label: "low", description: "Nice to fix"}
      ]
    },
    {
      question: "What category does this issue fall into?",
      header: "Category",
      multiSelect: false,
      options: [
        {label: "logic-error", description: "Incorrect behavior or wrong output"},
        {label: "integration", description: "Cross-component or API compatibility"},
        {label: "quality-gate", description: "Quality gate failures during workflows"},
        {label: "security", description: "Security vulnerabilities or concerns"},
        {label: "performance", description: "Speed, memory, or scalability issues"},
        {label: "ux", description: "User experience or usability problems"},
        {label: "architecture", description: "Structural or design pattern issues"}
      ]
    }
  ]
})
Step 2: Determine Current Phase
bash
# Check if STATE.md exists
if [ -f .octo/STATE.md ]; then
  grep "current_phase:" .octo/STATE.md
else
  echo "Unknown"
fi
Step 3: Generate Issue ID

Format: ISS-YYYYMMDD-NNN

bash
# Get today's date
TODAY=$(date +%Y%m%d)

# Find existing issues for today
grep "ISS-${TODAY}-" .octo/ISSUES.md | tail -1

# Increment sequence number
# If ISS-20260203-001 exists, next is ISS-20260203-002
Step 4: Append to ISSUES.md

Add new row to Open Issues table:

markdown
| ISS-20260203-003 | medium | performance | Slow query performance | 2026-02-03 | Develop |

Preserve existing issues - append only, don't overwrite.

Step 5: Confirm
markdown
✅ Issue created: ISS-20260203-003

**Severity:** medium
**Category:** performance
**Description:** Slow query performance
**Created:** 2026-02-03
**Phase:** Develop

View with: /octo:issues show ISS-20260203-003
3. Resolve Issue

Trigger: /octo:issues resolve <id>

Mark issue as resolved and move to Resolved section.

Flow:

Step 1: Validate Issue Exists
bash
# Check if issue ID exists in Open Issues
grep "ISS-20260203-001" .octo/ISSUES.md

If not found, show error:

markdown
❌ Issue ISS-20260203-001 not found in open issues.

Use `/octo:issues list` to see all open issues.
Step 2: Ask for Resolution Notes
markdown
**Resolving issue:** ISS-20260203-001

Please provide resolution notes:
Step 3: Move to Resolved Section
  1. Extract issue row from Open Issues table
  2. Remove from Open Issues
  3. Add to Resolved Issues with resolution date and notes

Resolved Issues format:

markdown
| ID | Severity | Category | Description | Created | Resolved | Resolution |
|----|----------|----------|-------------|---------|----------|------------|
| ISS-20260203-001 | high | integration | Auth not working | 2026-02-03 | 2026-02-04 | Fixed OAuth token refresh |
Step 4: Confirm
markdown
✅ Issue resolved: ISS-20260203-001

**Resolution date:** 2026-02-04
**Resolution notes:** Fixed OAuth token refresh

View with: /octo:issues show ISS-20260203-001
4. Show Issue Details

Trigger: /octo:issues show <id>

Display full details of specific issue.

Flow:

Step 1: Find Issue

Search both Open and Resolved sections for issue ID.

Step 2: Display Details

For open issue:

markdown
## Issue Details: ISS-20260203-001

**Status:** Open
**Severity:** high
**Category:** integration
**Description:** Auth not working
**Created:** 2026-02-03
**Phase:** Develop

**Actions:**
- Resolve: `/octo:issues resolve ISS-20260203-001`

For resolved issue:

markdown
## Issue Details: ISS-20260203-001

**Status:** Resolved
**Severity:** high
**Category:** integration
**Description:** Auth not working
**Created:** 2026-02-03
**Resolved:** 2026-02-04
**Resolution:** Fixed OAuth token refresh
Show full SKILL.md (238 more words)Show less
Step 3: If Not Found
markdown
❌ Issue ISS-20260203-001 not found.

Use `/octo:issues list` to see all open issues.

File Management

Initialize ISSUES.md

When: First time skill is used or .octo/ISSUES.md doesn't exist.

Action:

bash
# Create .octo directory if needed
mkdir -p .octo

# Copy template
cp ${HOME}/.claude-octopus/plugin/config/templates/ISSUES.md.template .octo/ISSUES.md

# Replace {{PROJECT_NAME}} with actual project name
PROJECT_NAME=$(basename $(pwd))
sed -i '' "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" .octo/ISSUES.md
Preserve Existing Issues

CRITICAL: When adding or resolving issues, NEVER overwrite existing content.

Pattern:

bash
# Read existing content
EXISTING=$(cat .octo/ISSUES.md)

# Modify specific section only
# Append new issue to Open Issues table
# OR move issue from Open to Resolved

# Write back with all content preserved
echo "$MODIFIED" > .octo/ISSUES.md

ID Generation Algorithm

Format: ISS-YYYYMMDD-NNN

Example: ISS-20260203-001

Implementation:

bash
#!/bin/bash

# Get today's date in YYYYMMDD format
TODAY=$(date +%Y%m%d)

# Find all issues created today
TODAY_ISSUES=$(grep -o "ISS-${TODAY}-[0-9]\{3\}" .octo/ISSUES.md || echo "")

if [ -z "$TODAY_ISSUES" ]; then
  # No issues today, start at 001
  NEXT_NUM="001"
else
  # Get highest number for today
  HIGHEST=$(echo "$TODAY_ISSUES" | sed "s/ISS-${TODAY}-//" | sort -n | tail -1)
  
  # Increment
  NEXT_NUM=$(printf "%03d" $((10#$HIGHEST + 1)))
fi

# Generate ID
ISSUE_ID="ISS-${TODAY}-${NEXT_NUM}"
echo "$ISSUE_ID"

Severity Levels

LevelMeaningExample
criticalBlocks all progressProduction down, data loss
highSignificant impactFeature broken, security issue
mediumShould addressPerformance degradation, UX issue
lowNice to fixMinor bug, cosmetic issue

Integration with Other Skills

With skill-debug
User: "track this bug for later"

1. Use skill-issues to create issue
2. Use skill-debug to investigate if time permits
3. Link issue ID in debug notes
With skill-task-management
User: "add fixing ISS-20260203-001 to todos"

1. Use skill-task-management to add todo
2. Reference issue ID in todo description
3. Mark issue as resolved when todo completes
With flow-develop
User: "implement fix for ISS-20260203-001"

1. Use flow-develop to implement fix
2. Use skill-issues to resolve issue after fix
3. Link commit SHA in resolution notes

Best Practices

1. Clear Descriptions

Good:

Auth token refresh fails after 15 minutes

Poor:

Auth broken
2. Appropriate Severity

Critical: Only for blockers that stop all work High: Significant but workarounds exist Medium: Should fix but not urgent Low: Nice to have

3. Resolution Notes

Good:

Fixed OAuth token refresh by updating expiration logic in auth.ts
Commit: abc123

Poor:

Fixed

Common Patterns

Pattern 1: Track During Development
User: "track this issue: API rate limiting not working"

Action:
1. Create issue with appropriate severity
2. Record current phase from STATE.md
3. Continue development
Pattern 2: Resolve After Fix
User: "resolve ISS-20260203-001, fixed in commit abc123"

Action:
1. Ask for resolution notes
2. Move to Resolved section
3. Record resolution date and notes
Pattern 3: Review Open Issues
User: "what issues do we have?"

Action:
1. List all open issues
2. Show severity and phase
3. Offer to show details or resolve

Red Flags - Don't Do This

ActionWhy It's Wrong
Overwrite ISSUES.mdLose all existing issues
Skip severity validationInvalid data in file
Duplicate issue IDsID collision
Vague descriptionsCan't remember what issue was
Resolve without notesNo record of what was done

Quick Reference

User IntentSkill ActionOutput
"list issues"Read and display Open IssuesTable of issues
"add issue X"Generate ID, append to fileIssue created
"resolve ISS-X"Move to Resolved sectionIssue resolved
"show ISS-X"Find and display detailsIssue details

The Bottom Line

Issue tracking → Persistent memory across sessions
Otherwise → Forget problems, repeat mistakes

Track everything. Resolve systematically. Learn from history.

© nyldn, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in skills/skill-issues of nyldn/claude-octopus.

  • SKILL.md
  • agents/openai.yaml

Open the folder on GitHubat commit 18b66ca

Used in 1 other repository

We found 2 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in nyldn/claude-octopus, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Skill Issues next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Skill Issues compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Skill Issues this skillnyldn/claude-octopus4.2k1 repos~2.7kAutomated safety check: PassMIT
Agent Browserquran/quran.com-frontend-next1.9k41 repos~3.3kAutomated safety check: PassNone
Process Inboxtelegramdesktop/tdesktop33k2 repos~4.5kAutomated safety check: PassGPL-3.0
Perform Tasktelegramdesktop/tdesktop33k2 repos~3kAutomated safety check: PassGPL-3.0
Brave Searchbadlogic/pi-skills2.6k6 repos~592Automated safety check: PassMIT
Continuetelegramdesktop/tdesktop33k2 repos~9.4kAutomated safety check: PassGPL-3.0

Similar skills

  • Agent Browser

    quran/quran.com-frontend-next

    Automates browser interactions for web testing, form filling, screenshots, and data extraction.

    1.9k GitHub starsUsed in 41 repos~3.3k tokens
    Productivity & AutomationAuto-check passed
  • Process Inbox

    telegramdesktop/tdesktop

    Process the local ignored ai-tdesktop inbox into durable, independently testable Telegram Desktop task records while task execution worktrees remain active.

    33k GitHub starsUsed in 2 repos~4.5k tokens
    Productivity & AutomationAuto-check passed
  • Perform Task

    telegramdesktop/tdesktop

    Resolve, start or resume, implement, review, test, and publish exactly one existing ai-tdesktop task by short slug or full dated id, including rare blocked retries and split-required results.

    33k GitHub starsUsed in 2 repos~3k tokens
    Productivity & AutomationAuto-check passed
  • Brave Search

    badlogic/pi-skills

    Web search and content extraction via Brave Search API. An agent skill from badlogic/pi-skills.

    2.6k GitHub starsUsed in 6 repos~592 tokens
    Productivity & AutomationAuto-check passed
  • Continue

    telegramdesktop/tdesktop

    Continue autonomous Telegram Desktop development from the shared ai-tdesktop repository.

    33k GitHub starsUsed in 2 repos~9.4k tokens
    Productivity & AutomationAuto-check passed
  • Garden Inbox

    paperclipai/paperclip

    Scan a Paperclip user's Mine inbox, classify reversible archive candidates, request checkbox confirmation, and archive only accepted selections.

    98k GitHub stars~1.1k tokensUpdated today
    Productivity & AutomationAuto-check passed

More from nyldn/claude-octopus

All 62 skills in this repo
  • Octopus Quick

    nyldn/claude-octopus

    Quick execution for ad-hoc tasks without full workflow overhead — use for small, self-contained requests

    4.2k GitHub starsUsed in 1 repo~2.2k tokens
    Auto-check passed
  • Octopus Research

    nyldn/claude-octopus

    Thorough research across multiple sources — use for complex topics needing broad synthesis

    4.2k GitHub starsUsed in 1 repo~1.9k tokens
    Auto-check passed
  • Octopus Security Audit

    nyldn/claude-octopus

    OWASP compliance, vulnerability scanning, and adversarial red team testing — use for security reviews

    4.2k GitHub starsUsed in 1 repo~2.3k tokens
    Auto-check passed
  • Skill Audit

    nyldn/claude-octopus

    Audit codebases for quality, consistency, and broken patterns — use for pre-release or tech debt review

    4.2k GitHub starsUsed in 1 repo~3.2k tokens
    Auto-check passed
  • Skill Content Pipeline

    nyldn/claude-octopus

    Extract patterns and anatomy from URLs — use to reverse-engineer content strategies from live pages

    4.2k GitHub starsUsed in 1 repo~3.9k tokens
    Auto-check passed
  • Skill Context Detection

    nyldn/claude-octopus

    Auto-detect work context (Dev vs Knowledge) — use to tailor workflows based on current task type

    4.2k GitHub starsUsed in 1 repo~2.6k tokens
    Auto-check passed

Questions about Skill Issues

What does Skill Issues do?

Track project blockers, bugs, and gaps across sessions — use when issues pile up or need triage. Skill Issues is an agent skill from nyldn/claude-octopus.

When should I use Skill Issues?

Skill Issues fits situations like: productivity & Automation work in your project.

How do I install Skill Issues in Claude Code?

Run `npx skills add nyldn/claude-octopus --skill skill-issues -a claude-code`. Or copy the skill folder (skills/skill-issues in nyldn/claude-octopus) into .claude/skills/skill-issues in your project. Claude Code loads it when a task matches its description.

How do I install Skill Issues in Codex?

Run `npx skills add nyldn/claude-octopus --skill skill-issues -a codex`. Or copy the skill folder (skills/skill-issues in nyldn/claude-octopus) into .agents/skills/skill-issues in your project. Codex loads it when a task matches its description.

Can I use Skill Issues in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add nyldn/claude-octopus --skill skill-issues -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/skill-issues, .gemini/skills/skill-issues, .github/skills/skill-issues and .opencode/skills/skill-issues in your project.

What does Skill Issues need to run?

SKILL.md names no scripts, command-line tools or credentials: Skill Issues is instructions for the agent only.

Does Skill Issues access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Skill Issues safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Skill Issues use?

Skill Issues is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Skill Issues use?

About 2.7k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Skill Issues?

Skills that share tags, products or a category with Skill Issues: Agent Browser (quran/quran.com-frontend-next, 1.9k stars), Process Inbox (telegramdesktop/tdesktop, 33k stars), Perform Task (telegramdesktop/tdesktop, 33k stars) and Brave Search (badlogic/pi-skills, 2.6k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Skill Issues?

nyldn (a GitHub user) maintains it in nyldn/claude-octopus, which has 4,173 GitHub stars. The repository holds 62 skills in this directory. The repository was last updated on October 7, 2026.

Source: nyldn/claude-octopus on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.