@iamdevlinph/codex-kit 1.0.9 → 1.0.10

package/README.md

@@ -168,9 +168,13 @@ pnpm dlx @iamdevlinph/codex-kit@latest project sync
 codex-kit project status
 ```
 
-`project sync` never edits `AGENTS.md`. It prints a prompt asking Codex to merge
-only applicable reusable changes while preserving local adaptations. After
-reviewing the semantic merge, record the applied template hash:
+`project sync` never edits `AGENTS.md` or project skills. It prints a prompt
+asking Codex to merge only applicable reusable changes while preserving local
+adaptations. Reconciliation keeps always-on rules in `AGENTS.md` and may create
+or update task-specific workflows under `.agents/skills` when the updated
+template warrants them. Critical safety and authorization rules remain in
+`AGENTS.md`, and speculative skills are avoided. After reviewing the semantic
+merge and any skill changes, record the applied template hash:
 
 ```sh
 codex-kit project mark-applied

package/assets/TEMPLATE_AGENTS.md

@@ -13,6 +13,28 @@ the managed markers.
   priorities, deferred requirements, product or implementation decisions, and
   major completed milestones.
 
+## Instructions And Skills
+
+- Keep `AGENTS.md` focused on durable, always-applicable repository context:
+  architecture, conventions, commands, safety and authorization boundaries,
+  verification expectations, and concise pointers to specialized workflows.
+- Use project skills under `.agents/skills/<skill-name>/SKILL.md` for repeatable,
+  task-specific workflows or detailed guidance needed only for matching tasks.
+- In existing projects, review large task-specific procedures in `AGENTS.md`.
+  When a procedure is reusable and conditionally relevant, extract it into a
+  project skill and leave a concise routing rule in `AGENTS.md`.
+- Preserve critical safety, authorization, destructive-operation, database, and
+  deployment restrictions in `AGENTS.md`, even when a skill contains the
+  detailed workflow.
+- In new projects, begin with a concise `AGENTS.md`. Add a skill only after a
+  concrete repeatable workflow or specialized procedure is identified; do not
+  create speculative skills.
+- Avoid duplicating detailed instructions between `AGENTS.md` and `SKILL.md`.
+  Keep the always-on rule in `AGENTS.md` and the conditional procedure in the
+  skill.
+- Each project skill must use valid YAML frontmatter with a clear `name` and a
+  `description` that states when the skill should trigger.
+
 ## Template Maintenance
 
 - Projects normally use `AGENTS.md` as the active instruction file. The source
@@ -52,8 +74,12 @@ contents of TEMPLATE_AGENTS.md between
 <!-- END codex-kit:shared-template -->. Preserve every repository-specific
 instruction from the current AGENTS.md after the managed block under
 # Project-Specific Instructions, remove only duplicate shared rules, and do not
-change project behavior. Afterward, summarize what was preserved and whether any
-local rules appear template-worthy.
+change project behavior. Review existing project skills under .agents/skills and
+move conditionally relevant, repeatable procedures out of AGENTS.md only when a
+skill is warranted. Preserve critical safety and authorization rules in
+AGENTS.md, preserve existing relevant skills, avoid speculative skills, and
+validate any skill you create or modify. Afterward, summarize what was preserved,
+what moved into a skill, and whether any local rules appear template-worthy.
 ```
 
 ## Core Behavior

package/bin/codex-kit.js

@@ -266,7 +266,29 @@ function saveProjectState(cwd, state) {
     write(join(cwd, PROJECT_STATE_FILE), `${JSON.stringify(state, null, 2)}\n`);
 }
 function templatePrompt() {
-    return `Template reference updated. Ask Codex:\n\nThe project's TEMPLATE_AGENTS.md was refreshed from codex-kit. Compare it with\nAGENTS.md and merge only new or changed reusable guidelines that apply to this\nrepository. Preserve project-specific instructions and existing adaptations. Do\nnot replace AGENTS.md wholesale. If a template rule conflicts with a local rule,\nkeep the local rule and report the conflict. Summarize what was added, updated,\nskipped, or adapted, and why. When finished, run codex-kit project mark-applied.`;
+    return `Template reference updated. Ask Codex:
+
+The project's TEMPLATE_AGENTS.md was refreshed from codex-kit. Compare it with
+AGENTS.md and merge only new or changed reusable guidelines that apply to this
+repository.
+
+Keep durable, always-applicable repository rules in AGENTS.md. When the updated
+template identifies a repeatable, task-specific procedure, inspect existing
+project skills under .agents/skills and create or update a skill only when it
+would reduce conditional detail in AGENTS.md. Preserve existing relevant skills
+and avoid duplicating detailed instructions between AGENTS.md and SKILL.md.
+
+Keep critical safety, authorization, database, deployment, and destructive-
+operation restrictions in AGENTS.md even when a skill contains the detailed
+workflow. Do not create speculative skills.
+
+Preserve project-specific instructions and existing adaptations. Do not replace
+AGENTS.md wholesale. If a template rule conflicts with a local rule, keep the
+local rule and report the conflict.
+
+Summarize what was added, updated, skipped, adapted, or moved into a skill, and
+why. Validate any created or modified skills. When finished, run codex-kit
+project mark-applied.`;
 }
 function managedBlock(content, begin, end) {
     return `${begin}\n${content.trimEnd()}\n${end}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamdevlinph/codex-kit",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "Portable Codex subagents and project AGENTS.md defaults.",
   "type": "module",
   "bin": {