Skill Taxonomy & Classification Guide

ci-cd/
├── github-actions/{generator,validator}
├── gitlab-ci/{generator,validator}
└── ...

infrastructure/
├── terraform/{generator,validator}
├── cfn/
│   ├── behavior-validator/
│   └── template-compare/
└── aws-cdk/
    └── cdk-nag/

repository-mgmt/
└── nx/
    ├── workspace-patterns/
    ├── executors/
    └── ...

development/
├── bun-development/
├── typescript-advanced/
├── scripting/
│   ├── bash-script/{generator,validator}
│   └── makefile/{generator,validator}
└── front-end/
    ├── web-reference-sheet-generator/
    └── website-theme-porter/

agentic-harness/
├── opencode/
├── agents-md/
└── [future: cursor, claude-desktop, etc.]

testing/
├── bdd-testing/
├── test-driven-development/
├── skill-quality-auditor/
└── ui-debug-workflow/

software-engineering/
├── solid-principles/
├── clean-architecture/
├── design-patterns/
├── testable-design/
└── design-principles/tile.json  (unified tile)

---

### observability/
**Scope:** Monitoring, logging, debugging, metrics, alerting

**Includes:**
- PromQL (Prometheus query language)
- LogQL (Loki query language)
- K8s debugging tools

**Excludes:**
- Testing frameworks (use testing/ instead)
- CI/CD pipelines (use ci-cd/ instead)

**Structure:** Mix of paired tools and standalone skills

---

### documentation/
**Scope:** General-purpose writing, technical communication, documentation practices

**Includes:**
- Markdown authoring (general markdown syntax)
- Acceptance criteria (user story requirements)
- Conventional commits (commit message standards)
- Plain English (technical writing for non-technical audiences)
- Journal entries (personal documentation)

**Excludes:**
- Agent-specific documentation (use agentic-harness/ instead)
- API documentation tools (may belong in development/)

**Why Not agents-md:** AGENTS.md is specifically for AI agent collaboration, not general technical documentation

**Structure:** Flat list of documentation skills

---

### package-mgmt/
**Scope:** Package management, version management, dependency management

**Includes:**
- Mise (cross-language version manager)
- Future: npm/yarn/pnpm, pip, cargo, gem, etc.

**Excludes:**
- Build tools (use development/ or repository-mgmt/ instead)
- Deployment tools (use ci-cd/ instead)

**Broad Scope:** Encompasses language-specific, cross-language, and Node ecosystem package management tools

**Structure:** Flat list of package management tools

---

### project-mgmt/
**Scope:** Planning, prioritization, task management, project organization

**Includes:**
- Moscow prioritization (requirement prioritization)
- Implementation plan splitter (breaking down work)
- Context file creator (planning artifacts)

**Excludes:**
- Development workflows (use development/ or testing/ instead)
- Repository management (use repository-mgmt/ instead)

**Structure:** Flat list of planning/organization skills

---

### specialized/
**Scope:** Domain-specific tools that don't fit other categories

**Includes:**
- Colyseus multiplayer (game server framework)
- GitHub Copilot models (AI model listings)
- GitLab API (platform-specific API)

**Use Sparingly:** Only when skill truly doesn't belong elsewhere

**Structure:** Flat list of specialized skills

---

## Classification Decision Tree

Use this flowchart to classify new skills:

1. **Is it about deploying/releasing code?** → ci-cd/
2. **Is it about provisioning infrastructure?** → infrastructure/
3. **Is it specific to repository/workspace management?** → repository-mgmt/
4. **Is it about agent frameworks or agent collaboration?** → agentic-harness/
5. **Is it about monitoring/logging production systems?** → observability/
6. **Is it about testing or debugging?** → testing/
7. **Is it about software engineering principles/patterns?** → software-engineering/
8. **Is it about general-purpose writing/documentation?** → documentation/
9. **Is it about package/version management?** → package-mgmt/
10. **Is it a general development tool?** → development/
11. **Is it about project planning/organization?** → project-mgmt/
12. **Doesn't fit anywhere else?** → specialized/ (use sparingly)

---

## Borderline Cases

### agents-md (AGENTS.md documentation)
**Placement:** agentic-harness/  
**Rationale:** AGENTS.md files are specifically for AI agent collaboration and orchestration  
**Alternative considered:** documentation/ (general documentation) - rejected because agent-specific, not general-purpose writing

