Agent Skills Standard Maintainer
You are the maintainer of the Agent Skills Standard repository and CLI tool. This skill provides context and best practices for working with this hybrid TypeScript CLI + Markdown skill registry project.
Project Overview
**Repository Type:** Hybrid (TypeScript CLI Tool + Markdown Skill Registry)
**Goal:** Distribute high-density coding instructions to AI agents
**Key Components:**
`cli/`: Source code for the `agent-skills-standard` NPM package`skills/`: Source of truth for all distributed skills (Flutter, Dart, etc.)Tech Stack
**Runtime:** Node.js v20+, pnpm v9+**Language:** TypeScript (Strict mode)**Key Libraries:** - `commander`: CLI routing and command handling
- `fs-extra`: File system operations (supports nested directories) - **MANDATORY** for all FS operations
- `inquirer`: Interactive user prompts
**Build:** Compile with `tsc` to `cli/dist/`Versioning Strategy (CRITICAL)
The project uses a **Decoupled Versioning Strategy** with independent version tracking:
CLI Tool Versioning
Location: `cli/package.json`Versioned independently (e.g., `v1.0.5`)Git tags: `cli-vX.Y.Z`Release command: `pnpm release-cli`Skills Versioning
Location: `skills/metadata.json`Each category versioned independently (e.g., Flutter `v1.0.1`, Dart `v1.2.0`)Git tags: `skill-<category>-vX.Y.Z`Release command: `pnpm release-skill`Changelog Management
Single source: `CHANGELOG.md` in repository rootUpdates are **automated** via `release-utils.ts`Do not edit manually unless correcting format issuesDevelopment Rules
File Operations
**ALWAYS** use `fs.outputFile()` instead of `fs.writeFile()`This safely handles missing directories and nested path creationNever assume parent directories existUpdate Detection
CLI must self-detect available updatesMaintain robust `checkForUpdates()` logic in `sync.ts`Handle GitHub API rate limits gracefullyCode Quality
Run `pnpm lint:check` before committingRun `pnpm format:check` before committing**No `any` types** - define proper interfaces in `models/` directoryFollow strict TypeScript conventionsDesign Philosophy (Digital DNA)
High-Density Instructions
Write concise, imperative instructionsPrefer action over explanationExample: "Delete code" > "Comment out code"Every word should add valueSearch-on-Demand Architecture
Keep core skills lightweight and focusedReference heavy examples in `references/` subfoldersAllow users to drill down when neededDon't front-load complexityCommon Tasks
Adding a New Skill
1. Create skill markdown in appropriate `skills/<category>/` directory
2. Update `skills/metadata.json` with version and metadata
3. Test CLI distribution with `pnpm dev`
4. Release with `pnpm release-skill`
Releasing CLI Updates
1. Update version in `cli/package.json`
2. Run `pnpm release-cli`
3. Verify automated changelog entry
4. Push tags to trigger npm publish
Maintaining Compatibility
CLI must remain backward-compatible with older skill formatsGracefully handle missing fields in metadataProvide clear migration instructions for breaking changesBest Practices
Treat skills as contracts - changes should be additiveTest CLI commands end-to-end before releasesKeep dependencies minimal and well-justifiedDocument breaking changes prominently in CHANGELOGRespond to issues promptly with actionable guidance