docs: optimize CosId skills

Author: Ahoo-Wang

skills/cosid-manual-integration/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: cosid-manual-integration
-description: Guide for manually integrating CosId into Java/Kotlin projects without Spring Boot auto-configuration. Use this skill when the user wants to configure CosId programmatically, set up custom ID generators, integrate CosId in non-Spring environments, asks about CosId core API usage (SnowflakeId, SegmentId, CosIdGenerator), needs to configure machine ID allocation manually, or mentions "manual integration", "programmatic configuration", "without Spring Boot", "non-Spring environment", or "library integration".
+description: Manually integrate CosId into Java or Kotlin applications without Spring Boot auto-configuration. Use when the user needs programmatic setup for SnowflakeId, SegmentId, SegmentChainId, CosIdGenerator, machine ID distribution, custom IdConverter wiring, non-Spring environments, library/framework integration, or production-safe generator lifecycle management.
 ---
 
 # CosId Manual Integration Skill
 
-## Instructions
+Use this skill when CosId must be configured with code instead of `cosid-spring-boot-starter`.
 
-### When to Use
+## Workflow
 
-- User wants to integrate CosId without Spring Boot
-- User needs custom programmatic configuration of ID generators
-- User is building a library or framework that needs ID generation
-- User asks about CosId core API usage (SnowflakeId, SegmentId, CosIdGenerator)
-- User needs to configure machine ID allocation manually
+1. Identify the generator strategy. Use `$cosid-strategy-guide` first if the user has not chosen one.
+2. Identify the coordination mechanism: manual machine ID, StatefulSet ordinal, Redis, JDBC, MongoDB, ZooKeeper, or proxy.
+3. Show the minimal constructor/wiring path for the chosen generator.
+4. Include lifecycle handling for distributors, guard/heartbeat, prefetch workers, and state storage when relevant.
+5. Add a small verification example: uniqueness, monotonicity, parser behavior, or restart behavior.
 
-### Core Architecture
+## Core APIs
 
 CosId provides three main ID generation strategies:
 
@@ -33,22 +33,24 @@ CosId provides three main ID generation strategies:
    - Requires `MachineIdDistributor` for machine ID allocation (same as SnowflakeId)
    - Supports much larger instance counts than SnowflakeId (not constrained by 63-bit long format)
 
-### Machine ID Allocation
+## Machine ID Allocation
 
 For SnowflakeId, each instance needs a unique machineId. Options:
 
 - **Manual**: Set machineId directly (0-1023 for default 10-bit)
-- **Redis**: `RedisMachineIdDistributor` - uses Redis for coordination
+- **Redis**: `SpringRedisMachineIdDistributor` - uses Redis for coordination
 - **JDBC**: `JdbcMachineIdDistributor` - uses database table
 - **ZooKeeper**: `ZookeeperMachineIdDistributor` - uses ZK nodes
 - **MongoDB**: `MongoMachineIdDistributor` - uses MongoDB collection
 - **StatefulSet**: Kubernetes StatefulSet ordinal as machineId
 
-### Manual Configuration Pattern
+Always define the namespace and instance identity deliberately. For production, prefer a distributor that can guard ownership and reclaim expired machine IDs.
+
+## SnowflakeId Configuration Pattern
 
 ```java
-// 1. Create machine ID distributor
-MachineIdDistributor distributor = new RedisMachineIdDistributor(redisTemplate);
+// 1. Create a backend-specific MachineIdDistributor
+MachineIdDistributor distributor = createMachineIdDistributor();
 
 // 2. Allocate machine ID
 int machineId = distributor.distribute("my-namespace", instanceId, Duration.ofSeconds(10));
@@ -63,7 +65,34 @@ SnowflakeId safeId = new ClockSyncSnowflakeId(snowflakeId);
 long id = safeId.generate();
 ```
 
