xdrs-core 0.3.8 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: 003-write-skill
|
|
3
|
+
description: >
|
|
4
|
+
Creates a new skill package following XDR skill standards: determines type, scope, subject, and number;
|
|
5
|
+
then writes a focused SKILL.md with correct frontmatter, phased instructions, examples, and edge cases.
|
|
6
|
+
Activate this skill when the user asks to create, add, or write a new skill, agent skill, or SKILL.md file.
|
|
7
|
+
metadata:
|
|
8
|
+
author: flaviostutz
|
|
9
|
+
version: "1.0"
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Overview
|
|
13
|
+
|
|
14
|
+
Guides the creation of a well-structured skill package by following `_core-adr-003` skill standards, checking existing skills to avoid duplication, and producing a complete SKILL.md ready to activate in VS Code.
|
|
15
|
+
|
|
16
|
+
## Instructions
|
|
17
|
+
|
|
18
|
+
### Phase 1: Understand the Skill Goal
|
|
19
|
+
|
|
20
|
+
1. Read `.xdrs/_core/adrs/principles/003-skill-standards.md` in full to internalize the SKILL.md format, folder layout, and numbering rules.
|
|
21
|
+
2. Identify what the skill must do and the exact conditions under which an agent should activate it. Do NOT proceed without a clear goal and activation trigger.
|
|
22
|
+
|
|
23
|
+
### Phase 2: Select Type, Scope, Subject, and Number
|
|
24
|
+
|
|
25
|
+
**Type** — choose one based on the skill's activity:
|
|
26
|
+
- **EDR skill**: engineering workflows, tool usage, coding procedures, implementation how-tos
|
|
27
|
+
- **ADR skill**: architectural evaluation, pattern compliance, technology selection guidance
|
|
28
|
+
- **BDR skill**: business process execution, operations procedures, policy-driven activities
|
|
29
|
+
|
|
30
|
+
Quick test:
|
|
31
|
+
- "How to implement or operate something?" → EDR
|
|
32
|
+
- "How to evaluate or decide on architecture?" → ADR
|
|
33
|
+
- "How to execute a business process or policy?" → BDR
|
|
34
|
+
|
|
35
|
+
**Scope** — use `_local` unless the user explicitly names another scope.
|
|
36
|
+
|
|
37
|
+
**Subject** — pick the most specific match for the chosen type (see `003-skill-standards`):
|
|
38
|
+
- ADR subjects: `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
|
|
39
|
+
- BDR subjects: `principles`, `marketing`, `product`, `controls`, `operations`, `organization`, `finance`, `sustainability`
|
|
40
|
+
- EDR subjects: `principles`, `application`, `infra`, `ai`, `observability`, `devops`, `governance`
|
|
41
|
+
|
|
42
|
+
**Skill number** — scan `.xdrs/[scope]/[type]/[subject]/skills/` for the highest existing number and increment by 1. Never reuse numbers from deleted skills.
|
|
43
|
+
|
|
44
|
+
**Skill name** — `[number]-[short-kebab-case-description]`, max 64 characters total.
|
|
45
|
+
|
|
46
|
+
### Phase 3: Research Existing Skills and Related XDRs
|
|
47
|
+
|
|
48
|
+
1. List `.xdrs/[scope]/[type]/[subject]/skills/` for existing skills. If one already covers the goal, extend or reference it instead of creating a duplicate.
|
|
49
|
+
2. Read all XDRs relevant to the skill's domain to collect rules and cross-references.
|
|
50
|
+
|
|
51
|
+
### Phase 4: Write the SKILL.md
|
|
52
|
+
|
|
53
|
+
Use the mandatory agentskills format:
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
---
|
|
57
|
+
name: [number]-[skill-name]
|
|
58
|
+
description: >
|
|
59
|
+
[What the skill does AND exactly when an agent should activate it. Max 1024 chars.]
|
|
60
|
+
metadata:
|
|
61
|
+
author: [author]
|
|
62
|
+
version: "1.0"
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Overview
|
|
66
|
+
|
|
67
|
+
[1–3 sentence goal statement.]
|
|
68
|
+
|
|
69
|
+
## Instructions
|
|
70
|
+
|
|
71
|
+
### Phase 1: …
|
|
72
|
+
[Step-by-step agent instructions organized into named phases. Use imperative language.]
|
|
73
|
+
|
|
74
|
+
## Examples
|
|
75
|
+
|
|
76
|
+
[At least one concrete input/context → expected agent action pair.]
|
|
77
|
+
|
|
78
|
+
## Edge Cases
|
|
79
|
+
|
|
80
|
+
[Situations where the skill must not activate or must behave differently.]
|
|
81
|
+
|
|
82
|
+
## References
|
|
83
|
+
|
|
84
|
+
[Links to related XDRs and skills.]
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Rules:
|
|
88
|
+
- Use imperative language ("Read …", "Ask …", "Create …").
|
|
89
|
+
- The `description` field must state both *what* the skill does and *when* to activate it.
|
|
90
|
+
- Do not duplicate content from referenced XDRs — link instead.
|
|
91
|
+
- No emojis. Lowercase filenames. Target under 500 lines.
|
|
92
|
+
|
|
93
|
+
### Phase 5: Review the Draft
|
|
94
|
+
|
|
95
|
+
Before writing files, verify:
|
|
96
|
+
|
|
97
|
+
1. **Activation criteria**: Is it unambiguous when this skill loads vs. when it should not?
|
|
98
|
+
2. **Completeness**: Does every phase have actionable steps?
|
|
99
|
+
3. **Length**: Under 500 lines? Trim verbose explanations.
|
|
100
|
+
4. **Duplication**: Does this overlap an existing skill? If yes, revise.
|
|
101
|
+
5. **References**: Are all related XDRs and skills linked?
|
|
102
|
+
|
|
103
|
+
If any check fails, revise before continuing.
|
|
104
|
+
|
|
105
|
+
### Phase 6: Write Files
|
|
106
|
+
|
|
107
|
+
1. Create the skill file at `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`.
|
|
108
|
+
2. Create a hardlink at `.github/skills/[number]-[skill-name]/SKILL.md` so VS Code picks it up immediately:
|
|
109
|
+
```
|
|
110
|
+
mkdir -p .github/skills/[number]-[skill-name]
|
|
111
|
+
ln .xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md .github/skills/[number]-[skill-name]/SKILL.md
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### Constraints
|
|
115
|
+
|
|
116
|
+
- MUST follow the agentskills SKILL.md format from `003-skill-standards` exactly.
|
|
117
|
+
- MUST NOT create a skill that duplicates an existing one — extend or reference it instead.
|
|
118
|
+
- MUST keep scope `_local` unless the user explicitly states otherwise.
|
|
119
|
+
- MUST include a References section linking to `003-skill-standards`.
|
|
120
|
+
|
|
121
|
+
## Examples
|
|
122
|
+
|
|
123
|
+
**Input**: "Create a skill to help debug CI pipelines"
|
|
124
|
+
- Type: EDR (engineering workflow)
|
|
125
|
+
- Scope: `_local`
|
|
126
|
+
- Subject: `devops`
|
|
127
|
+
- Number: scan `.xdrs/_local/edrs/devops/skills/` → next available
|
|
128
|
+
- Output: `.xdrs/_local/edrs/devops/skills/001-debug-ci-pipeline/SKILL.md`
|
|
129
|
+
|
|
130
|
+
**Input**: "Create a skill to review API designs"
|
|
131
|
+
- Type: ADR (architectural evaluation)
|
|
132
|
+
- Scope: `_local`
|
|
133
|
+
- Subject: `integration`
|
|
134
|
+
- Number: scan `.xdrs/_local/adrs/integration/skills/` → next available
|
|
135
|
+
- Output: `.xdrs/_local/adrs/integration/skills/001-review-api-design/SKILL.md`
|
|
136
|
+
|
|
137
|
+
## Edge Cases
|
|
138
|
+
|
|
139
|
+
- If the user's goal is already covered by an existing skill, inform the user and offer to extend it instead of creating a new one.
|
|
140
|
+
- If scope is ambiguous, default to `_local` and note the assumption.
|
|
141
|
+
- If the goal spans multiple types (e.g., both EDR and ADR), favor the type that best matches the primary activity.
|
|
142
|
+
|
|
143
|
+
## References
|
|
144
|
+
|
|
145
|
+
- [_core-adr-003 - Skill standards](../../003-skill-standards.md)
|
|
146
|
+
- [_core-adr-001 - XDR standards](../../001-xdr-standards.md)
|
|
147
|
+
- [002-write-xdr skill](../002-write-xdr/SKILL.md)
|
package/package.json
CHANGED