Skip to content

Commit 3d8d61c

Browse files
f0d010cf0d010c
committed
Prepare SkillForge for launch
1 parent 7b7a568 commit 3d8d61c

11 files changed

Lines changed: 303 additions & 16 deletions

File tree

‎.github/ISSUE_TEMPLATE/false-positive.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
name: False positive
3+
about: Report a SkillForge rule that flags valid Codex skill/plugin content
4+
title: "[false positive]: "
5+
labels: false-positive
6+
---
7+
8+
## Repo or fixture
9+
10+
Link to the skill/plugin repo or paste the minimal fixture.
11+
12+
## Command
13+
14+
```bash
15+
codex-skillforge lint .
16+
```
17+
18+
## Output
19+
20+
```text
21+
Paste the relevant SkillForge output here.
22+
```
23+
24+
## Expected behavior
25+
26+
Explain why this should pass or be downgraded.

‎.github/ISSUE_TEMPLATE/rule-request.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
name: Rule request
3+
about: Suggest a new publish-readiness check for Codex skills/plugins
4+
title: "[rule]: "
5+
labels: rule-request
6+
---
7+
8+
## Problem
9+
10+
What mistake should SkillForge catch?
11+
12+
## Example
13+
14+
Paste or link to a minimal example.
15+
16+
## Desired severity
17+
18+
- [ ] Error
19+
- [ ] Warning
20+
21+
## Notes
22+
23+
Any relevant Codex docs, marketplace behavior, or real-world repo examples.

‎.github/pull_request_template.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
## Summary
2+
3+
## Validation
4+
5+
- [ ] `npm run build`
6+
- [ ] `npm test`
7+
- [ ] `npm audit`
8+
- [ ] `npm pack --dry-run`

‎.github/workflows/ci.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
jobs:
9+
test:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-node@v4
14+
with:
15+
node-version: "20"
16+
cache: "npm"
17+
- run: npm ci
18+
- run: npm run build
19+
- run: npm test
20+
- run: npm audit
21+
- run: npm pack --dry-run
22+
23+
dogfood:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- uses: actions/checkout@v4
27+
- uses: ./
28+
with:
29+
path: tests/fixtures/collection
30+
format: text

‎CONTRIBUTING.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Contributing
2+
3+
Thanks for helping improve SkillForge.
4+
5+
The most valuable contributions are real Codex skill/plugin repos that expose:
6+
7+
- false positives
8+
- missing publish-readiness checks
9+
- unclear scaffold defaults
10+
- marketplace packaging edge cases
11+
12+
## Local Setup
13+
14+
```bash
15+
npm install
16+
npm run build
17+
npm test
18+
```
19+
20+
## Before Opening A PR
21+
22+
```bash
23+
npm run build
24+
npm test
25+
npm audit
26+
npm pack --dry-run
27+
```
28+
29+
## Rule Changes
30+
31+
When adding or changing lint rules:
32+
33+
- add a fixture under `tests/fixtures`
34+
- add or update a Vitest case
35+
- prefer warnings for subjective quality checks
36+
- reserve errors for broken structure, missing files, invalid manifests, or failed smoke expectations
37+
38+
## Real-Repo Audits
39+
40+
If you run SkillForge against a public Codex extension repo, include:
41+
42+
- repo URL
43+
- command used
44+
- output summary
45+
- whether findings are true positives, false positives, or rule suggestions

‎README.md‎

Lines changed: 43 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,21 @@
11
# Codex SkillForge
22

3-
Creator tooling for OpenAI Codex skills and plugins: scaffold, lint, smoke-test, inspect, and package ecosystem artifacts.
3+
**ESLint for Codex skills and plugins.**
44

