Skip to content

Commit 718f70e

Browse files
Kevin NgoKevin Ngo
Kevin Ngo
authored and
Kevin Ngo
committed
Initial repository scaffolding
Set up CockroachDB Skills repository structure with: - 9 operational domain directories - GitHub Actions validation workflow - Issue and PR templates - Comprehensive contribution guidelines - Validation script for Agent Skills Specification compliance This establishes the foundation for community contributions of CockroachDB operational expertise as structured Agent Skills.
0 parents  commit 718f70e

File tree

21 files changed

+1679
-0
lines changed

21 files changed

+1679
-0
lines changed

‎.github/ISSUE_TEMPLATE/bug-report.yml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
name: Bug Report
2+
description: Report an issue with an existing CockroachDB skill
3+
title: "[Bug] "
4+
labels: ["bug", "needs-triage"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for reporting a bug! Please provide details about the issue you've found.
10+
11+
- type: input
12+
id: skill-name
13+
attributes:
14+
label: Skill Name
15+
description: Which skill has the issue?
16+
placeholder: "e.g., analyzing-slow-queries"
17+
validations:
18+
required: true
19+
20+
- type: input
21+
id: skill-path
22+
attributes:
23+
label: Skill Path
24+
description: Full path to the skill directory
25+
placeholder: "e.g., skills/performance-and-scaling/analyzing-slow-queries/"
26+
validations:
27+
required: true
28+
29+
- type: textarea
30+
id: expected-behavior
31+
attributes:
32+
label: Expected Behavior
33+
description: What did you expect to happen?
34+
placeholder: "The skill should guide me to identify slow queries using the DB Console..."
35+
validations:
36+
required: true
37+
38+
- type: textarea
39+
id: actual-behavior
40+
attributes:
41+
label: Actual Behavior
42+
description: What actually happened?
43+
placeholder: "The skill references a SQL query that doesn't work in CockroachDB v23.1..."
44+
validations:
45+
required: true
46+
47+
- type: textarea
48+
id: reproduction
49+
attributes:
50+
label: Steps to Reproduce
51+
description: How can we reproduce this issue?
52+
placeholder: |
53+
1. Open the skill in an AI agent
54+
2. Follow the guidance in section "Analyzing Execution Plans"
55+
3. Run the suggested SQL query
56+
4. Observe the error...
57+
validations:
58+
required: true
59+
60+
- type: textarea
61+
id: environment
62+
attributes:
63+
label: Environment Context
64+
description: Relevant environment information
65+
placeholder: |
66+
- CockroachDB version: v23.1.5
67+
- AI agent used: Claude Code
68+
- Cluster type: CockroachDB Serverless
69+
validations:
70+
required: false
71+
72+
- type: textarea
73+
id: additional-context
74+
attributes:
75+
label: Additional Context
76+
description: Any other relevant information
77+
placeholder: "Add screenshots, error messages, or other helpful context here."

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: General Questions
4+
url: https://github.com/cockroachlabs/cockroachdb-skills/discussions
5+
about: Ask questions or discuss ideas that don't fit the templates above
6+
- name: CockroachDB Documentation
7+
url: https://www.cockroachlabs.com/docs/
8+
about: Official CockroachDB documentation
9+
- name: CockroachDB Community
10+
url: https://www.cockroachlabs.com/community/
11+
about: Join the CockroachDB community

‎.github/ISSUE_TEMPLATE/documentation.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Documentation Improvement
2+
description: Suggest improvements to repository documentation
3+
title: "[Docs] "
4+
labels: ["documentation", "enhancement"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for helping improve our documentation! Please describe what needs to be improved.
10+
11+
- type: dropdown
12+
id: documentation-type
13+
attributes:
14+
label: Documentation Type
15+
description: What documentation needs improvement?
16+
options:
17+
- README.md
18+
- CONTRIBUTING.md
19+
- Skill documentation (SKILL.md)
20+
- Issue/PR templates
21+
- Other
22+
validations:
23+
required: true
24+
25+
- type: textarea
26+
id: current-issue
27+
attributes:
28+
label: What's Unclear or Incorrect?
29+
description: What about the current documentation is unclear, incorrect, or missing?
30+
placeholder: "The CONTRIBUTING.md doesn't explain how to choose between domains when a skill could fit in multiple places..."
31+
validations:
32+
required: true
33+
34+
- type: textarea
35+
id: proposed-changes
36+
attributes:
37+
label: Proposed Changes
38+
description: How would you improve this documentation?
39+
placeholder: |
40+
Add a decision tree or flowchart to help contributors choose the right domain:
41+
42+
1. If the skill is primarily about migration → Onboarding and Migrations
43+
2. If the skill is primarily about performance → Performance and Scaling
44+
...
45+
validations:
46+
required: true
47+
48+
- type: textarea
49+
id: affected-sections
50+
attributes:
51+
label: Affected Sections
52+
description: Which specific sections or files need updating?
53+
placeholder: |
54+
- CONTRIBUTING.md, "Domain Structure" section
55+
- README.md, "Skill Domains" section (for consistency)
56+
validations:
57+
required: false
58+
59+
- type: textarea
60+
id: additional-context
61+
attributes:
62+
label: Additional Context
63+
description: Any other relevant information
64+
placeholder: "This confusion came up when I was trying to propose a skill for migration performance optimization..."

‎.github/ISSUE_TEMPLATE/new-skill.yml‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
name: New Skill Proposal
2+
description: Propose a new CockroachDB skill for the repository
3+
title: "[Skill] "
4+
labels: ["skill-proposal", "needs-review"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for proposing a new CockroachDB skill! Please fill out the information below to help us understand your proposal.
10+
11+
- type: input
12+
id: skill-name
13+
attributes:
14+
label: Skill Name
15+
description: Proposed name for the skill (lowercase, hyphens only, preferably gerund form like "analyzing-slow-queries")
16+
placeholder: "e.g., analyzing-slow-queries"
17+
validations:
18+
required: true
19+
20+
- type: dropdown
21+
id: domain
22+
attributes:
23+
label: Domain
24+
description: Which operational domain does this skill belong to?
25+
options:
26+
- Onboarding and Migrations
27+
- Application Development
28+
- Performance and Scaling
29+
- Operations and Lifecycle
30+
- Resilience and Disaster Recovery
31+
- Observability and Diagnostics
32+
- Security and Governance
33+
- Integrations and Ecosystem
34+
- Cost and Usage Management
35+
validations:
36+
required: true
37+
38+
- type: textarea
39+
id: description
40+
attributes:
41+
label: Description
42+
description: Brief description of what the skill does and when to use it (max 1024 characters)
43+
placeholder: "Identifies and diagnoses slow queries using CockroachDB's built-in observability tools. Use when query performance degrades or users report slow response times."
44+
validations:
45+
required: true
46+
47+
- type: textarea
48+
id: scope
49+
attributes:
50+
label: Scope and Boundaries
51+
description: What is explicitly included and excluded from this skill?
52+
placeholder: |
53+
**Included:**
54+
- Identifying slow queries from system tables
55+
- Analyzing query execution plans
56+
- Recommending index improvements
57+
58+
**Excluded:**
59+
- Automatic index creation
60+
- Schema redesign
61+
- Hardware capacity planning
62+
validations:
63+
required: true
64+
65+
- type: textarea
66+
id: inputs-outputs
67+
attributes:
68+
label: Expected Inputs and Outputs
69+
description: What information does this skill need, and what does it provide?
70+
placeholder: |
71+
**Inputs:**
72+
- Access to CockroachDB DB Console or SQL shell
73+
- Query performance metrics
74+
- Current schema information
75+
76+
**Outputs:**
77+
- List of slow queries ranked by impact
78+
- Execution plan analysis
79+
- Specific optimization recommendations
80+
validations:
81+
required: true
82+
83+
- type: textarea
84+
id: safety
85+
attributes:
86+
label: Safety Considerations
87+
description: Are there any risks or safety guardrails needed for this skill?
88+
placeholder: |
89+
- Avoid running EXPLAIN ANALYZE on production write queries
90+
- Consider cluster load when collecting diagnostics
91+
- Recommend testing index changes in staging first
92+
93+
- type: textarea
94+
id: references
95+
attributes:
96+
label: CockroachDB Documentation References
97+
description: Links to relevant official CockroachDB documentation
98+
placeholder: |
99+
- https://www.cockroachlabs.com/docs/stable/query-performance-best-practices.html
100+
- https://www.cockroachlabs.com/docs/stable/explain.html
101+
validations:
102+
required: true
103+
104+
- type: textarea
105+
id: use-case
106+
attributes:
107+
label: Use Case and Motivation
108+
description: Why is this skill needed? Who will benefit from it?
109+
placeholder: |
110+
This skill is needed because query performance issues are one of the most common operational challenges.
111+
Database operators and SREs need structured guidance to diagnose and resolve slow queries efficiently.
112+
113+
This skill would help:
114+
- New CockroachDB users unfamiliar with performance debugging
115+
- SREs responding to production incidents
116+
- Developers optimizing application queries
117+
validations:
118+
required: true
119+
120+
- type: checkboxes
121+
id: checklist
122+
attributes:
123+
label: Proposal Checklist
124+
description: Please confirm the following
125+
options:
126+
- label: I have searched existing issues and this skill has not been proposed yet
127+
required: true
128+
- label: I have reviewed the Agent Skills Specification (https://agentskills.io/specification)
129+
required: true
130+
- label: I have read the contributing guidelines (CONTRIBUTING.md)
131+
required: true
132+
- label: The skill name follows naming conventions (lowercase, hyphens, no reserved words)
133+
required: true

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
## What does this PR do?
2+
3+
<!-- Provide a brief summary of your changes -->
4+
5+
## Related Issue
6+
7+
<!-- Link to the skill proposal or issue this PR addresses -->
8+
Closes #
9+
10+
## Type of Change
11+
12+
<!-- Check all that apply -->
13+
14+
- [ ] New skill
15+
- [ ] Skill update/improvement
16+
- [ ] Documentation update
17+
- [ ] Infrastructure/tooling change
18+
- [ ] Bug fix
19+
20+
## Skill Compliance Checklist
21+
22+
<!-- If this PR adds or modifies a skill, complete this checklist -->
23+
24+
- [ ] SKILL.md includes required frontmatter fields (`name`, `description`)
25+
- [ ] Skill name follows naming conventions (lowercase, hyphens, gerund form preferred)
26+
- [ ] Skill name matches directory name exactly
27+
- [ ] Description is specific and includes "when to use" trigger keywords
28+
- [ ] Description is max 1024 characters
29+
- [ ] Skill is under 500 lines (or uses `references/` for detailed content)
30+
- [ ] References official CockroachDB documentation (not duplicate content)
31+
- [ ] Includes safety guardrails for risky operations (if applicable)
32+
- [ ] Tested with at least one AI agent (manual validation)
33+
- [ ] No time-sensitive information (version numbers, dates, "currently")
34+
- [ ] Directory structure follows specification (only `scripts/`, `references/`, `assets/` subdirs)
35+
- [ ] No reserved words in skill name ("anthropic", "claude")
36+
- [ ] Local validation passes: `python scripts/validate-spec.py skills/`
37+
38+
## Documentation Updates
39+
40+
<!-- List any documentation files that were updated or need updating -->
41+
42+
- [ ] README.md
43+
- [ ] CONTRIBUTING.md
44+
- [ ] Skill SKILL.md files
45+
- [ ] Other (specify):
46+
47+
## Testing
48+
49+
<!-- Describe how you validated this change -->
50+
51+
**Manual testing:**
52+
- [ ] Tested with AI agent (specify which one):
53+
- [ ] Verified skill is discoverable with appropriate prompts
54+
- [ ] Validated technical accuracy against CockroachDB docs
55+
- [ ] Tested any scripts or commands included in the skill
56+
57+
**Automated testing:**
58+
- [ ] Local validation script passes: `python scripts/validate-spec.py skills/`
59+
- [ ] CI validation will run automatically on this PR
60+
61+
## Additional Context
62+
63+
<!-- Add any other relevant information, screenshots, or notes -->
64+
65+
## Reviewer Notes
66+
67+
<!-- Anything specific you want reviewers to focus on? -->
68+
69+
---
70+
71+
**By submitting this PR, I confirm:**
72+
- [ ] I have read the [contributing guidelines](../CONTRIBUTING.md)
73+
- [ ] I have followed the [Agent Skills Specification](https://agentskills.io/specification)
74+
- [ ] I have tested my changes
75+
- [ ] I am willing to address review feedback

0 commit comments

Comments
 (0)