Feat: adding skill files

skills/agent-md-refactor/LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2026 softaworks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

skills/agent-md-refactor/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: agent-md-refactor
+description: Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation.
+license: MIT
+metadata:
+  category: development
+  source:
+    repository: https://github.com/softaworks/agent-toolkit
+    path: skills/agent-md-refactor
+---
+
+# Agent MD Refactor
+
+Refactor bloated agent instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc.) to follow **progressive disclosure principles** - keeping essentials at root and organizing the rest into linked, categorized files.
+
+---
+
+## Triggers
+
+Use this skill when:
+- "refactor my AGENTS.md" / "refactor my CLAUDE.md"
+- "split my agent instructions"
+- "organize my CLAUDE.md file"
+- "my AGENTS.md is too long"
+- "progressive disclosure for my instructions"
+- "clean up my agent config"
+
+---
+
+## Quick Reference
+
+| Phase | Action | Output |
+|-------|--------|--------|
+| 1. Analyze | Find contradictions | List of conflicts to resolve |
+| 2. Extract | Identify essentials | Core instructions for root file |
+| 3. Categorize | Group remaining instructions | Logical categories |
+| 4. Structure | Create file hierarchy | Root + linked files |
+| 5. Prune | Flag for deletion | Redundant/vague instructions |
+
+---
+
+## Process
+
+### Phase 1: Find Contradictions
+
+Identify any instructions that conflict with each other.
+
+**Look for:**
+- Contradictory style guidelines (e.g., "use semicolons" vs "no semicolons")
+- Conflicting workflow instructions
+- Incompatible tool preferences
+- Mutually exclusive patterns
+
+**For each contradiction found:**
+```markdown
+## Contradiction Found
+
+**Instruction A:** [quote]
+**Instruction B:** [quote]
+
+**Question:** Which should take precedence, or should both be conditional?
+```
+
+Ask the user to resolve before proceeding.
+
+---
+
+### Phase 2: Identify the Essentials
+
+Extract ONLY what belongs in the root agent file. The root should be minimal - information that applies to **every single task**.
+
+**Essential content (keep in root):**
+| Category | Example |
+|----------|---------|
+| Project description | One sentence: "A React dashboard for analytics" |
+| Package manager | Only if not npm (e.g., "Uses pnpm") |
+| Non-standard commands | Custom build/test/typecheck commands |
+| Critical overrides | Things that MUST override defaults |
+| Universal rules | Applies to 100% of tasks |
+
+**NOT essential (move to linked files):**
+- Language-specific conventions
+- Testing guidelines
+- Code style details
+- Framework patterns
+- Documentation standards
+- Git workflow details
+
+---
+
+### Phase 3: Group the Rest
+
+Organize remaining instructions into logical categories.
+
+**Common categories:**
+| Category | Contents |
+|----------|----------|
+| `typescript.md` | TS conventions, type patterns, strict mode rules |
+| `testing.md` | Test frameworks, coverage, mocking patterns |
+| `code-style.md` | Formatting, naming, comments, structure |
+| `git-workflow.md` | Commits, branches, PRs, reviews |
+| `architecture.md` | Patterns, folder structure, dependencies |
+| `api-design.md` | REST/GraphQL conventions, error handling |
+| `security.md` | Auth patterns, input validation, secrets |
+| `performance.md` | Optimization rules, caching, lazy loading |
+
+**Grouping rules:**
+1. Each file should be self-contained for its topic
+2. Aim for 3-8 files (not too granular, not too broad)
+3. Name files clearly: `{topic}.md`
+4. Include only actionable instructions
+
+---
+
+### Phase 4: Create the File Structure
+
+**Output structure:**
+```
+project-root/
+├── CLAUDE.md (or AGENTS.md)     # Minimal root with links
+└── .claude/                      # Or docs/agent-instructions/
+    ├── typescript.md
+    ├── testing.md
+    ├── code-style.md
+    ├── git-workflow.md
+    └── architecture.md
+```
+
+**Root file template:**
+```markdown
+# Project Name
+
+One-sentence description of the project.
+
+## Quick Reference
+
+- **Package Manager:** pnpm
+- **Build:** `pnpm build`
+- **Test:** `pnpm test`
+- **Typecheck:** `pnpm typecheck`
+
+## Detailed Instructions
+
+For specific guidelines, see:
+- [TypeScript Conventions](.claude/typescript.md)
+- [Testing Guidelines](.claude/testing.md)
+- [Code Style](.claude/code-style.md)
+- [Git Workflow](.claude/git-workflow.md)
+- [Architecture Patterns](.claude/architecture.md)
+```
+
+**Each linked file template:**
+```markdown
+# {Topic} Guidelines
+
+## Overview
+Brief context for when these guidelines apply.
+
+## Rules
+
+### Rule Category 1
+- Specific, actionable instruction
+- Another specific instruction
+
+### Rule Category 2
+- Specific, actionable instruction
+
+## Examples
+
+### Good
+\`\`\`typescript
+// Example of correct pattern
+\`\`\`
+
+### Avoid
+\`\`\`typescript
+// Example of what not to do
+\`\`\`
+```
+
+---
+
+### Phase 5: Flag for Deletion
+
+Identify instructions that should be removed entirely.
+
+**Delete if:**
+| Criterion | Example | Why Delete |
+|-----------|---------|------------|
+| Redundant | "Use TypeScript" (in a .ts project) | Agent already knows |
+| Too vague | "Write clean code" | Not actionable |
+| Overly obvious | "Don't introduce bugs" | Wastes context |
+| Default behavior | "Use descriptive variable names" | Standard practice |
+| Outdated | References deprecated APIs | No longer applies |
+
+**Output format:**
+```markdown
+## Flagged for Deletion
+
+| Instruction | Reason |
+|-------------|--------|
+| "Write clean, maintainable code" | Too vague to be actionable |
+| "Use TypeScript" | Redundant - project is already TS |
+| "Don't commit secrets" | Agent already knows this |
+| "Follow best practices" | Meaningless without specifics |
+```
+
+---
+
+## Execution Checklist
+
+```
+[ ] Phase 1: All contradictions identified and resolved
+[ ] Phase 2: Root file contains ONLY essentials
+[ ] Phase 3: All remaining instructions categorized
+[ ] Phase 4: File structure created with proper links
+[ ] Phase 5: Redundant/vague instructions removed
+[ ] Verify: Each linked file is self-contained
+[ ] Verify: Root file is under 50 lines
+[ ] Verify: All links work correctly
+```
+
+---
+
+## Anti-Patterns
+
+| Avoid | Why | Instead |
+|-------|-----|---------|
+| Keeping everything in root | Bloated, hard to maintain | Split into linked files |
+| Too many categories | Fragmentation | Consolidate related topics |
+| Vague instructions | Wastes tokens, no value | Be specific or delete |
+| Duplicating defaults | Agent already knows | Only override when needed |
+| Deep nesting | Hard to navigate | Flat structure with links |
+
+---
+
+## Examples
+
+### Before (Bloated Root)
+```markdown
+# CLAUDE.md
+
+This is a React project.
+
+## Code Style
+- Use 2 spaces
+- Use semicolons
+- Prefer const over let
+- Use arrow functions
+... (200 more lines)
+
+## Testing
+- Use Jest
+- Coverage > 80%
+... (100 more lines)
+
+## TypeScript
+- Enable strict mode
+... (150 more lines)
+```
+
+### After (Progressive Disclosure)
+```markdown
+# CLAUDE.md
+
+React dashboard for real-time analytics visualization.
+
+## Commands
+- `pnpm dev` - Start development server
+- `pnpm test` - Run tests with coverage
+- `pnpm build` - Production build
+
+## Guidelines
+- [Code Style](.claude/code-style.md)
+- [Testing](.claude/testing.md)
+- [TypeScript](.claude/typescript.md)
+```
+
+---
+
+## Verification
+
+After refactoring, verify:
+
+1. **Root file is minimal** - Under 50 lines, only universal info
+2. **Links work** - All referenced files exist
+3. **No contradictions** - Instructions are consistent
+4. **Actionable content** - Every instruction is specific
+5. **Complete coverage** - No instructions were lost (unless flagged for deletion)
+6. **Self-contained files** - Each linked file stands alone
+
+---