rules-extract
Extract project-specific coding rules and domain knowledge from an existing codebase, generating structured markdown for AI agents. Use when onboarding a new project, after code review discussions about coding style, after sessions where preferences were corrected (--from-conversation), after PRs with significant review feedback (--from-pr), when rule files exceed 40k chars (--compact), or when the project structure has evolved and rules need reorganization (--restructure).
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- rules-extract
- description
- Extract project-specific coding rules and domain knowledge from an existing codebase, generating structured markdown for AI agents. Use when onboarding a new project, after code review discussions about coding style, after sessions where preferences were corrected (--from-conversation), after PRs with significant review feedback (--from-pr), when rule files exceed 40k chars (--compact), or when the project structure has evolved and rules need reorganization (--restructure).
- allowed-tools
- Read Glob Grep Write Edit Agent TodoWrite Bash(git:*) Bash(gh:*) Bash(ls:*) Bash(pwd:*) Bash(node:*)
02 资源文件 15
- 参考文档references/compaction-mode.md28.2 KB
- 参考文档references/compaction-orchestration.md23.1 KB
- 参考文档references/conversation-mode.md11.7 KB
- 参考文档references/examples-format.md8.0 KB
- 参考文档references/extraction-criteria.md6.9 KB
- 参考文档references/full-extraction-mode.md9.8 KB
- 参考文档references/integration-criteria.md1.5 KB
- 参考文档references/output-structure.md6.6 KB
- 参考文档references/pr-review-mode.md11.9 KB
- 参考文档references/report-templates.md8.6 KB
- 参考文档references/resolve-references.md2.4 KB
- 参考文档references/restructure-mode.md3.7 KB
- 参考文档references/security.md1.1 KB
- 参考文档references/update-mode.md6.8 KB
- 脚本scripts/extract_session_messages.mjs5.9 KB
03 SKILL.md 正文
Extract Rules
Analyzes existing codebase to identify what Codex would get wrong without project-specific guidance, extracting coding rules and domain knowledge as structured markdown documentation for AI agents.
Quick Start
| Mode | Command | When |
|---|---|---|
| Full extraction | /rules-extract |
New project — no .Codex/rules/ yet |
| Update | /rules-extract --update |
Re-scan and add new patterns (preserves existing) |
| Restructure | /rules-extract --restructure |
Project evolved, new frameworks, or split_output changed |
| Conversation | /rules-extract --from-conversation |
Extract from current or recent session |
| Compaction | /rules-extract --compact |
Rules file exceeded 40k chars |
| PR Review | /rules-extract --from-pr 123 |
Extract from PR review comments |
Typical first run:
- Optionally create
.Codex/rules-extract.local.mdwithoutput_dir,language,split_output - Run
/rules-extract— detects stack, samples files, writes rule files - Review generated files in
output_dir(default.Codex/rules/) - Run
/rules-extract --updateafter significant codebase changes or conversations
When to Use
- Onboarding a new project with no
.Codex/rules/yet - After code review sessions where coding preferences were corrected
- After PRs with significant reviewer feedback on style or conventions
- When
.Codex/rules/files have grown past 40k chars (--compact) - After the codebase adds a new framework or architectural layer (
--updateor--restructure) - When
split_outputsetting changes and files need format migration (--restructure)
When NOT to Use
- Creating a rule from a single observation → use
rule-developmentinstead - Merging rules across multiple org projects → use
rules-mergeinstead - Applying org rules to the current project → use
rules-applyinstead - Reviewing rule compliance against a diff → use
/rules-reviewinstead
Usage
/rules-extract # Extract rules from codebase (initial)
/rules-extract --update # Re-scan and add new patterns (preserve existing)
/rules-extract --restructure # Re-analyze, reorganize structure, merge existing rules
/rules-extract --from-conversation # Extract from current session (latest)
/rules-extract --from-conversation <session-id> # Extract from a specific session
/rules-extract --from-pr 123 # PR in current repo
/rules-extract --from-pr owner/repo#123 # PR in another repo (URL form also accepted)
/rules-extract --from-pr 100..110 # PR range (space-separate multiple specs for cross-analysis)
/rules-extract --compact # Compact all over-threshold rules files (output_dir/**/*.md)
/rules-extract --compact path/to/file.md ... # Compact specific files
Configuration
Settings file: rules-extract.local.md (YAML frontmatter only, no markdown body)
- Project-level:
.Codex/rules-extract.local.md(takes precedence) - User-level:
~/.Codex/rules-extract.local.md
| Setting | Default | Description |
|---|---|---|
target_dirs |
["."] |
Analysis target directories |
exclude_dirs |
[".git", ".Codex"] |
Exclude directories (in addition to .gitignore) |
exclude_patterns |
[] |
Exclude file patterns (e.g., *.generated.ts, *.d.ts) |
output_dir |
.Codex/rules |
Output directory for rule files (.md and .local.md). Inside Codex's .Codex/rules/** recursive auto-load scope — every file written here is injected into context on session start |
examples_output_dir |
.Codex/rules-extras |
Output directory for .examples.md files. Defaults to a sibling directory outside .Codex/rules/** auto-load scope. Set to output_dir to opt examples into auto-load |
staging_output_dir |
.Codex/rules-staging |
Staging directory for 1st-observation project-level candidates from incremental modes; 2nd-observation matches are promoted to canonical. See references/output-structure.md § Configuration Details |
language |
en |
Report language (e.g., en, ja) |
split_output |
true |
Separate Principles (.md) and patterns (.local.md) |
resolve_references |
true |
Resolve file references during restructure |
compaction_threshold |
40000 |
Char count threshold for --compact mode; files above this value are compacted. Default 40000 matches Codex's per-file warning. See references/output-structure.md § Configuration Details |
min_cluster_size |
3 |
Minimum bullet cluster size for consolidation detection in --compact mode. See references/output-structure.md § Configuration Details |
See references/output-structure.md § Configuration YAML for a full example with all settings.
Output Structure
Three output directories: output_dir (rule files — inside .Codex/rules/** auto-load scope), examples_output_dir (.examples.md files — outside auto-load by default), staging_output_dir (1st-observation project-level candidates from incremental modes). The paths: frontmatter on rule files is a human-facing scope hint; auto-load is determined by directory placement only.
See references/output-structure.md for directory tree diagrams (default, hybrid, integration libraries), YAML config example, and rule file format.
Shared Reference Files
Pre-load these files before executing any mode procedure — they are referenced throughout the mode reference files:
| File | Used for |
|---|---|
references/extraction-criteria.md |
Pattern classification criteria (what to extract vs. skip) |
references/security.md |
Security self-check patterns (run after every generation step) |
references/examples-format.md |
.examples.md file structure and generation procedure |
references/report-templates.md |
Report format for all modes |
Processing Flow
Mode Detection
Check arguments to determine mode:
- No arguments → Full Extraction Mode
--update→ Update Mode--restructure→ Restructure Mode--from-conversation [session-id]→ Conversation Extraction Mode--compact [<paths>]→ Compaction Mode--from-pr <number|owner/repo#number|range> [...]→ PR Review Extraction Mode
Full Extraction Mode
Load settings, detect project type, collect sample files, analyze by category (using pre-loaded extraction-criteria.md), analyze documentation and deduplicate against existing rules, generate output per split_output mode with security self-check, and report.
Read references/full-extraction-mode.md for the complete procedure (Steps 1–7).
Update Mode
When --update is specified, re-scan the codebase and add new patterns while preserving existing rules.
Staging awareness: Update Mode reads the staging file under staging_output_dir (when present) and promotes any staged project-level patterns that re-match against fresh code observations to canonical (<output_dir>/project.md), removing them from staging. Update Mode does not write new entries to staging — un-matched new patterns land directly in canonical. See references/conversation-mode.md § Mode interaction summary for the full per-mode staging behavior.
Operational note: After a dependency's major-version bump, run --update so the Step U3 staleness check flags removed symbols. The check only scans inline `symbol` in .local.md's ## Project-specific patterns — .examples.md is not auto-scanned. --restructure is not a substitute here: it reorganizes files without running the staleness check.
Read references/update-mode.md for the complete procedure (Steps U1–U6).
Restructure Mode
When --restructure is specified, re-analyze the codebase to determine the optimal file structure, then merge existing rule content into the new structure. Use when the project has evolved (new frameworks, architectural changes), when split_output settings change, or after updating the rules-extract skill itself.
Note: Restructure Mode does NOT run the staleness check — use --update first so stale symbols are flagged for manual review.
Read references/restructure-mode.md for the complete procedure (Steps R1–R5).
Conversation Extraction Mode
When --from-conversation is specified, extract rules from the full conversation history stored in session .jsonl files. The heavy processing (jsonl parsing, analysis, rule writing) is delegated to a subagent to keep the main context clean.
Step C1: Prepare and Locate Session File (main agent)
-
Load settings from
rules-extract.local.md(same as Step 1 inreferences/full-extraction-mode.md) -
Check if output directory exists (default:
.Codex/rules/)- If not exists: Error "Run /rules-extract first to initialize rule files."
-
Locate the session file:
- Get the current working directory (
pwd) - Encode the path: replace
/and.with-(leading-is kept)- Example:
/Users/hiropon/Sources/github.com/myproject→-Users-hiropon-Sources-github-com-myproject
- Example:
- Session files are stored at:
~/.Codex/projects/<encoded-path>/<session-id>.jsonl
- Get the current working directory (
-
Select the target session:
- If a
<session-id>argument is provided: use~/.Codex/projects/<encoded-path>/<session-id>.jsonl - If no argument: use the most recently modified
.jsonlfile in the directory (byls -t) - Verify the file exists. Inform the user which session file was selected.
- If a
Step C2: Delegate to Subagent (main agent)
Spawn a subagent using the Agent tool. The subagent performs all heavy processing (C3–C5) and returns a summary of what was added. Read references/conversation-mode.md for the full subagent instructions (Steps C3–C5).
Include in the agent prompt:
- This skill's absolute directory path (where SKILL.md resides — needed to run bundled scripts)
- Session file absolute path
output_dir,examples_output_dir, andstaging_output_dirpaths, plussplit_output/languagesettingscanonical_files: list of existing rule file paths for canonical-match deduplication — include both rule files underoutput_dirand.examples.mdfiles underexamples_output_dirstaging_files: list of existing staging file paths for staging-match detection — include the project-level staging file understaging_output_dir- The subagent instructions from
references/conversation-mode.md - Contents of
references/extraction-criteria.md(Step C4 uses for classification criteria) - Contents of
references/security.md(Step C5 item 7 security self-check) - Contents of
references/examples-format.md(Step C5 item 6 examples generation) - Contents of
references/report-templates.md(Step C5 item 8 summary format)
After the subagent completes, report the results to the user.
Compaction Mode
When --compact is specified, compact over-threshold rules files. Target file selection, char-count check, and threshold filtering all happen inside this mode — orchestrating callers invoke --compact without file arguments.
Uses the Pattern A iteration loop: main thread resolves targets → subagent analyzes → main thread applies mechanical_edits → fenced JSON return contract for caller dispatch. Per-file outer loop with max_iterations = 2 (default).
Read references/compaction-orchestration.md for the full orchestration steps: CP1 (load settings + resolve targets), CP2 (per-file iteration loop: dispatch, parse, apply, converge), CP3 (security self-check), CP4 (structured JSON output schema), CP5 (sub-skill caller directive). For subagent heuristics and contract, see references/compaction-mode.md.
PR Review Extraction Mode
When --from-pr is specified, extract rules from PR review comments (human comments only).
Single or multiple PRs can be specified. Numbers and URLs can be mixed. Cross-repository PRs are allowed.
Read references/pr-review-mode.md for the full processing steps (P1-P5). Key flow:
- Check prerequisites (
ghCLI authentication) - Parse all PR arguments, validate each PR exists
- Fetch review comments from GitHub API (3 endpoints per PR), filter bot comments
- Extract principles and patterns (per pre-loaded
extraction-criteria.md) - Multiple PRs: Cross-PR frequency analysis — general best practices that are repeatedly pointed out across different PRs are promoted as organizational emphasis
- Append to existing rule files and update
.examples.md(same as Step C5)
Testing & Validation
After running rules-extract:
- Output present —
output_dir(default.Codex/rules/) contains files matching the detected stack - Split format — with
split_output: true:.mdhas## Principlesonly,.local.mdhas## Project-specific patternsonly - Security — no tokens, secrets, or internal URLs in generated files (Step 6.5 passed)
- No stale symbols — Step U3 (Update Mode) flags symbols no longer in codebase; review before accepting
- Deduplication — patterns already in existing rule files are not re-added
Quality gates:
- [ ] Each detected language/framework has a corresponding rule file in
output_dir - [ ]
paths:frontmatter present on all rule files (exceptproject.md) - [ ]
.examples.mdfiles written toexamples_output_dir(outside auto-load scope by default) - [ ] No patterns duplicated between
.mdand.local.mdsibling files - [ ]
/rules-reviewfires on known violations from the extracted rules
Reference Guide
| Resource | Purpose |
|---|---|
references/extraction-criteria.md |
Classification criteria — what to extract vs. skip |
references/integration-criteria.md |
Detection rules and output routing for integration libraries |
references/security.md |
Security self-check patterns — run after every generation step |
references/examples-format.md |
.examples.md file structure, Good/Bad guidelines, reference section format |
references/report-templates.md |
Report format for all modes |
references/output-structure.md |
Directory tree diagrams, YAML config example, rule file format |
references/full-extraction-mode.md |
Complete procedure for Full Extraction Mode (Steps 1–7) |
references/update-mode.md |
Complete procedure for Update Mode (Steps U1–U6) |
references/restructure-mode.md |
Complete procedure for Restructure Mode (Steps R1–R5) |
references/conversation-mode.md |
Subagent instructions for Steps C3–C5 (Conversation Extraction) |
references/pr-review-mode.md |
Full processing steps P1–P5 (PR Review Extraction) |
references/compaction-mode.md |
Subagent instructions and heuristics for Compaction Mode |
references/compaction-orchestration.md |
Main-thread orchestration for Compaction Mode (CP1–CP5) |
references/resolve-references.md |
Reference resolution processing steps (Restructure Mode R2.5) |
scripts/extract_session_messages.mjs |
Node.js script for parsing session .jsonl files (Conversation Mode) |
Sub-skill caller directive
When invoked as a sub-skill (i.e. via Skill(rules-extract) from an orchestrating caller), the fenced JSON verdict block this skill emits in --compact mode is the structured return value of the skill's procedure — it is not a deliverable to the user, and emitting it does not terminate the orchestrator's turn. The same agent that ran this skill must immediately issue the next tool call dictated by the orchestrator's flow. Do not insert a prose summary, an acknowledgment, or a "shall I proceed?" sentence between the JSON verdict and the next tool call. Only one fenced JSON block — the verdict block — appears in the response, so callers can locate it unambiguously.
This directive applies specifically to --compact mode. Other modes produce prose reports rather than fenced JSON verdicts and are not subject to this contract.
Stop hook note: If a Stop hook fires mid-dispatch, ignore it and continue — per-file boundaries are the canonical completion signal.
04 同仓库更多 Skills
demo
Fixture skill used by scripts.marketplace_ci sync tests.
export-demo
Fixture skill used by scripts.marketplace_ci export tests.
work-to-development
Validate an accepted Linear Issue's readiness for implementation (criteria, dependencies, duplicate/existing artifacts) and request governed branch/worktree creation through git-kit:starting-work — recording work-started Git/GitHub evidence and a deliberate Linear Started transition only after Git identity is read back and verified. Use when asked to start work on a Linear issue, begin development for an accepted issue, or prepare an accepted issue for implementation. Never creates a branch directly — always delegates to git-kit.
work-linking
Create and maintain stable cross-system links and authority labels between Notion and Linear records, and detect/repair drift between them. Use when asked to link a Notion record to a Linear record, check for drift between Notion and Linear, or repair a broken/stale link. Repairs only the bounded non-authoritative copy or link — never chooses by newest timestamp, and never creates a reverse-write loop against either system's own authority.
status-and-learning
Produce a dated, explicitly non-live Linear-to-Notion progress summary, or capture an outcome/learning after work completes. Use when asked to summarize progress to Notion, report portfolio status, or capture what was learned from a completed piece of work — not to disposition open follow-up items (see open-item-management for that). Never runs automatically or continuously — every summary is a deliberate, approved snapshot, not a live sync.
repository-gates
Discover, delegate, record, and invalidate this repository's actual Git/GitHub lifecycle gates (pre-commit, pre-push, PR required checks, Codex delta review, review requirements, merge rights) and the repository-policy provider profile that maps governed operations to git-kit. Use when asked what gates apply to this repository, to discover repository policy before starting Wave 2 work, or to check whether prior gate evidence is still valid after new commits. Discovery and delegation only — never executes a gate's own internal logic, and never invents a gate the repository doesn't actually define (in particular, never assumes a "Review Changes" gate exists).