### design-principles tile (solid-principles, clean-architecture, design-patterns, testable-design)
**Placement:** software-engineering/ (top-level domain)  
**Rationale:** Foundational engineering principles split into focused single-responsibility skills  
**Alternative considered:** Keep monolithic hub - rejected for violation of single-responsibility and progressive disclosure
**Migration note:** Replaced monolithic `software-design-principles` hub (254 lines, 44 refs) with 4 focused skills under unified `pantheon-ai/design-principles` tile

### mise-complete
**Placement:** package-mgmt/ (new top-level domain)  
**Rationale:** Cross-language version/package management tool  
**Alternative considered:** development/ (dev tool) - rejected because package management is a distinct domain with future growth potential

### extending-nx-plugins
**Placement:** repository-mgmt/nx/  
**Rationale:** Teaches extending Nx itself, which is specific to repository management  
**Alternative considered:** development/ (general tooling) - rejected because too Nx-specific

### cdk-nag
**Placement:** infrastructure/aws-cdk/  
**Rationale:** AWS CDK-specific validation tool, warrants CDK subdomain  
**Alternative considered:** infrastructure/cfn/ (CFN tools) - rejected because CDK is distinct from CloudFormation, even though it generates CFN

### cfn-behavior-validator, cfn-template-compare
**Placement:** infrastructure/cfn/  
**Rationale:** Grouped CloudFormation-specific tools under subdomain  
**Alternative considered:** infrastructure/ (flat) - rejected because grouping related CFN tools improves organization

### bash-script, makefile
**Placement:** development/scripting/  
**Rationale:** Shell scripting is a specialized development activity  
**Alternative considered:** top-level scripting/ domain - rejected because scripting is fundamentally a development tool, nesting under development/ keeps related tools together

### ui-debug-workflow
**Placement:** testing/  
**Rationale:** Testing methodology for UI changes  
**Alternative considered:** development/ (dev tool) - rejected because primarily about testing, not general development

### web-reference-sheet-generator, website-theme-porter
**Placement:** development/front-end/  
**Rationale:** Front-end web development tools for design tokens, theming, and CSS workflows; general development tools not specific to testing, CI/CD, or infrastructure  
**Alternative considered:** specialized/ - rejected because they serve a broad, well-defined front-end development use case, not a niche domain that doesn't fit anywhere else

---

## Adding New Skills

When adding a new skill:

1. **Read domain definitions** above to understand scope and boundaries
2. **Run through decision tree** to identify best-fit domain
3. **Check for existing related skills** in candidate domain for consistency
4. **Consider generator/validator pairing:**
   - If creating both, use nested structure: `domain/tool/{generator,validator}/`
   - If standalone, place directly in domain or subdomain: `domain/skill-name/`
5. **Consider subdomain grouping:**
   - If 3+ related skills exist, consider creating subdomain
   - Example: infrastructure/cfn/ groups CloudFormation tools
6. **Document borderline decisions** in this file for future reference
7. **Update this guide** if skill doesn't fit existing domains

---

## Creating New Domains

Before creating a new domain:

1. **Verify at least 3-5 skills** would belong in the new domain
2. **Ensure it's not a subset** of existing domains
3. **Define clear scope** that doesn't overlap with existing domains
4. **Consider future growth:** Will this domain attract more skills?
5. **Update this guide** with domain definition and decision tree
6. **Update AGENTS.md** with new domain information
7. **Get team consensus** before restructuring

**Recent Examples:**
- `software-engineering/` created for design principles (foundational, cross-cutting)
- `agentic-harness/` created for agent frameworks (distinct category, future growth)
- `package-mgmt/` created for version managers (broad scope, future growth)

---

## Subdomain Strategy

**When to create a subdomain:**
- 3+ related skills under a common tool/platform (e.g., nx/, cfn/, aws-cdk/)
- Clear separation from other skills in the domain
- Future growth expected in that subdomain

**Current subdomains:**
- `infrastructure/aws-cdk/` - AWS CDK ecosystem (allows cdk-patterns, cdk-constructs)
- `infrastructure/cfn/` - CloudFormation tools (grouped related functionality)
- `repository-mgmt/nx/` - Nx ecosystem (allows turborepo, lerna, rush)
- `development/scripting/` - Shell scripting tools (bash, makefile)

**Future subdomain candidates:**
- `ci-cd/github/` - If we add github-release, github-checks, etc.
- `development/nodejs/` - If we add multiple Node.js-specific tools
- `agentic-harness/cursor/` - If we add multiple Cursor-specific skills

---

## Generator/Validator Pairing

**When to nest generator/validator:**
- Both skills exist for the same tool
- They share common concepts and workflows
- Users typically need both for complete workflow

**Structure:**