-### Key Configuration Parameters
+If the user has fixed deployment slots, use `ManualMachineIdDistributor` or directly provide the machine ID, but warn that duplicate machine IDs can create duplicate IDs.
+
+## Segment Configuration Pattern
+
+Use `SegmentId` or `SegmentChainId` when monotonic IDs and batch allocation are more important than time-encoded IDs.
+
+```java
+IdSegmentDistributor distributor = createIdSegmentDistributor("order_id", 100);
+SegmentChainId idGenerator = new SegmentChainId(distributor);
+
+long id = idGenerator.generate();
+String text = idGenerator.generateAsString();
+```
+
+For `SegmentChainId`, ensure the prefetch worker lifecycle is owned by the application and is closed during shutdown if the concrete setup exposes close/shutdown behavior.
+
+## CosIdGenerator Pattern
+
+Use `CosIdGenerator` when callers need compact string IDs rather than `long` IDs.
+
+```java
+CosIdGenerator generator = new Radix62CosIdGenerator(machineId);
+String id = generator.generateAsString();
+```
+
+Wrap with the clock-sync variant when system clock drift is a production concern.
+
+## Key Parameters
 
 | Parameter | Default | Description |
 |-----------|---------|-------------|
@@ -73,22 +102,32 @@ long id = safeId.generate();
 | sequenceBit | 12 (ms) / 22 (s) | IDs per time unit per machine |
 | clockSync | true | Enable clock backwards synchronization |
 
-### Common Pitfalls
+## Common Pitfalls
 
 - **Clock backwards**: Always use `ClockSyncSnowflakeId` wrapper in production
 - **Machine ID overflow**: With 10 bits, max 1024 instances per namespace
 - **Sequence exhaustion**: High throughput may need `SecondSnowflakeId` (4M/s/machine) over millisecond variant (4K/s/machine)
 - **JavaScript safety**: Use `SafeJavaScriptSnowflakeId` if IDs go to frontend
+- **Lifecycle leaks**: Close distributor clients and background workers when the application shuts down
+- **State loss**: Persist machine state when restart stability matters
 
-### Testing Configuration
+## Testing Configuration
 
 For tests, use `ManualMachineIdDistributor` with fixed machine IDs:
 
 ```java
 MachineIdDistributor distributor = new ManualMachineIdDistributor(1);
 ```
 
-## References
+Add tests for the property that matters in the user's case:
+
+- Uniqueness across concurrent generation
+- Local monotonicity for SegmentId/SegmentChainId
+- Time parser correctness for SnowflakeId
+- JavaScript-safe range or string conversion
+- Machine ID conflict behavior when manual IDs are used
+
+## Source Pointers
 
 - Source: `cosid-core/src/main/java/me/ahoo/cosid/`
 - Examples: `examples/` directory

skills/cosid-manual-integration/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "CosId Manual Integration"
+  short_description: "Integrate CosId without Spring Boot"
+  default_prompt: "Use $cosid-manual-integration to wire CosId programmatically without Spring Boot."

skills/cosid-sharding/SKILL.md

@@ -1,11 +1,19 @@
 ---
 name: cosid-sharding
-description: Guide for using CosId sharding algorithms for database sharding with ShardingSphere. Use this skill whenever the user mentions database sharding, table sharding, ShardingSphere, interval sharding, modulo sharding, date-based sharding, range sharding, or needs to distribute data across multiple database tables or nodes. Also use when the user asks about ModCycle, IntervalTimeline, CachedSharding, PreciseSharding, RangeSharding, or SnowflakeLocalDateTimeConvertor.
+description: Design and configure CosId sharding algorithms for database sharding and ShardingSphere. Use when the user mentions table or database sharding, ShardingSphere COSID_MOD or COSID_INTERVAL rules, modulo sharding, date/time interval sharding, range routing, SnowflakeId timestamp extraction, ModCycle, IntervalTimeline, CachedSharding, PreciseSharding, RangeSharding, or SnowflakeLocalDateTimeConvertor.
 ---
 
 # CosId Sharding Algorithms
 
