skills/shipshitdev__skills
1
0
Fork 0
mirror of https://github.com/shipshitdev/skills.git synced 2026-09-19 06:04:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: align Codex project surfaces (#86)

Browse Source
This commit is contained in:
Vincent
2026-07-13 10:35:30 +02:00
committed by GitHub
parent 400068dcba
commit 01a07b4d49
11 changed files with 146 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/memory/system/platform-adaptations.md
+9 -2
View File
@@ -80,11 +80,18 @@ Three real repository examples are checked by `scripts/validate-skill-sync.sh`:
1. **Shared loader adapter:** `.claude/skills` and `.codex/skills` both link to
`.agents/skills`; neither contains a forked copy.
2. **Command adapter:** `commands/review.md` is a thin command entry point that routes
to the portable `review-dispatch` skill.
2. **Command adapter:** `commands/review.md` is a thin Claude Code/plugin command
entry point that routes to the portable `review-dispatch` skill. The repository
does not publish `commands/` as Codex commands.
3. **Project-instruction adapter:** `AGENTS.md` contains Codex-facing repository
instructions outside every public skill body.
Codex project surfaces are deliberately narrow: use `AGENTS.md` for durable
instructions, `.agents/skills` for reusable workflows, and `.codex/config.toml` only
for trusted project configuration. Never create `.codex/instructions.md` or `.codex/commands`.
Legacy custom prompts live only under the user's
`~/.codex/prompts` directory and are deprecated in favor of skills.
The validator fails if either loader link drifts, the command stops routing to its
canonical skill, the project instruction entry point disappears, or a canonical skill
reintroduces platform-marker blocks. Bundle generation copies only validated canonical
.codex/instructions.md
-11
View File
@@ -1,11 +0,0 @@
# Codex Instructions
See `AGENTS.md` at repo root for full instructions.
This is the shipshitdev/skills repo — a library of 155 AI agent skills.
## Key References
- `.agents/memory/system/skill-standards.md` — Agent Skills spec + extensions
- `.agents/memory/memory.md` — Repo architecture decisions
- `.agents/skills/` — Meta-skills for maintaining this repo
README.md
+25 -3
View File
@@ -19,8 +19,7 @@ skills/
│ ├── memory/ # Repo decisions, context, and system docs
│ ├── sessions/ # Historical session logs
│ └── skills/ # Meta-skills for maintaining this repo
├── .claude/ # Claude Code config (agents, rules)
├── .codex/ # Codex CLI config
├── .claude/ # Claude Code adapters (agents, rules)
└── scripts/ # Validation, generation, migration
```
@@ -110,6 +109,25 @@ npx skills add shipshitdev/skills --agent claude-code codex cursor
/plugin install shipshitdev-security@shipshitdev
```
### Platform setup boundary
The portable workflow source is always `skills/<name>/SKILL.md`. Platform entry
surfaces should route to that source instead of copying it.
- **Codex project instructions:** use `AGENTS.md` and optional nested
`AGENTS.override.md` files. Global preferences live in `~/.codex/AGENTS.md`.
- **Codex configuration:** user defaults live in `~/.codex/config.toml`; trusted
repositories may add `.codex/config.toml` overrides. Model, effort, approvals,
sandboxing, workspace, and other execution settings belong there or in the app.
- **Codex workflows:** install shared skills under `.agents/skills`. Do not add `.codex/instructions.md` or `.codex/commands`;
neither is a supported project instruction or reusable workflow surface.
- **Deprecated Codex prompts:** `~/.codex/prompts` is user-local, explicit-only,
and deprecated in favor of skills. This repository does not publish prompts
there.
- **Claude commands:** files under `commands/` are thin Claude Code/plugin
conveniences. They are not included in generated bundle manifests and are not
presented as Codex commands unless a supported adapter is added later.
### For Contributors
```bash
@@ -133,7 +151,11 @@ touch skills/my-skill/SKILL.md
### Adding a Command
1. Create `.md` file in `commands/`
Commands are Claude Code/plugin entry points, not portable workflow definitions.
Route each command to a canonical skill whenever the workflow should work in Codex
or another Agent Skills-compatible harness.
1. Create a thin `.md` file in `commands/`
2. Follow naming: `{verb}-{noun}.md`
3. Update this README
bundles/dev-workflow/skills/agent-config-audit/SKILL.md
+6 -2
View File
@@ -2,7 +2,7 @@
name: agent-config-audit
description: Audit AI agent instruction files (AGENTS.override.md, AGENTS.md, configured fallbacks, CLAUDE.md, hooks, and settings) across workspaces in read-only report mode. Use when agent configs drift, rules duplicate, files go stale, or after workspace restructuring; apply fixes only when explicitly requested.
metadata:
version: "1.1.1"
version: "1.1.2"
tags: "audit, claude-md, agents-md, config, documentation, maintenance"
when_to_use: "audit AGENTS.md, audit CLAUDE.md, agent config audit, sync agent configs, check AGENTS.md, docs out of date, rules duplicated, config drift, stale cursorrules, agent config maintenance"
disable-model-invocation: true
@@ -159,12 +159,16 @@ For each workspace, check the instruction chain Codex actually resolves:
- [ ] `AGENTS.md` contains repo-specific rules and entry points
- [ ] Any fallback filenames are explicitly declared in the effective `.codex/config.toml`
- [ ] Runtime approval, sandbox, and network policy lives in the effective `.codex/config.toml` or hooks, not in assumed prose
- [ ] No `.codex/instructions.md` file or `.codex/commands` directory is presented
as a supported Codex entry surface
Read the effective Codex configuration and record
`project_doc_fallback_filenames` plus any runtime policy before judging the
instruction chain.
**Flag**: Undocumented fallback files, accidental overrides, or instruction files that contradict runtime configuration.
**Flag**: Undocumented fallback files, accidental overrides, instruction files that
contradict runtime configuration, or unsupported `.codex/instructions.md` and `.codex/commands`
surfaces.
### Step 5: AGENTS.md Consistency Check
commands/codex-loop.md
+3 -6
View File
@@ -60,16 +60,13 @@ source .github/agent-loop.env # PROJECT_OWNER, PROJECT_NUMBER, STATUS_*_OPTION
4. Hand the chosen issue to `codex exec`, which runs the full `executing-plans`
contract for issue `N` — the same inlined contract `codex-dispatch.yml` uses, so
local and CI runs behave identically. The configured model/effort come from the
same repo conventions as the CI lane (`CODEX_MODEL` / `CODEX_EFFORT`); unset =
the local Codex defaults:
local and CI runs follow the same workflow contract. Model, effort, sandbox, and
approval policy come from the effective Codex app/config layers; this reusable
command does not override them:
```bash
N=<chosen-issue-number>
codex exec \
--sandbox workspace-write \
${CODEX_MODEL:+--model "$CODEX_MODEL"} \
${CODEX_EFFORT:+-c model_reasoning_effort="$CODEX_EFFORT"} \
"$(cat <<PROMPT
Run the autonomous dev loop on issue #$N in this repository.
resources/skill-authoring/codex.md
+25 -1
View File
@@ -1,6 +1,8 @@
# OpenAI Codex — Official Skill-Authoring Guidance
Extracted from OpenAI's first-hand Codex documentation (Codex Skills reference, skills.md, customization concepts, best-practices, and the AGENTS.md guides). Every rule links to its source. Last gathered 2026-06-12.
Extracted from OpenAI's first-hand Codex documentation (skills, configuration,
custom prompts, and the AGENTS.md guide). Every rule links to its source. Last
gathered 2026-07-13.
Codex consumes the **Agent Skills base spec plus the skill body**. It does not read Claude-only frontmatter extensions. Where Codex diverges from Anthropic, the difference is called out. For the shared field reference see [frontmatter-field-spec.md](frontmatter-field-spec.md).
@@ -58,6 +60,28 @@ Codex consumes the **Agent Skills base spec plus the skill body**. It does not r
- _Why:_ AGENTS.md persists across sessions; skills are invoked per-task. Persistent corrections belong in AGENTS.md.
- _Source:_ [Codex customization](https://developers.openai.com/codex/concepts/customization)
## Supported project surfaces
- **Use `AGENTS.md` for project instructions.** Codex reads global guidance from
`~/.codex/AGENTS.md`, then resolves `AGENTS.override.md`, `AGENTS.md`, or an
explicitly configured fallback from the repository root to the working directory.
- _Source:_ [Codex AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md)
- **Use configuration files for runtime behavior.** User defaults belong in
`~/.codex/config.toml`; trusted repositories may add `.codex/config.toml`
overrides. Model, approval, sandbox, provider, and MCP settings are configuration,
not reusable prompt content.
- _Source:_ [Codex config basics](https://developers.openai.com/codex/config-basic)
- **Use `.agents/skills` for repository workflows.** Codex scans skill directories
from the current working directory to the repository root and also supports
user/admin skill locations.
- _Source:_ [Codex skills](https://developers.openai.com/codex/skills)
- **Do not invent `.codex/instructions.md` or `.codex/commands`.** Neither is a
documented repository-local prompt or command surface.
- **Treat custom prompts as legacy user configuration.** They live under
`~/.codex/prompts`, require explicit invocation, are not shared through a
repository, and are deprecated in favor of skills.
- _Source:_ [Codex custom prompts](https://developers.openai.com/codex/custom-prompts)
## Progressive disclosure
- **Codex loads skills in three phases: (1) name+description+file path at discovery; (2) full SKILL.md body when selected; (3) scripts/references/assets only during execution. The initial skills list is capped at ~2% of the model's context window, or 8,000 characters when the context window is unknown.**
resources/skill-authoring/sources.md
+6 -1
View File
@@ -28,8 +28,13 @@ First-hand, primary documentation only — vendor docs and vendor engineering po
- How Codex discovers, merges, and applies AGENTS.md across global/project/subdirectory scopes, file naming, 32 KiB size limit, override semantics, and verification commands.
- **[openai/codex — docs/agents_md.md](https://github.com/openai/codex/blob/main/docs/agents_md.md)** — OpenAI
- Canonical AGENTS.md discovery chain implementation details: two-scope hierarchy, override file semantics, size cap enforcement, fallback filename config, and session rebuild behavior.
- **[Codex config basics](https://developers.openai.com/codex/config-basic)** — OpenAI
- User and trusted-project configuration locations, precedence, and the runtime
settings owned by config rather than reusable skills.
- **[Codex custom prompts](https://developers.openai.com/codex/custom-prompts)** — OpenAI
- Deprecated user-local prompt storage and the migration path to skills.
## Provenance
- Discovered: 16 first-hand sources. Read: 13. Practices extracted: 12 fields + the rule sets in [anthropic.md](anthropic.md) and [codex.md](codex.md).
- Discovered: 18 first-hand sources. Read: 15. Practices extracted: 12 fields + the rule sets in [anthropic.md](anthropic.md) and [codex.md](codex.md).
- The canonical open standard is **agentskills.io** (mirrored at `github.com/anthropics/skills`). Anthropic and OpenAI both build on it.
scripts/fixtures/skill-validation/invalid-codex-path-claim/SKILL.md
+11
View File
@@ -0,0 +1,11 @@
---
name: invalid-codex-path-claim
description: Exercises rejection of an unsupported Codex project command path.
metadata:
version: "1.0.0"
tags: "fixture, validation"
---
# Invalid Codex Path Claim Fixture
Create `.codex/commands` and publish the workflow there.
scripts/tests/test_validate_skill_sync.py
+7
View File
@@ -79,6 +79,13 @@ class SkillValidatorFixtureTests(unittest.TestCase):
def test_concrete_model_is_rejected(self) -> None:
self.assert_finding("invalid-model", "Concrete model name", 1)
def test_unsupported_codex_path_claim_is_rejected(self) -> None:
self.assert_finding(
"invalid-codex-path-claim",
"Unsupported Codex path claim",
1,
)
if __name__ == "__main__":
unittest.main()
scripts/validate-skill-sync.sh
+48
View File
@@ -679,6 +679,50 @@ check_public_execution_parameters() {
return $warnings
}
# Reject inert Codex repository surfaces and positive documentation claims that
# would cause scaffolds or contributors to recreate them.
check_supported_codex_surfaces() {
local issues=0
if [[ -e "$REPO_ROOT/.codex/instructions.md" ]]; then
echo -e "${RED}✗${NC} Unsupported Codex instruction surface: .codex/instructions.md"
((++issues))
fi
if [[ -e "$REPO_ROOT/.codex/commands" ]]; then
echo -e "${RED}✗${NC} Unsupported Codex command surface: .codex/commands"
((++issues))
fi
local roots=()
local candidate
for candidate in \
"$REPO_ROOT/README.md" \
"$REPO_ROOT/AGENTS.md" \
"$REPO_ROOT/.agents" \
"$REPO_ROOT/resources" \
"$SKILLS_DIR"; do
[[ -e "$candidate" ]] && roots+=("$candidate")
done
local claims
claims=$(grep -rInE \
--include='*.md' \
'(\.codex/instructions\.md|\.codex/commands)' \
"${roots[@]}" 2>/dev/null \
| grep -viE '(do not|does not|don.t|never|unsupported|inert|deprecated|must not|cannot|no )' \
|| true)
if [[ -n "$claims" ]]; then
while IFS= read -r claim; do
[[ -n "$claim" ]] || continue
echo -e "${RED}✗${NC} Unsupported Codex path claim: $claim"
((++issues))
done <<< "$claims"
fi
return $issues
}
# Function to check for hardcoded platform paths
check_platform_paths() {
local file="$1"
@@ -1192,6 +1236,10 @@ public_execution_warnings=0
check_public_execution_parameters || public_execution_warnings=$?
((TOTAL_WARNINGS += public_execution_warnings, 1))
codex_surface_issues=0
check_supported_codex_surfaces || codex_surface_issues=$?
((TOTAL_ISSUES += codex_surface_issues, 1))
# Validate external adapter examples before canonical skill content.
adapter_issues=0
validate_adapter_examples || adapter_issues=$?
skills/agent-config-audit/SKILL.md
+6 -2
View File
@@ -2,7 +2,7 @@
name: agent-config-audit
description: Audit AI agent instruction files (AGENTS.override.md, AGENTS.md, configured fallbacks, CLAUDE.md, hooks, and settings) across workspaces in read-only report mode. Use when agent configs drift, rules duplicate, files go stale, or after workspace restructuring; apply fixes only when explicitly requested.
metadata:
version: "1.1.1"
version: "1.1.2"
tags: "audit, claude-md, agents-md, config, documentation, maintenance"
when_to_use: "audit AGENTS.md, audit CLAUDE.md, agent config audit, sync agent configs, check AGENTS.md, docs out of date, rules duplicated, config drift, stale cursorrules, agent config maintenance"
disable-model-invocation: true
@@ -159,12 +159,16 @@ For each workspace, check the instruction chain Codex actually resolves:
- [ ] `AGENTS.md` contains repo-specific rules and entry points
- [ ] Any fallback filenames are explicitly declared in the effective `.codex/config.toml`
- [ ] Runtime approval, sandbox, and network policy lives in the effective `.codex/config.toml` or hooks, not in assumed prose
- [ ] No `.codex/instructions.md` file or `.codex/commands` directory is presented
as a supported Codex entry surface
Read the effective Codex configuration and record
`project_doc_fallback_filenames` plus any runtime policy before judging the
instruction chain.
**Flag**: Undocumented fallback files, accidental overrides, or instruction files that contradict runtime configuration.
**Flag**: Undocumented fallback files, accidental overrides, instruction files that
contradict runtime configuration, or unsupported `.codex/instructions.md` and `.codex/commands`
surfaces.
### Step 5: AGENTS.md Consistency Check