Skip to content

Commit dfc91d4

Browse files
gblanc-1agblanc-1a
authored
Merge pull request #126 from wherka-ama/cleanup/remove-github-packages-dependency
feat(scaffold): improve scaffolding with InnerSource docs, rich skills, and GitHub templates
2 parents af2b98f + 51e76c2 commit dfc91d4

26 files changed

+2376
-183
lines changed

‎.vscodeignore.production‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ temp_*.txt
6969

7070
# Documentation (keep only essential)
7171
docs/
72+
presentation/
7273
!docs/assets/
7374
!docs/assets/*.png
7475
!docs/assets/*.jpg

‎docs/author-guide/agentic-primitives-guide.md‎

Lines changed: 294 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,294 @@
1+
# Agentic Primitives Guide
2+
3+
This guide helps you choose the right type of agentic primitive for your use case in the Prompt Registry ecosystem.
4+
5+
## Decision Tree
6+
7+
```mermaid
8+
flowchart TD
9+
A[Start: What do you want to create?] --> B{Is it for a specific task or scenario?}
10+
B -->|Yes| C{Do you need reusable behavior?}
11+
B -->|No| D{Do you want to share knowledge or standards?}
12+
13+
C -->|Yes| E{Does it require multiple files/assets?}
14+
C -->|No| F[Create a Prompt]
15+
16+
E -->|Yes| G[Create a Skill]
17+
E -->|No| H[Create an Agent]
18+
19+
D -->|Yes| I[Create an Instruction]
20+
D -->|No| J[Create a Collection]
21+
22+
F --> K[.prompt.md file]
23+
H --> L[.agent.md file]
24+
G --> M[SKILL.md with assets]
25+
I --> N[.instructions.md file]
26+
J --> O[.collection.yml file]
27+
```
28+
29+
## Primitive Types Comparison
30+
31+
| Primitive | Purpose | Complexity | When to Use | File Format | Key Features |
32+
|-----------|---------|------------|-------------|-------------|--------------|
33+
| **Prompt** | Single-task instructions | Low | Quick, specific tasks | `.prompt.md` | Simple, focused, reusable |
34+
| **Instruction** | Team standards & guidelines | Medium | Sharing best practices | `.instructions.md` | Contextual, educational |
35+
| **Agent** | AI persona with behavior | Medium-High | Specialized AI roles | `.agent.md` | Personality, expertise areas |
36+
| **Skill** | Complex capabilities with assets | High | Multi-file functionality | `SKILL.md` + assets | Bundled resources, tools |
37+
| **Collection** | Organized groups of primitives | Variable | Curating related content | `.collection.yml` | Metadata-driven grouping |
38+
39+
## Detailed Guide
40+
41+
### 🎯 Prompts (.prompt.md)
42+
43+
**Use when you need:**
44+
- Quick, task-specific instructions
45+
- Reusable single-purpose prompts
46+
- Simple formatting without complex behavior
47+
48+
**Examples:**
49+
- "Generate unit tests for this function"
50+
- "Explain this code in simple terms"
51+
- "Convert this SQL to MongoDB query"
52+
53+
**Structure:**
54+
```markdown
55+
# Code Review Prompt
56+
57+
You are a senior developer reviewing code for:
58+
- Performance issues
59+
- Security vulnerabilities
60+
- Code style violations
61+
62+
Please analyze the provided code and suggest improvements.
63+
```
64+
65+
### 📚 Instructions (.instructions.md)
66+
67+
**Use when you need:**
68+
- Team coding standards
69+
- Best practices documentation
70+
- Educational content for developers
71+
- Process guidelines
72+
73+
**Examples:**
74+
- "JavaScript coding standards for our team"
75+
- "Security review checklist"
76+
- "API design guidelines"
77+
78+
**Structure:**
79+
```markdown
80+
# React Component Standards
81+
82+
## Overview
83+
Guidelines for creating React components in our projects.
84+
85+
## Rules
86+
- Use functional components with hooks
87+
- Implement proper TypeScript types
88+
- Follow naming conventions
89+
90+
## Examples
91+
[Code examples and patterns]
92+
```
93+
94+
### 🤖 Agents (.agent.md)
95+
96+
**Use when you need:**
97+
- Specialized AI personas
98+
- Domain-specific expertise
99+
- Consistent behavior patterns
100+
- Role-based interactions
101+
102+
**Examples:**
103+
- "Senior React Architect"
104+
- "Security Auditor"
105+
- "Performance Optimization Expert"
106+
107+
**Structure:**
108+
```markdown
109+
# React Architect Agent
110+
111+
You are a senior React architect with 10+ years experience.
112+
113+
## Expertise
114+
- React ecosystem
115+
- Performance optimization
116+
- Architecture patterns
117+
118+
## Behavior
119+
- Ask clarifying questions about requirements
120+
- Suggest multiple implementation approaches
121+
- Consider scalability and maintainability
122+
123+
## Limitations
124+
- Focus on React/JavaScript solutions
125+
- Ask for business context when needed
126+
```
127+
128+
### 🛠️ Skills (SKILL.md)
129+
130+
**Use when you need:**
131+
- Complex multi-file functionality
132+
- External tool integration
133+
- Custom workflows with assets
134+
- Advanced capabilities
135+
136+
**Examples:**
137+
- "Database Migration Tool"
138+
- "API Documentation Generator"
139+
- "Test Suite Builder"
140+
141+
**Structure:**
142+
```
143+
skills/my-skill/
144+
├── SKILL.md
145+
├── assets/
146+
│ ├── templates/
147+
│ ├── scripts/
148+
│ └── config/
149+
└── examples/
150+
```
151+
152+
**SKILL.md Example:**
153+
```markdown
154+
---
155+
name: api-doc-generator
156+
description: Generates API documentation from code
157+
version: 1.0.0
158+
metadata:
159+
author: Team Name
160+
license: MIT
161+
---
162+
163+
# API Documentation Generator
164+
165+
Automatically generates comprehensive API documentation from source code.
166+
167+
## Features
168+
- Parses JSDoc comments
169+
- Generates Markdown docs
170+
- Creates interactive examples
171+
- Supports multiple frameworks
172+
173+
## Usage
174+
1. Point to your source directory
175+
2. Configure output format
176+
3. Generate documentation
177+
178+
## Assets
179+
- Templates for different output formats
180+
- Parsers for various languages
181+
- Example configurations
182+
```
183+
184+
### 📦 Collections (.collection.yml)
185+
186+
**Use when you need:**
187+
- Group related primitives
188+
- Share themed content sets
189+
- Organize by domain or purpose
190+
- Create curated experiences
191+
192+
**Examples:**
193+
- "React Development Starter Kit"
194+
- "Security Review Collection"
195+
- "Frontend Performance Tools"
196+
197+
**Structure:**
198+
```yaml
199+
name: react-starter-kit
200+
description: Essential prompts and tools for React development
201+
version: 1.0.0
202+
author: Team Name
203+
204+
items:
205+
- type: prompt
206+
path: prompts/component-review.prompt.md
207+
name: Component Review
208+
description: Review React components for best practices
209+
210+
- type: instruction
211+
path: instructions/react-standards.instructions.md
212+
name: React Standards
213+
description: Team coding standards for React
214+
215+
- type: agent
216+
path: agents/react-architect.agent.md
217+
name: React Architect
218+
description: Expert React architect for guidance
219+
220+
tags:
221+
- react
222+
- frontend
223+
- javascript
224+
- development
225+
226+
category: Development
227+
```
228+
229+
## Best Practices
230+
231+
### 1. Start Simple
232+
- Begin with prompts for specific tasks
233+
- Evolve to instructions for team standards
234+
- Create agents for specialized roles
235+
- Build skills for complex workflows
236+
237+
### 2. Naming Conventions
238+
- Use descriptive, action-oriented names
239+
- Include purpose in the filename
240+
- Follow consistent patterns:
241+
- `task-name.prompt.md`
242+
- `standard-name.instructions.md`
243+
- `role-name.agent.md`
244+
- `capability-name/` (for skills)
245+
246+
### 3. Content Quality
247+
- Provide clear examples
248+
- Include edge cases
249+
- Document limitations
250+
- Test with real scenarios
251+
252+
### 4. Organization
253+
- Group related items in collections
254+
- Use tags for discoverability
255+
- Provide meaningful descriptions
256+
- Version your content
257+
258+
## Migration Path
259+
260+
```mermaid
261+
flowchart LR
262+
A[Prompt] --> B[Instruction]
263+
A --> C[Agent]
264+
B --> D[Collection]
265+
C --> D
266+
C --> E[Skill]
267+
D --> F[Published Hub]
268+
E --> F
269+
```
270+
271+
1. **Start with Prompts** - Test individual use cases
272+
2. **Create Instructions** - Document successful patterns
273+
3. **Build Agents** - Encapsulate expert behavior
274+
4. **Develop Skills** - Handle complex scenarios
275+
5. **Organize Collections** - Group related content
276+
6. **Publish to Hub** - Share with your team
277+
278+
## Common Use Cases
279+
280+
| Scenario | Recommended Primitive | Why |
281+
|----------|---------------------|-----|
282+
| Code review checklist | Instruction | Educational, reusable standards |
283+
- Bug investigation assistant | Agent | Specialized expertise, consistent behavior |
284+
- API documentation generation | Skill | Complex, multi-file functionality |
285+
- React component templates | Collection | Grouped related content |
286+
- SQL query optimization | Prompt | Simple, specific task |
287+
- Security audit workflow | Skill | Multiple steps, tools, and assets |
288+
289+
## Resources
290+
291+
- [Prompt Registry Documentation](../README.md)
292+
- [Collection Authoring Guide](creating-collections.md)
293+
- [Skill Development Guide](creating-skills.md)
294+
- [Hub Configuration Guide](../reference/hub-config.md)

‎docs/author-guide/collection-scripts.md‎

Lines changed: 4 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -4,49 +4,22 @@ The Prompt Registry provides a shared npm package `@prompt-registry/collection-s
44

55
## Installation
66

7-
### Quick Setup with GitHub CLI (Recommended)
7+
### Quick Setup
88

9-
If you have the [GitHub CLI](https://cli.github.com/) installed:
9+
The `@prompt-registry/collection-scripts` package is now available on npmjs.com:
1010

1111
```bash
12-
# Ensure you have packages scope (one-time)
13-
gh auth login --scopes read:packages
14-
15-
# Configure npm to use GitHub Packages
16-
npm config set @prompt-registry:registry https://npm.pkg.github.com
17-
npm config set //npm.pkg.github.com/:_authToken $(gh auth token)
18-
1912
# Install the package
2013
npm install @prompt-registry/collection-scripts
2114
```
2215

23-
### Manual Setup
24-
25-
1. Create or edit `.npmrc` in your project root:
26-
```
27-
@prompt-registry:registry=https://npm.pkg.github.com
28-
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
29-
```
30-
31-
2. Set your GitHub token:
32-
```bash
33-
export GITHUB_TOKEN=<your-personal-access-token-with-read:packages>
34-
```
35-
36-
3. Install the package:
37-
```bash
38-
npm install @prompt-registry/collection-scripts
39-
```
40-
41-
### GitHub Actions (No Setup Required)
16+
### GitHub Actions
4217

43-
In GitHub Actions, authentication is automatic via `GITHUB_TOKEN`:
18+
In GitHub Actions, no special configuration is needed since the package is on npmjs:
4419

4520
```yaml
4621
- name: Install dependencies
4722
run: npm ci
48-
env:
49-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
5023
```
5124
5225
## Usage in Collection Repositories

0 commit comments

Comments
 (0)