-CosId provides sharding algorithms designed for database sharding, compatible with Apache ShardingSphere. All algorithms implement both precise sharding (single key lookup) and range sharding (key range lookup).
+Use this skill to choose, configure, and validate CosId sharding behavior.
+
+## Workflow
+
+1. Identify the sharding key type: numeric ID, SnowflakeId, `LocalDateTime`, or an existing timestamp column.
+2. Choose the algorithm: `ModCycle` for uniform numeric distribution, `IntervalTimeline` for time ranges, or `CachedSharding` to cache repeated range routing.
+3. Confirm both precise and range queries. ShardingSphere routes `=`, `IN`, and range predicates differently.
+4. Define effective nodes and bounds explicitly. For interval sharding, include lower/upper datetime bounds and suffix format.
+5. Provide a minimal Java or ShardingSphere YAML example and a routing test.
 
 ## Sharding Algorithm Types
 
@@ -34,6 +42,8 @@ Implementations:
 
 Distributes numeric IDs across nodes using `value % divisor`. Best for uniform distribution when using SnowflakeId or SegmentId.
 
+Use `ModCycle` when the sharding key is already numeric and the desired distribution is even across a fixed number of tables or databases.
+
 ### Usage
 
 ```java
@@ -75,6 +85,8 @@ rules:
 
 Distributes data across time-based intervals. Each interval maps to a specific node named with a formatted date suffix.
 
+Use `IntervalTimeline` when table names encode time periods such as day, month, or hour. It is also appropriate when a SnowflakeId can be converted back into event time.
+
 ### Usage
 
 ```java