5-
SkillForge is the “Prettier + ESLint + create-vite” layer for Codex creators. It is not a marketplace. It helps you build skills and plugins that are clean enough to install locally, share in a repo, or submit to a marketplace.
5+
SkillForge helps Codex extension authors scaffold, lint, smoke-test, inspect, and package skills/plugins before they publish or submit them to a marketplace.
6+
7+
```bash
8+
npx codex-skillforge lint .
9+
```
10+
11+
Example output:
12+
13+
```text
14+
SkillForge plugin lint found 3 issue(s):
15+
[ERROR] plugin.skills.missing - Manifest path does not exist: ./skills/
16+
[WARNING] skill.description.vague - Description should clearly say what the skill does and when Codex should use it.
17+
[ERROR] metadata.openai-yaml.legacy-shape - agents/openai.yaml fields must live under interface:
18+
```
619

720
## Why This Exists
821

@@ -14,10 +27,12 @@ Codex skills and plugins are small, powerful folders. They are also easy to get
1427
- missing bundled skills, hooks, MCP, app, or asset files
1528
- plugins that work locally but are not marketplace-ready
1629

17-
SkillForge catches those problems before users do.
30+
SkillForge is not a marketplace. It is the publish-readiness check you run before sharing a Codex skill/plugin repo.
1831

1932
## Quick Start
2033

34+
From this repo:
35+
2136
```bash
2237
npm install
2338
npm run build
@@ -28,7 +43,7 @@ node dist/cli.js smoke ./my-skill
2843
node dist/cli.js pack ./my-skill
2944
```
3045

31-
When published to npm, the same flow becomes:
46+
When published to npm:
3247

