Extract reusable AI skills from Shelve best practices

[HugoRCD]

Context

Shelve has accumulated a clean, well-structured codebase with strong conventions and patterns that go beyond this project. These best practices should be extractable as reusable AI skills (SKILL.md / AGENTS.md files) that can be applied to any project I work on.

The goal is to codify the implicit knowledge embedded in this repo into portable, actionable skill files.

To extract

1. Turborepo Monorepo Patterns

• Task dependency graph and caching strategy (turbo.json)
• Filtered commands for focused development (--filter=@scope/pkg)
• Output caching patterns (.vercel/output/**, .output/**, .nuxt/**, dist/**)
• Environment variable tracking in build tasks
• Standardized script conventions across packages (dev, build, lint, typecheck)

2. pnpm Workspace Conventions

• Workspace structure (apps/* vs packages/*)
• Package naming with scoped prefixes (@shelve/*)
• Cross-package references and path aliases
• Built dependency handling
• Lockfile and version pinning strategies

3. Progressive Documentation Architecture

• Minimal root entry point (AGENTS.md) with progressive disclosure
• Detailed docs in docs/agents/ subdirectory
• Actionable, specific instructions only (no fluff)
• Reference links centralization (docs-links.md)
• Self-updating documentation workflow (ai-workflow.md)

4. NuxtHub Integration Best Practices

• Database schema organization (server/db/schema/)
• Drizzle ORM migration workflow (nuxt db generate → nuxt db migrate)
• KV usage patterns (@nuxthub/kv over legacy hub:kv)
• OpenAPI configuration via Nitro experimental flags
• Server route conventions

5. Monorepo TypeScript Configuration

• Config inheritance and path alias patterns
• Cross-package type references
• Nuxt-specific tsconfig extensions (.nuxt/tsconfig.json)
• Strict mode and bundler module resolution
• Shared types package pattern (@shelve/types)

6. Conventional Commits & Versioning

• Changesets integration for monorepo versioning
• Commit type conventions (breaking, feat, fix, build, ci, etc.)
• Scope patterns aligned with workspace packages (app, cli, types, etc.)
• PR template and release workflow

7. Shared Code Quality Configuration

• Monorepo-wide ESLint with shared config (@hrcd/eslint-config)
• EditorConfig for consistent formatting (2-space indent, LF, UTF-8)
• Consistent linting rules across all packages
• Base layer pattern for shared app configuration (@shelve/base)

Expected output

Each skill should be a standalone SKILL.md file that:

• Can be dropped into any compatible project
• Contains actionable patterns, not just theory
• Includes code examples extracted from the actual codebase
• Follows the progressive disclosure pattern (summary → details)
• Is usable by AI agents (Cursor, Codex, etc.) as context

Why this matters

These patterns took time to develop and refine. Extracting them means:

• Consistent quality across all projects
• Faster onboarding for AI agents on new repos
• A living library of battle-tested conventions
• Less time re-explaining the same patterns

References:

• How to make goods skills: https://skills.sh/anthropics/skills/skill-creator