mirror of
https://github.com/alirezarezvani/claude-skills.git
synced 2026-10-10 03:27:56 +00:00
1851c8fb09
Same root cause as #587/#591 — Claude Code's runtime loader rejects array-form skills paths like ["./content-production", "./ai-seo", ...] even when each entry is a valid subdirectory containing SKILL.md. `claude plugin validate` accepts them but the loader does not. The proven canonical layout (used by self-improving-agent in #536): <plugin>/ ├── .claude-plugin/plugin.json skills: "./skills" └── skills/ ├── <skill-1>/SKILL.md ├── <skill-2>/SKILL.md └── ... Restructured 9 multi-skill domain plugins: - business-growth (4 skills moved) - c-level-advisor (28) - engineering (36) - engineering-team (32) - finance (2) - marketing-skill (43) - product-team (12) - project-management (8) - ra-qm-team (13) Also fixed standalone plugins that had root SKILL.md + ./skills/ subdir (agenthub, autoresearch-agent, executive-mentor, playwright-pro). The loader rejected them despite skills="./skills" because of the conflicting root SKILL.md (compare self-improving-agent which works because PR #536 moved its root SKILL.md). Moved each root SKILL.md into ./skills/<name>/. Restored standalone plugin folders to their original paths after the multi-skill restructure swept them into parent skills/ directories (marketplace.json source paths require original locations). Removed 7 orphaned marketplace entries that pointed to skill folders without their own plugin.json (content-creator, demand-gen, fullstack-engineer, aws-architect, product-manager, scrum-master, skill-security-auditor) — these were already non-functional. Bumped patch versions on every changed plugin and synced marketplace.json. Marketplace now lists 29 working plugins (down from 36). After merge: users run `/plugin marketplace update claude-code-skills` followed by `/plugin update --all` to pick up the working layout.
186 lines
3.3 KiB
Markdown
186 lines
3.3 KiB
Markdown
# Onboarding Document Template
|
|
|
|
## README.md - Full Template
|
|
|
|
```markdown
|
|
# [Project Name]
|
|
|
|
> One-sentence description of what this does and who uses it.
|
|
|
|
[](https://github.com/org/repo/actions/workflows/ci.yml)
|
|
[](https://codecov.io/gh/org/repo)
|
|
|
|
## What is this?
|
|
|
|
[2-3 sentences: problem it solves, who uses it, current state]
|
|
|
|
**Live:** https://myapp.com
|
|
**Staging:** https://staging.myapp.com
|
|
**Docs:** https://docs.myapp.com
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
| Tool | Version | Install |
|
|
|------|---------|---------|
|
|
| Node.js | 20+ | `nvm install 20` |
|
|
| pnpm | 8+ | `npm i -g pnpm` |
|
|
| Docker | 24+ | [docker.com](https://docker.com) |
|
|
| PostgreSQL | 16+ | via Docker (see below) |
|
|
|
|
### Setup (5 minutes)
|
|
|
|
```bash
|
|
git clone https://github.com/org/repo
|
|
cd repo
|
|
pnpm install
|
|
docker compose up -d
|
|
cp .env.example .env
|
|
pnpm db:migrate
|
|
pnpm db:seed
|
|
pnpm dev
|
|
pnpm test
|
|
```
|
|
|
|
### Verify it works
|
|
|
|
- [ ] App loads on localhost
|
|
- [ ] Health endpoint returns ok
|
|
- [ ] Tests pass
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
### System Overview
|
|
|
|
```
|
|
Browser / Mobile
|
|
|
|
|
v
|
|
[Next.js App] <- [Auth]
|
|
|
|
|
+-> [PostgreSQL]
|
|
+-> [Redis]
|
|
+-> [S3]
|
|
```
|
|
|
|
### Tech Stack
|
|
|
|
| Layer | Technology | Why |
|
|
|-------|-----------|-----|
|
|
| Frontend | Next.js | SSR + routing |
|
|
| Styling | Tailwind + shadcn/ui | Rapid UI |
|
|
| API | Route handlers | Co-location |
|
|
| Database | PostgreSQL | Relational |
|
|
| Queue | BullMQ + Redis | Background jobs |
|
|
|
|
---
|
|
|
|
## Key Files
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `app/` | Pages and route handlers |
|
|
| `src/db/` | Schema and migrations |
|
|
| `src/lib/` | Shared utilities |
|
|
| `tests/` | Test suites and helpers |
|
|
| `.env.example` | Required variables |
|
|
|
|
---
|
|
|
|
## Common Developer Tasks
|
|
|
|
### Add a new API endpoint
|
|
|
|
```bash
|
|
touch app/api/my-resource/route.ts
|
|
touch tests/api/my-resource.test.ts
|
|
```
|
|
|
|
### Run a database migration
|
|
|
|
```bash
|
|
pnpm db:generate
|
|
pnpm db:migrate
|
|
```
|
|
|
|
### Add a background job
|
|
|
|
```bash
|
|
# Create worker module and enqueue path
|
|
```
|
|
|
|
---
|
|
|
|
## Debugging Guide
|
|
|
|
### Common Errors
|
|
|
|
- Missing environment variable
|
|
- Database connectivity failure
|
|
- Expired auth token
|
|
- Generic 500 in local dev
|
|
|
|
### Useful SQL Queries
|
|
|
|
- Slow query checks
|
|
- Connection status
|
|
- Table bloat checks
|
|
|
|
### Log Locations
|
|
|
|
| Environment | Logs |
|
|
|-------------|------|
|
|
| Local dev | local terminal |
|
|
| Production | platform logs |
|
|
| Worker | worker process logs |
|
|
|
|
---
|
|
|
|
## Contribution Guidelines
|
|
|
|
### Branch Strategy
|
|
|
|
- `main` protected
|
|
- feature/fix branches with ticket IDs
|
|
|
|
### PR Requirements
|
|
|
|
- CI green
|
|
- Tests updated
|
|
- Why documented
|
|
- Self-review completed
|
|
|
|
### Commit Convention
|
|
|
|
- `feat(scope): ...`
|
|
- `fix(scope): ...`
|
|
- `docs: ...`
|
|
|
|
---
|
|
|
|
## Audience-Specific Notes
|
|
|
|
### Junior Developers
|
|
- Start with core auth/data modules
|
|
- Follow tests as executable examples
|
|
|
|
### Senior Engineers
|
|
- Read ADRs and scaling notes first
|
|
- Validate performance/security assumptions early
|
|
|
|
### Contractors
|
|
- Stay within scoped feature boundaries
|
|
- Use wrappers for external integrations
|
|
```
|
|
|
|
## Usage Notes
|
|
|
|
- Keep onboarding setup under 10 minutes where possible.
|
|
- Include executable verification checks after each setup phase.
|
|
- Prefer links to canonical docs instead of duplicating long content.
|
|
- Update this template when stack conventions or tooling change.
|