3348
```bash
3449
npx codex-skillforge init skill ./my-skill --name my-skill
@@ -54,6 +69,29 @@ codex-skillforge pack ./my-plugin
5469

5570
`lint .` can inspect a repository-style collection and recursively find skill/plugin folders under paths like `.agents/skills` and `plugins`.
5671

72+
## GitHub Action
73+
74+
Use SkillForge in CI:
75+
76+
```yaml
77+
name: SkillForge
78+
79+
on:
80+
pull_request:
81+
push:
82+
branches: [main]
83+
84+
jobs:
85+
lint-codex-extensions:
86+
runs-on: ubuntu-latest
87+
steps:
88+
- uses: actions/checkout@v4
89+
- uses: f0d010c/skillforge@main
90+
with:
91+
path: .
92+
format: sarif
93+
```
94+
5795
## Config
5896
5997
Add `skillforge.json` to a skill or plugin root:
@@ -120,13 +158,7 @@ $HOME/.agents/plugins/marketplace.json
120158
- `INSTALL.md`
121159
- `marketplace-entry.json`
122160

123-
## CI
124-
125-
```yaml
126-
- run: npx codex-skillforge lint . --format sarif
127-
```
128-
129-
Exit codes:
161+
## Exit Codes
130162

131163
- `0`: pass, or warnings only
132164
- `1`: lint errors or failed smoke checks

‎action.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: "Codex SkillForge"
2+
description: "Lint Codex skills and plugins in CI."
3+
author: "f0d010c"
4+
5+
inputs:
6+
path:
7+
description: "Skill, plugin, or repository path to lint."
8+
required: false
9+
default: "."
10+
format:
11+
description: "Output format: text, json, or sarif."
12+
required: false
13+
default: "text"
14+
15+
runs:
16+
using: "composite"
17+
steps:
18+
- name: Set up Node.js
19+
uses: actions/setup-node@v4
20+
with:
21+
node-version: "20"
22+
- name: Install SkillForge dependencies
23+
shell: bash
24+
run: npm ci
25+
working-directory: ${{ github.action_path }}
26+
- name: Build SkillForge
27+
shell: bash
28+
run: npm run build
29+
working-directory: ${{ github.action_path }}
30+
- name: Run SkillForge
31+
shell: bash
32+
run: node "${{ github.action_path }}/dist/cli.js" lint "${{ inputs.path }}" --format "${{ inputs.format }}"

‎docs/audit-results.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Public Repo Audit Notes
2+
3+
SkillForge was tested against a small sample of public Codex skill/plugin repositories to validate that the rules catch useful issues without requiring project-specific setup.
4+
5+
## Sample
6+
7+
- `openai/codex-plugin-cc`
8+
- `sigridjineth/oh-my-codex`
9+
- `OutlineDriven/odin-codex-plugin`
10+
- `zeabur/agent-skills`
11+
- `TheGreenCedar/codex-autoresearch`
12+
13+
## Results
14+
15+
- `TheGreenCedar/codex-autoresearch`: passed after tuning path parsing for inline script examples.
16+
- `openai/codex-plugin-cc`: surfaced one weak trigger-description warning.
17+
- `zeabur/agent-skills`: surfaced a plugin package-name/folder-name mismatch as a warning.
18+
- `OutlineDriven/odin-codex-plugin`: surfaced missing references, long descriptions, late trigger wording, and unreferenced scripts across a large skill collection.
19+
- `sigridjineth/oh-my-codex`: surfaced many trigger-description warnings, large `SKILL.md` files, missing figure assets, and hook feature-flag documentation.
20+
21+
## Rule Changes From The Audit
22+
23+
- Plugin manifest/folder name mismatch is now a warning, because repo-level packages may intentionally differ from plugin package names.
24+
- Inline references such as `scripts/foo.mjs --flag` are no longer treated as missing files.
25+
- Placeholder/reference patterns with angle brackets, regex syntax, or command arguments are ignored by path-resolution checks.
26+
27+
## Marketing Takeaway
28+
29+
The strongest message is not "generic linter." It is:
30+
31+
> Before you submit or share a Codex plugin, run SkillForge to catch publish-readiness issues.

‎docs/example-pr.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Example PR Body For External Repos
2+
3+
## Summary
4+
5+
This runs the Codex skill/plugin files through SkillForge and fixes a few publish-readiness issues:
6+
7+
- aligns plugin manifest paths with `./`-relative plugin-root paths
8+
- improves skill trigger descriptions
9+
- fixes missing or stale metadata references
10+
11+
## Validation
12+
13+
```bash
14+
npx codex-skillforge lint .
15+
```
16+
17+
## Notes
18+
19+
SkillForge is a small OSS linter for Codex skills/plugins. I am testing it against real extension repos and opening small fixes where the checks catch something actionable.

‎docs/launch.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Launch Notes
2+
3+
## One-Liner
4+
5+
SkillForge is ESLint for Codex skills and plugins: scaffold, lint, smoke-test, and package Codex extensions before publishing.
6+
7+
## Short Post
8+
9+
I built a small OSS CLI for people making Codex skills/plugins.
10+
11+
Codex extensions are easy to package incorrectly: vague `SKILL.md` triggers, broken `./skills/` paths, stale `agents/openai.yaml`, missing hook files, marketplace metadata drift.
12+
13+
SkillForge gives authors a quick publish-readiness check:
14+
15+
```bash
16+
npx codex-skillforge lint .
17+
```
18+
19+
It also scaffolds skills/plugins, smoke-tests declared example prompts, and packs release artifacts with install notes.
20+
21+
Repo: https://github.com/f0d010c/skillforge
22+
23+
I am looking for Codex skill/plugin repos to test it against.
24+
25+
## Reddit / Hacker News Title Options
26+
27+
- I built an ESLint-style linter for Codex skills and plugins
28+
- Before you publish a Codex plugin, run this linter
29+
- SkillForge: publish-readiness checks for Codex skills/plugins
30+
31+
## Useful Reply To Feedback
32+
33+
Thanks. The main thing I am trying to validate is whether plugin authors want a stricter publish-readiness check before submitting to marketplaces. If you have a skill/plugin repo, I can run SkillForge against it and use the failures to improve the rules.
34+
35+
## Outreach Targets
36+
37+
- Codex plugin marketplace maintainers
38+
- `awesome-codex-plugins` maintainers
39+
- authors of public Codex skill/plugin repos
40+
- r/codex
41+
- OpenAI developer community posts about Codex skills/plugins

0 commit comments

Comments
 (0)