@@ -213,12 +225,30 @@ Range queries are often repeated (e.g., querying "last 7 days" across many reque
 | High QPS range queries | CachedSharding + any | Cache avoids recomputation |
 | Auto-increment / SegmentId as key | ModCycle | Even distribution of monotonic IDs |
 
+## Validation Checklist
+
+Use a small routing matrix before finalizing a rule:
+
+- One exact key routes to exactly one expected node.
+- An `IN` query routes to the union of expected nodes.
+- A range query covers all boundary nodes and no unrelated nodes when possible.
+- Values outside an `IntervalTimeline` effective range fail intentionally.
+- Snowflake timestamp extraction uses the same epoch and timestamp bits as the generator.
+- The ShardingSphere `actualDataNodes` expression matches every possible CosId effective node.
+
 ## Key Design Principles
 
 1. **Precise + Range**: Every algorithm supports both single-value and range sharding. ShardingSphere uses precise for `=` and `IN`, and range for `BETWEEN`, `>`, `<`.
-
 2. **Effective nodes**: `getEffectiveNodes()` returns all possible target nodes. This is used by ShardingSphere for routing optimization.
-
 3. **Thread safety**: All sharding implementations are thread-safe (`@ThreadSafe`).
+4. **Interval bounds**: `IntervalTimeline` requires an explicit effective time range. Values outside this range throw `IllegalArgumentException`.
+5. **Generator alignment**: When the sharding key is a CosId-generated ID, keep the generator epoch, timestamp unit, and converter settings aligned with the sharding rule.
+
+## Response Template
+
+When answering a sharding request, include:
 
-4. **Interval bounds**: IntervalTimeline requires an explicit effective time range. Values outside this range throw `IllegalArgumentException`.
+1. The selected algorithm and why it fits the sharding key.
+2. The expected table/database naming pattern.
+3. A concise Java or ShardingSphere YAML example.
+4. A routing test matrix for exact, `IN`, and range queries.

skills/cosid-sharding/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "CosId Sharding"
+  short_description: "Design CosId ShardingSphere rules"
+  default_prompt: "Use $cosid-sharding to design CosId sharding rules for my database tables."

skills/cosid-spring-boot/SKILL.md

@@ -1,12 +1,21 @@
 ---
 name: cosid-spring-boot
-description: Guide for integrating CosId distributed ID generator with Spring Boot. Use this skill whenever the user mentions CosId, distributed ID generation, SnowflakeId, SegmentId, SegmentChainId, CosIdGenerator, machine ID allocation, or needs help configuring ID generation in a Spring Boot application. Also use when the user asks about ID conversion (Radix62, Radix36, SnowflakeFriendly), sharding with CosId, or configuring machine ID distributors (Redis, JDBC, MongoDB, ZooKeeper) for Spring Boot. Triggers on cosid YAML configuration, application.yml ID setup, or any CosId Spring Boot starter questions.
+description: Configure CosId in Spring Boot applications with cosid-spring-boot-starter. Use when the user works with application.yml, Gradle or Maven dependencies, starter feature variants, Redis/JDBC/MongoDB/ZooKeeper/proxy distributors, SnowflakeId, SegmentId, SegmentChainId, CosIdGenerator, @CosId, IdGeneratorProvider, ID converters, machine guarder settings, clock-backwards synchronization, or Actuator endpoints in a Spring Boot service.
 ---
 
 # CosId Spring Boot Integration
 
 CosId is a universal, flexible, high-performance distributed ID generator for Java 17+. The Spring Boot starter (`cosid-spring-boot-starter`) provides auto-configuration for all ID generation strategies.
 
+## Workflow
+
+1. Confirm the user's Spring Boot and CosId major versions. CosId 2.x targets Spring Boot 3.x and Java 17; CosId 3.x targets Spring Boot 4.x and Java 17.
+2. Choose the ID strategy. Use `$cosid-strategy-guide` first when the user has not chosen between SnowflakeId, SegmentId, SegmentChainId, and CosIdGenerator.
+3. Select the distributor and starter capability needed by the deployment: Redis, JDBC, MongoDB, ZooKeeper, proxy, manual, or StatefulSet.
+4. Provide the smallest working YAML for the selected strategy and backend.
+5. Show how the application consumes the generator: shared bean, named provider, or `@CosId`.
+6. Add validation guidance for uniqueness, ordering, machine ID ownership, segment allocation, and Actuator visibility.
+
 ## Dependency Setup
 
 Add the BOM and starter to your `build.gradle`:
@@ -16,7 +25,7 @@ dependencies {
     implementation platform("me.ahoo.cosid:cosid-bom:${cosidVersion}")
     implementation "me.ahoo.cosid:cosid-spring-boot-starter"
     
-    // Add exactly ONE distributor backend based on your infrastructure:
+    // Add the distributor backend needed by your infrastructure:
     implementation "me.ahoo.cosid:cosid-spring-boot-starter:springRedisSupport"  // Redis
     // implementation "me.ahoo.cosid:cosid-spring-boot-starter:jdbcSupport"     // JDBC/MySQL
     // implementation "me.ahoo.cosid:cosid-spring-boot-starter:mongoSupport"    // MongoDB
@@ -68,8 +77,9 @@ There are 4 ID generation strategies in CosId. The right choice depends on your
 
 - **Need maximum performance and have Redis/JDBC available?** → SegmentChainId (default segment mode)
 - **Need time-sortable IDs across machines?** → SnowflakeId
-- **Simple standalone app?** → CosIdGenerator (no external dependencies)
+- **Need compact string IDs or a large machine-ID design space?** → CosIdGenerator
 - **Database-friendly monotonic IDs?** → SegmentId or SegmentChainId
+- **Need only strategy selection?** → Use `$cosid-strategy-guide` before writing YAML
 
 ## Configuration Templates
 
@@ -459,3 +469,23 @@ management:
 ```
 
 The `cosid` endpoint shows all registered ID generators and their stats.
+
+## Validation Checklist
+
+- Run a focused Spring Boot test that loads the application context with the chosen backend capability.
+- Generate IDs concurrently and assert uniqueness.
+- For SnowflakeId, verify machine ID allocation and clock-backwards settings.
+- For SegmentId/SegmentChainId, verify the segment distributor initializes the `cosid` table or backend state.
+- For converters, assert the expected prefix, padding, radix, and string length.
+- For shared beans, assert `IdGenerator` or `StringIdGenerator` resolves to the intended provider.
+- For production services, expose and inspect the CosId Actuator endpoint when actuator support is enabled.
+
+## Response Template
+
+When answering a Spring Boot integration request, include:
+
+1. Dependency coordinates and the required backend capability.
+2. Minimal `application.yml` for the selected generator.
+3. Code snippet for injection or `@CosId`.
+4. Operational notes for machine ID, clock, state storage, and monitoring.
+5. A small test or verification command the user can run.

skills/cosid-spring-boot/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "CosId Spring Boot"
+  short_description: "Configure CosId Spring Boot starter"
+  default_prompt: "Use $cosid-spring-boot to configure CosId in my Spring Boot application."