Skip to content

Commit 444bb99

Browse files
Copilotxiaoland
Copilot
and
xiaoland
authored
Add Agent Skills generation for web-design package (#29)
* Initial plan * Add Claude Skill generation script for web-design package - Create build-claude-skill.ts to generate comprehensive documentation - Include component interfaces, props, and usage examples - Document router, i18n, and styling systems - Add script to build process and package files - Generate CLAUDE_SKILL.md with complete package documentation Co-authored-by: xiaoland <37663413+xiaoland@users.noreply.github.com> * Document Claude Skill generation in README - Add documentation section about Claude AI Skill - Explain what's included in the skill documentation - Note that it's auto-generated during build Co-authored-by: xiaoland <37663413+xiaoland@users.noreply.github.com> * Improve build-claude-skill.ts based on code review - Fix regex patterns to handle nested objects in props/emits - Extract cleanDocumentation() as dedicated function - Improve error handling for missing router.ts and i18n.ts files - Add fallback interface definitions when source files unavailable - Support multiline types and interface definitions Co-authored-by: xiaoland <37663413+xiaoland@users.noreply.github.com> * Add documentation about regex limitations - Document known limitations of regex-based extraction - Note that a TypeScript parser would be more robust - Clarify that patterns work for current codebase structure Co-authored-by: xiaoland <37663413+xiaoland@users.noreply.github.com> * Re-implement using proper Agent Skills format - Remove monolithic CLAUDE_SKILL.md approach - Create proper Agent Skills following agentskills.io specification - Generate 5 skills in .github/skills/ directory: - web-design-components: Component library with all 19 components - web-design-router: Router integration patterns - web-design-i18n: Internationalization setup - web-design-styling: Design tokens and SCSS utilities - web-design-best-practices: Development guidelines - Each skill has YAML frontmatter with name and description - Skills are modular and loaded on-demand by AI agents - Integrated into build process via build:skills script - Shipped with package in .github/skills/ directory Co-authored-by: xiaoland <37663413+xiaoland@users.noreply.github.com> * Restructure agent skills per feedback - Move skills from .github/skills/ to agent-skills/ - Remove web-design- prefix from skill names - Break down components into individual reference files - Only auto-generate components skill, others manual - Update README to reference skill files instead of inline docs - Components skill uses progressive disclosure with references/ Co-authored-by: xiaoland <37663413+xiaoland@users.noreply.github.com>
1 parent ebd2b76 commit 444bb99

29 files changed

+3154
-95
lines changed

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
},
1111
"scripts": {
1212
"build-tokens": "tsx scripts/build-tokens.ts",
13+
"build-skills": "tsx scripts/build-agent-skills.ts",
1314
"changeset": "changeset",
1415
"changeset:add": "changeset add",
1516
"changeset:version": "changeset version",

‎packages/web-design/README.md‎

Lines changed: 9 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -59,102 +59,11 @@ export default defineConfig({
5959

6060
### Use routing
6161

62-
InkHeader and some other components relies on your router abilities.
63-
64-
```ts
65-
// your-router.ts
66-
import { computed } from "vue";
67-
import type { Router, RouteLocationNormalizedLoaded } from "vue-router";
68-
import type { InkRouter } from "@inkcre/web-design";
69-
70-
export function createInkRouterAdapter(
71-
router: Router,
72-
route: RouteLocationNormalizedLoaded
73-
): InkRouter {
74-
return {
75-
currentPath: computed(() => route.path),
76-
currentName: computed(() => route.name),
77-
};
78-
}
79-
```
80-
81-
```ts
82-
// App.vue
83-
<script lang="ts" setup>
84-
import { INK_ROUTER_KEY } from "@inkcre/web-design";
85-
import { createInkRouterAdapter } from "./your-router.ts";
86-
import { useRoute } from "vue-router";
87-
88-
provide(
89-
INK_ROUTER_KEY,
90-
createInkRouterAdapter(router, useRoute())
91-
);
92-
</script>
93-
```
62+
InkHeader and some other components can integrate with your router. See `agent-skills/router/SKILL.md` for setup instructions.
9463

9564
### Use internationalization (i18n)
9665

97-
The design system supports internationalization. You can provide your own i18n implementation via the `INK_I18N_KEY` injection key.
98-
99-
Your i18n provider must implement the following interface:
100-
101-
```ts
102-
interface InkI18n {
103-
t: (key: string) => string; // Translation function
104-
locale: Ref<string>; // Current locale as a reactive ref
105-
}
106-
```
107-
108-
Components will fall back to English strings if no i18n provider is configured.
109-
110-
#### Example with vue-i18n
111-
112-
1. `pnpm add vue-i18n`
113-
114-
2. Add your messages. You can extend our exported locales (`en`, `zhCN`) from `@inkcre/web-design/locales`.
115-
116-
```ts
117-
// your/locales/messages/en.ts
118-
import { en } from "@inkcre/web-design/locales";
119-
120-
export default {
121-
...en,
122-
// your translations here
123-
}
124-
```
125-
126-
3. Config your vue-i18n
127-
128-
```ts
129-
// your/locales/index.ts
130-
import { createI18n } from "vue-i18n";
131-
import messages from "your/locales/messages";
132-
133-
const i18n = createI18n({
134-
legacy: false,
135-
locale: "en",
136-
fallbackLocale: "en",
137-
messages,
138-
});
139-
140-
export default i18n;
141-
```
142-
143-
4. Provide it to us
144-
145-
```ts
146-
// App.vue
147-
<script lang="ts" setup>
148-
import { INK_I18N_KEY } from "@inkcre/web-design";
149-
import i18n from "./locales";
150-
151-
// Provide i18n to the design system
152-
provide(INK_I18N_KEY, {
153-
t: i18n.global.t,
154-
locale: i18n.global.locale,
155-
});
156-
</script>
157-
```
66+
The design system supports internationalization. See `agent-skills/i18n/SKILL.md` for setup instructions with vue-i18n.
15867

15968
## Features
16069

@@ -164,3 +73,10 @@ Components will fall back to English strings if no i18n provider is configured.
16473
- Modular SCSS architecture
16574
- Provider-agnostic router support
16675
- Provider-agnostic internationalization support
76+
- Agent Skills for AI-assisted development
77+
78+
## Agent Skills
79+
80+
The package includes [Agent Skills](https://agentskills.io) - standardized packages of domain expertise that AI agents can discover and load dynamically. Located in `agent-skills/`, component skills are automatically generated from source code during the build process.
81+
82+
Skills work with Claude Code, GitHub Copilot, and other AI agents supporting the agentskills.io standard.

‎packages/web-design/agent-skills/best-practices/SKILL.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
name: best-practices
3+
description: Best practices for developing with @inkcre/web-design including coding guidelines and accessibility.
4+
---
5+
6+
# Best Practices
7+
8+
Use this skill for guidance on developing with @inkcre/web-design.
9+
10+
## Component Development
11+
12+
1. **Single Responsibility**: Each component does one thing well
13+
2. **High Cohesion, Low Coupling**: Keep related code together, minimize dependencies
14+
3. **Clear API**: Props and events should be intuitive
15+
4. **Avoid Prop Drilling**: Use provide/inject for deeply nested data
16+
5. **Testable**: Write components that are easy to test
17+
18+
## Naming Conventions
19+
20+
- **Components**: `camelCase` (e.g., `inkButton`)
21+
- **CSS Classes**: `kebab-case` (e.g., `ink-button`)
22+
- **Props/Variables**: `camelCase` (e.g., `isLoading`)
23+
- **Events**: `kebab-case` (e.g., `update:modelValue`)
24+
25+
## Error Handling
26+
27+
- Use graceful degradation
28+
- Provide user-friendly error messages
29+
- Log errors appropriately
30+
- Validate inputs and provide defaults
31+
32+
## Accessibility
33+
34+
- Use semantic HTML elements
35+
- Provide ARIA labels where needed
36+
- Ensure keyboard navigation works
37+
- Test with screen readers
38+
- Maintain proper color contrast
39+
40+
## Performance
41+
42+
- Use `v-if` vs `v-show` appropriately
43+
- Avoid unnecessary watchers
44+
- Use `computed` for derived state
45+
- Lazy load components when possible
46+
- Optimize large lists with virtual scrolling
47+
48+
## Code for Human Brains
49+
50+
Write code that's easy to understand:
51+
52+
- **Keep it simple**: Prefer straightforward solutions
53+
- **Limit cognitive load**: Keep functions simple (≤4 concepts to hold in memory)
54+
- **Use meaningful names**: Variables should be self-documenting
55+
- **Prefer early returns**: Avoid deeply nested conditions
56+
- **Comment the "why"**: Explain motivation, not just what
57+
58+
### Example
59+
60+
❌ Hard to understand:
61+
```typescript
62+
if (val > someConstant && (condition2 || condition3) && (condition4 && !condition5)) {
63+
// What are we checking?
64+
}
65+
```
66+
67+
✅ Easy to understand:
68+
```typescript
69+
const isValid = val > someConstant;
70+
const isAllowed = condition2 || condition3;
71+
const isSecure = condition4 && !condition5;
72+
73+
if (isValid && isAllowed && isSecure) {
74+
// Clear what each condition means
75+
}
76+
```

‎packages/web-design/agent-skills/components/SKILL.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
name: components
3+
description: Use @inkcre/web-design Vue 3 components. Includes all 19 components with props, events, and usage examples.
4+
---
5+
6+
# @inkcre/web-design Components
7+
8+
Use this skill when working with the @inkcre/web-design Vue 3 component library.
9+
10+
## Overview
11+
12+
@inkcre/web-design provides 19 UI components for Vue 3 applications:
13+
- [inkAutoForm](references/inkAutoForm.md)
14+
- [inkButton](references/inkButton.md)
15+
- [inkDatetimePickerView](references/inkDatetimePickerView.md)
16+
- [inkDialog](references/inkDialog.md)
17+
- [inkDoubleCheck](references/inkDoubleCheck.md)
18+
- [inkDropdown](references/inkDropdown.md)
19+
- [inkField](references/inkField.md)
20+
- [inkForm](references/inkForm.md)
21+
- [inkHeader](references/inkHeader.md)
22+
- [inkInput](references/inkInput.md)
23+
- [inkJsonEditor](references/inkJsonEditor.md)
24+
- [inkLoading](references/inkLoading.md)
25+
- [inkPagination](references/inkPagination.md)
26+
- [inkPicker](references/inkPicker.md)
27+
- [inkPlaceholder](references/inkPlaceholder.md)
28+
- [inkPopup](references/inkPopup.md)
29+
- [inkSwitch](references/inkSwitch.md)
30+
- [inkTextarea](references/inkTextarea.md)
31+
- [inkTooltip](references/inkTooltip.md)
32+
33+
## Installation
34+
35+
```bash
36+
npm install @inkcre/web-design
37+
# or
38+
pnpm add @inkcre/web-design
39+
```
40+
41+
## Setup
42+
43+
```typescript
44+
// main.ts
45+
import { createApp } from 'vue'
46+
import InKCreWebDesign from '@inkcre/web-design'
47+
import "@inkcre/web-design/styles"
48+
49+
const app = createApp(App)
50+
app.use(InKCreWebDesign)
51+
```
52+
53+
## Component References
54+
55+
Each component has detailed documentation in the `references/` directory:
56+
57+
- [`inkAutoForm`](references/inkAutoForm.md) - Component with props, events, and examples
58+
- [`inkButton`](references/inkButton.md) - Component with props, events, and examples
59+
- [`inkDatetimePickerView`](references/inkDatetimePickerView.md) - Component with props, events, and examples
60+
- [`inkDialog`](references/inkDialog.md) - Component with props, events, and examples
61+
- [`inkDoubleCheck`](references/inkDoubleCheck.md) - Component with props, events, and examples
62+
- [`inkDropdown`](references/inkDropdown.md) - Component with props, events, and examples
63+
- [`inkField`](references/inkField.md) - Component with props, events, and examples
64+
- [`inkForm`](references/inkForm.md) - Component with props, events, and examples
65+
- [`inkHeader`](references/inkHeader.md) - Component with props, events, and examples
66+
- [`inkInput`](references/inkInput.md) - Component with props, events, and examples
67+
- [`inkJsonEditor`](references/inkJsonEditor.md) - Component with props, events, and examples
68+
- [`inkLoading`](references/inkLoading.md) - Component with props, events, and examples
69+
- [`inkPagination`](references/inkPagination.md) - Component with props, events, and examples
70+
- [`inkPicker`](references/inkPicker.md) - Component with props, events, and examples
71+
- [`inkPlaceholder`](references/inkPlaceholder.md) - Component with props, events, and examples
72+
- [`inkPopup`](references/inkPopup.md) - Component with props, events, and examples
73+
- [`inkSwitch`](references/inkSwitch.md) - Component with props, events, and examples
74+
- [`inkTextarea`](references/inkTextarea.md) - Component with props, events, and examples
75+
- [`inkTooltip`](references/inkTooltip.md) - Component with props, events, and examples

0 commit comments

Comments
 (0)