YouTube Audio Extension Development

An AI agent skill for developing and maintaining the YouTube Audio browser extension, which allows users to stream only audio from YouTube videos to save battery life and bandwidth.

Technology Stack

Core Workflow

Rule 1: Documentation First

**"No spec, no code."**

Before writing any code:

1. Create or update specification in `docs/specs/`

2. After writing code, update `docs/history/` with handoff record

3. Architecture changes require updates to `docs/architecture/`

Rule 2: Check Before You Code

**"Avoid regression by learning from history."**

Before making changes:

1. Check `docs/adrs/` for past architectural decisions

2. Review existing specs to understand design rationale

3. Search codebase for similar patterns before creating new ones

Rule 3: Update Documentation

**"Code and docs must stay synchronized."**

After modifying code, you **MUST**:

Rule 4: Research, Don't Hallucinate

**"If you're unsure, search the internet."**

Step-by-Step Instructions

Before Any Work

1. **Read Required Documentation** (in order):

- All files in `docs/agent-instructions/` (00 → 03)

- Check `docs/adrs/` for architectural decisions

- Review `docs/specs/` for existing specifications

- Understand `docs/architecture/` system design

2. **Understand the Request**:

- Clarify if it's a feature, bug fix, or refactor

- Identify affected components

- Check for related past decisions

Adding a New Feature

1. Write specification in `docs/specs/SPEC-NNN-feature.md`

2. Update architecture documentation if needed

3. Write tests first (aim for 90%+ coverage)

4. Implement the feature using coding standards

5. Verify coverage meets 90% minimum

6. Run `./scripts/validate.sh`

7. Record handoff in `docs/history/`

Fixing a Bug

1. Check `docs/history/` for related context

2. Write a failing test that reproduces the bug

3. Fix the bug in the codebase

4. Verify the test passes

5. Update documentation if behavior changed

6. Run validation script

Updating Dependencies

1. Research the update (breaking changes, security fixes)

2. Create ADR documenting the decision in `docs/adrs/`

3. Update `manifest.json` or `package.json`

4. Run full test suite

5. Update related documentation

Code Review Checklist

Before completing any task:

Coding Standards

JavaScript Guidelines

Browser Extension Best Practices

Testing Requirements

File Structure

```

youtube-audio/

├── css/ # Stylesheets

├── docs/ # Documentation (THE BRAIN)

│ ├── adrs/ # Architecture Decision Records

│ ├── agent-instructions/ # Agent protocols

│ ├── architecture/ # System diagrams

│ ├── history/ # Handoffs and deprecated logic

│ └── specs/ # Technical specifications

├── html/ # HTML pages

├── img/ # Icons and images

├── js/ # JavaScript source

├── scripts/ # Automation scripts

├── tests/ # Test files

├── .github/ # GitHub configuration

└── .claude/ # Claude agent configs

```

Quick Reference Commands

| Task | Command |

| ------------------- | ----------------------- |

| Run all validations | `./scripts/validate.sh` |

| Run linter | `npm run lint` |

| Run tests | `npm test` |

| Check coverage | `npm run test:coverage` |

Important Constraints

1. **Never proceed without reading documentation first** - Check `docs/agent-instructions/`, `docs/adrs/`, `docs/specs/`, and `docs/architecture/` before any work

2. **No code without specs** - Always create or update specification before implementing

3. **90% coverage is mandatory** - New code must meet this threshold

4. **Research, don't guess** - Use web search to verify APIs and library versions

5. **Documentation synchronization** - Code changes require corresponding documentation updates

When Unsure

If uncertain about any aspect:

1. Check documentation in `docs/`

2. Search codebase for examples

3. Research using web search for official documentation

4. Ask for clarification rather than making assumptions

---

This skill follows the AI-Enabled Repository Standard where documentation drives code, testing is mandatory, and agents must validate their work before completion.