@devxiyang/agent-skill 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. package/README.md +5 -2
  2. package/dist/discovery/discovery.d.ts +4 -2
  3. package/dist/discovery/discovery.d.ts.map +1 -1
  4. package/dist/discovery/discovery.js +6 -5
  5. package/dist/discovery/discovery.js.map +1 -1
  6. package/dist/discovery/frontmatter.d.ts +0 -12
  7. package/dist/discovery/frontmatter.d.ts.map +1 -1
  8. package/dist/discovery/frontmatter.js +13 -79
  9. package/dist/discovery/frontmatter.js.map +1 -1
  10. package/dist/types.d.ts +5 -1
  11. package/dist/types.d.ts.map +1 -1
  12. package/package.json +1 -1
  13. package/skills/git/SKILL.md +78 -0
  14. package/skills/git/references/install.md +65 -0
  15. package/skills/github/SKILL.md +60 -3
  16. package/skills/github/references/install.md +68 -0
  17. package/skills/skill-creator/SKILL.md +3 -1
  18. package/skills/tmux/SKILL.md +10 -0
  19. package/skills/tmux/references/install.md +56 -0
  20. package/skills/weather/SKILL.md +10 -0
  21. package/skills/weather/references/install.md +51 -0
  22. package/skills/web/SKILL.md +91 -3
  23. package/skills/web/references/install.md +51 -0
package/README.md CHANGED
@@ -30,6 +30,8 @@ name: github
30
30
  description: Interact with GitHub using the gh CLI.
31
31
  requires: bin:gh,env:GITHUB_TOKEN
32
32
  os: darwin,linux
33
+ always: false
34
+ tags: github,vcs
33
35
  ---
34
36
  ```
35
37
 
@@ -39,7 +41,8 @@ os: darwin,linux
39
41
  | `description` | yes | What the skill does and when to use it |
40
42
  | `requires` | no | `bin:<name>` and/or `env:<NAME>` comma-separated |
41
43
  | `os` | no | Allowed platforms: `darwin`, `linux`, `win32` |
42
- | `always` | no | Load into agent context on every run |
44
+ | `always` | no | If `true`, inject into agent context on every run |
45
+ | `tags` | no | Comma-separated labels for categorisation |
43
46
 
44
47
  ## Usage
45
48
 
@@ -54,7 +57,7 @@ const discovery = new SkillDiscovery([
54
57
  // Discover all skills with eligibility info
55
58
  const entries = await discovery.list();
56
59
 
57
- // Load the body of a SKILL.md (frontmatter stripped)
60
+ // Load full SKILL.md content (frontmatter + body) for injection into agent context
58
61
  const content = await discovery.load(entries[0].filePath);
59
62
  ```
60
63
 
package/dist/discovery/discovery.d.ts CHANGED
@@ -27,8 +27,10 @@ export declare class SkillDiscovery {
27
27
  */
28
28
  list(): Promise<SkillEntry[]>;
29
29
  /**
30
- * Reads a SKILL.md file and returns its body with the frontmatter block stripped.
31
- * This is the content suitable for injecting into an agent's context.
30
+ * Reads a SKILL.md file and returns its full content — frontmatter and body — for
31
+ * injection into an agent's context. The agent can read the frontmatter metadata
32
+ * (name, description, requires, os, etc.) alongside the instructions, and use that
33
+ * information autonomously (e.g. installing a missing dependency declared in `requires`).
32
34
  */
33
35
  load(filePath: string): Promise<string>;
34
36
  /**
package/dist/discovery/discovery.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/discovery/discovery.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAsB,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAItD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc;IAIvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;gBAGxB,KAAK,EAAE,SAAS,EAAE,EACnC,SAAS,CAAC,EAAE,cAAc;IAK5B;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAqCnC;;;OAGG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO7C;;;OAGG;YACW,cAAc;CAyB7B"}
1
+ {"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/discovery/discovery.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAsB,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAItD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc;IAIvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;gBAGxB,KAAK,EAAE,SAAS,EAAE,EACnC,SAAS,CAAC,EAAE,cAAc;IAK5B;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAqCnC;;;;;OAKG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAM7C;;;OAGG;YACW,cAAc;CAyB7B"}
package/dist/discovery/discovery.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import fs from 'node:fs/promises';
2
2
  import path from 'node:path';
3
3
  import { defaultValidator } from '../validators/index.js';
4
- import { parseFrontmatter, stripFrontmatter } from './frontmatter.js';
4
+ import { parseFrontmatter } from './frontmatter.js';
5
5
  /**
6
6
  * Discovers and loads skills from one or more root directories.
7
7
  *
@@ -65,12 +65,13 @@ export class SkillDiscovery {
65
65
  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
66
66
  }
67
67
  /**
68
- * Reads a SKILL.md file and returns its body with the frontmatter block stripped.
69
- * This is the content suitable for injecting into an agent's context.
68
+ * Reads a SKILL.md file and returns its full content — frontmatter and body — for
69
+ * injection into an agent's context. The agent can read the frontmatter metadata
70
+ * (name, description, requires, os, etc.) alongside the instructions, and use that
71
+ * information autonomously (e.g. installing a missing dependency declared in `requires`).
70
72
  */
71
73
  async load(filePath) {
72
- const content = await fs.readFile(filePath, 'utf8');
73
- return stripFrontmatter(content);
74
+ return fs.readFile(filePath, 'utf8');
74
75
  }
75
76
  // ---------------------------------------------------------------------------
76
77
  /**
package/dist/discovery/discovery.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/discovery/discovery.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/discovery/discovery.ts"],"names":[],"mappings":"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"}
package/dist/discovery/frontmatter.d.ts CHANGED
@@ -10,18 +10,6 @@ export type SkillFrontmatter = {
10
10
  };
11
11
  /**
12
12
  * Parses the YAML frontmatter of a SKILL.md file into a normalized structure.
13
- *
14
- * Supports two requirement sources:
15
- * 1. Top-level `requires` field: `bin:git,env:GITHUB_TOKEN`
16
- * 2. `metadata` field: a JSON string with a namespaced object (`octoii` or `openclaw`)
17
- * containing `requires`, `bins`, `env`, and `os` keys.
18
- *
19
- * Values from both sources are merged and deduplicated.
20
13
  */
21
14
  export declare function parseFrontmatter(content: string): SkillFrontmatter;
22
- /**
23
- * Strips the frontmatter block from a SKILL.md file and returns the trimmed body.
24
- * This is the markdown content passed to the agent as skill instructions.
25
- */
26
- export declare function stripFrontmatter(content: string): string;
27
15
  //# sourceMappingURL=frontmatter.d.ts.map
package/dist/discovery/frontmatter.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/discovery/frontmatter.ts"],"names":[],"mappings":"AAEA,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAgBlE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD"}
1
+ {"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/discovery/frontmatter.ts"],"names":[],"mappings":"AAEA,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAalE"}
package/dist/discovery/frontmatter.js CHANGED
@@ -1,101 +1,38 @@
1
1
  import matter from 'gray-matter';
2
2
  /**
3
3
  * Parses the YAML frontmatter of a SKILL.md file into a normalized structure.
4
- *
5
- * Supports two requirement sources:
6
- * 1. Top-level `requires` field: `bin:git,env:GITHUB_TOKEN`
7
- * 2. `metadata` field: a JSON string with a namespaced object (`octoii` or `openclaw`)
8
- * containing `requires`, `bins`, `env`, and `os` keys.
9
- *
10
- * Values from both sources are merged and deduplicated.
11
4
  */
12
5
  export function parseFrontmatter(content) {
13
- const { data, content: body } = matter(content);
14
- void body;
15
- const meta = parseMetadataJson(data.metadata);
16
- const requires = extractRequirements(data, meta);
6
+ const { data } = matter(content);
7
+ const { bins, envs } = parseRequireString(data.requires);
17
8
  return {
18
9
  name: normalizeString(data.name),
19
10
  description: normalizeString(data.description),
20
- always: data.always === true || meta.always === true,
21
- tags: parseCsv(data.tags ?? meta.tags),
22
- requiresBins: requires.bins,
23
- requiresEnvs: requires.envs,
24
- requiresOs: parseCsv(meta.os),
11
+ always: data.always === true,
12
+ tags: parseCsv(data.tags),
13
+ requiresBins: bins,
14
+ requiresEnvs: envs,
15
+ requiresOs: parseCsv(data.os),
25
16
  };
26
17
  }
27
- /**
28
- * Strips the frontmatter block from a SKILL.md file and returns the trimmed body.
29
- * This is the markdown content passed to the agent as skill instructions.
30
- */
31
- export function stripFrontmatter(content) {
32
- return matter(content).content.trim();
33
- }
34
18
  // ---------------------------------------------------------------------------
35
- /**
36
- * Parses the `metadata` field, which is an embedded JSON string that may contain
37
- * a scoped namespace (`octoii` or `openclaw`). Returns an empty object on failure.
38
- */
39
- function parseMetadataJson(raw) {
40
- if (typeof raw !== 'string')
41
- return {};
42
- try {
43
- const parsed = JSON.parse(raw);
44
- if (!isRecord(parsed))
45
- return {};
46
- return pickScopedNamespace(parsed);
47
- }
48
- catch {
49
- return {};
50
- }
51
- }
52
- /**
53
- * If the object has a known namespace key (`octoii`, `openclaw`), returns that
54
- * nested object. Otherwise returns the object as-is for flat metadata structures.
55
- */
56
- function pickScopedNamespace(input) {
57
- for (const ns of ['octoii', 'openclaw']) {
58
- if (ns in input && isRecord(input[ns])) {
59
- return input[ns];
60
- }
61
- }
62
- return input;
63
- }
64
- /**
65
- * Merges `requires` strings and explicit `bins`/`env` lists from both the
66
- * top-level frontmatter and the metadata namespace, deduplicating results.
67
- */
68
- function extractRequirements(data, meta) {
69
- const bins = new Set();
70
- const envs = new Set();
71
- for (const { b, e } of [
72
- parseRequireString(data.requires),
73
- parseRequireString(meta.requires),
74
- ]) {
75
- b.forEach((v) => bins.add(v));
76
- e.forEach((v) => envs.add(v));
77
- }
78
- parseCsv(meta.bins).forEach((v) => bins.add(v));
79
- parseCsv(meta.env).forEach((v) => envs.add(v));
80
- return { bins: [...bins], envs: [...envs] };
81
- }
82
19
  /**
83
20
  * Parses a `requires` string of the form `bin:git,env:TOKEN` into separate
84
21
  * bin and env arrays. Supports both comma and semicolon as delimiters.
85
22
  */
86
23
  function parseRequireString(raw) {
87
24
  if (typeof raw !== 'string')
88
- return { b: [], e: [] };
89
- const b = [];
90
- const e = [];
25
+ return { bins: [], envs: [] };
26
+ const bins = [];
27
+ const envs = [];
91
28
  for (const part of raw.split(/[;,]/)) {
92
29
  const v = part.trim();
93
30
  if (v.startsWith('bin:'))
94
- b.push(v.slice(4).trim());
31
+ bins.push(v.slice(4).trim());
95
32
  else if (v.startsWith('env:'))
96
- e.push(v.slice(4).trim());
33
+ envs.push(v.slice(4).trim());
97
34
  }
98
- return { b, e };
35
+ return { bins, envs };
99
36
  }
100
37
  /**
101
38
  * Parses a value that may be a comma-separated string or an array of strings.
@@ -117,7 +54,4 @@ function normalizeString(raw) {
117
54
  const v = raw.trim();
118
55
  return v.length > 0 ? v : null;
119
56
  }
120
- function isRecord(v) {
121
- return v !== null && typeof v === 'object' && !Array.isArray(v);
122
- }
123
57
  //# sourceMappingURL=frontmatter.js.map
package/dist/discovery/frontmatter.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/discovery/frontmatter.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/discovery/frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAajC;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACjC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEzD,OAAO;QACL,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;QAChC,WAAW,EAAE,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC;QAC9C,MAAM,EAAE,IAAI,CAAC,MAAM,KAAK,IAAI;QAC5B,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QACzB,YAAY,EAAE,IAAI;QAClB,YAAY,EAAE,IAAI;QAClB,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;KAC9B,CAAC;AACJ,CAAC;AAED,8EAA8E;AAE9E;;;GAGG;AACH,SAAS,kBAAkB,CAAC,GAAY;IACtC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAC3D,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;aAClD,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,SAAS,QAAQ,CAAC,GAAY;IAC5B,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,0EAA0E;AAC1E,SAAS,eAAe,CAAC,GAAY;IACnC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACrB,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACjC,CAAC"}
package/dist/types.d.ts CHANGED
@@ -27,7 +27,11 @@ export type SkillEntry = {
27
27
  /** Absolute path to the SKILL.md file inside the skill folder. */
28
28
  filePath: string;
29
29
  scope: SkillScope;
30
- /** True when all requires/os constraints are satisfied in the current environment. */
30
+ /**
31
+ * True when all requires/os constraints are satisfied in the current environment.
32
+ * Informational only — the skill content should still be passed to the agent even
33
+ * when false, so the agent can autonomously resolve missing dependencies.
34
+ */
31
35
  eligible: boolean;
32
36
  /** Unmet requirements; empty when eligible is true. */
33
37
  missing: SkillMissingReason[];
package/dist/types.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE3C,oEAAoE;AACpE,MAAM,MAAM,SAAS,GAAG;IACtB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,KAAK,EAAE,UAAU,CAAC;CACnB,CAAC;AAEF,2CAA2C;AAC3C,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC;AAEtE,0EAA0E;AAC1E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,sBAAsB,CAAC;IAC7B,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG;IACvB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,CAAC;IAClB,sFAAsF;IACtF,QAAQ,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,mFAAmF;IACnF,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE3C,oEAAoE;AACpE,MAAM,MAAM,SAAS,GAAG;IACtB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,KAAK,EAAE,UAAU,CAAC;CACnB,CAAC;AAEF,2CAA2C;AAC3C,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC;AAEtE,0EAA0E;AAC1E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,sBAAsB,CAAC;IAC7B,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG;IACvB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,CAAC;IAClB;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,mFAAmF;IACnF,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@devxiyang/agent-skill",
3
- "version": "0.0.1",
3
+ "version": "0.0.2",
4
4
  "description": "SDK for skill discovery and registration — integrates into any agent",
5
5
  "license": "MIT",
6
6
  "repository": {
package/skills/git/SKILL.md CHANGED
@@ -6,6 +6,16 @@ requires: bin:git
6
6
 
7
7
  # Git Skill
8
8
 
9
+ ## Preflight
10
+
11
+ Verify git is available before proceeding:
12
+
13
+ ```bash
14
+ git --version
15
+ ```
16
+
17
+ If missing, load `references/install.md` for installation instructions.
18
+
9
19
  ## Common workflow
10
20
 
11
21
  ```bash
@@ -30,6 +40,37 @@ git log --oneline -20
30
40
  git log --oneline --graph --all
31
41
  git show <commit>
32
42
  git diff main...HEAD
43
+ git blame <file>
44
+ ```
45
+
46
+ ## Cherry-pick
47
+
48
+ ```bash
49
+ # Apply a specific commit onto the current branch
50
+ git cherry-pick <commit>
51
+
52
+ # Cherry-pick a range
53
+ git cherry-pick <from>..<to>
54
+
55
+ # Cherry-pick without committing (stage only)
56
+ git cherry-pick -n <commit>
57
+ ```
58
+
59
+ ## Tags
60
+
61
+ ```bash
62
+ # Create annotated tag
63
+ git tag -a v1.0.0 -m "Release 1.0.0"
64
+
65
+ # List tags
66
+ git tag
67
+
68
+ # Push tags to remote
69
+ git push origin --tags
70
+
71
+ # Delete a tag
72
+ git tag -d v1.0.0
73
+ git push origin :refs/tags/v1.0.0
33
74
  ```
34
75
 
35
76
  ## Undoing changes
@@ -77,6 +118,43 @@ git merge --abort
77
118
  3. `git add <resolved-file>`
78
119
  4. `git rebase --continue` or `git merge --continue`
79
120
 
121
+ ## Worktrees
122
+
123
+ Check out multiple branches simultaneously in separate directories — useful for working on or reviewing a branch without touching the current working tree:
124
+
125
+ ```bash
126
+ # Add a worktree for an existing branch
127
+ git worktree add ../project-fix fix/some-bug
128
+
129
+ # Add a worktree and create a new branch
130
+ git worktree add -b feature/new ../project-feature main
131
+
132
+ # List worktrees
133
+ git worktree list
134
+
135
+ # Remove a worktree when done
136
+ git worktree remove ../project-fix
137
+ ```
138
+
139
+ Each worktree shares the same repository history but has its own working directory and HEAD.
140
+
141
+ ## Debugging
142
+
143
+ ```bash
144
+ # Find which commit introduced a bug (binary search)
145
+ git bisect start
146
+ git bisect bad # current commit is broken
147
+ git bisect good <commit> # last known good commit
148
+ # git will check out commits for you to test; mark each:
149
+ git bisect good
150
+ git bisect bad
151
+ git bisect reset # done
152
+
153
+ # Show who last changed each line
154
+ git blame <file>
155
+ git blame -L 10,20 <file> # specific line range
156
+ ```
157
+
80
158
  ## Remotes
81
159
 
82
160
  ```bash
package/skills/git/references/install.md ADDED
@@ -0,0 +1,65 @@
1
+ # Installing git
2
+
3
+ ## macOS
4
+
5
+ The simplest way — install Xcode Command Line Tools, which includes git:
6
+
7
+ ```bash
8
+ xcode-select --install
9
+ ```
10
+
11
+ A dialog will appear asking to install the tools. No Homebrew or admin configuration needed beyond the standard macOS install prompt.
12
+
13
+ If you already have Homebrew:
14
+
15
+ ```bash
16
+ brew install git
17
+ ```
18
+
19
+ As a last resort, download the macOS installer from https://git-scm.com/download/mac.
20
+
21
+ After installing, configure your identity:
22
+
23
+ ```bash
24
+ git config --global user.name "Your Name"
25
+ git config --global user.email "you@example.com"
26
+ ```
27
+
28
+ ## Windows
29
+
30
+ Download the installer from https://git-scm.com/download/win and run it — this is the most straightforward path.
31
+
32
+ If winget is available:
33
+
34
+ ```powershell
35
+ winget install Git.Git
36
+ ```
37
+
38
+ If Chocolatey is available:
39
+
40
+ ```powershell
41
+ choco install git
42
+ ```
43
+
44
+ After installing, restart your terminal and configure identity:
45
+
46
+ ```bash
47
+ git config --global user.name "Your Name"
48
+ git config --global user.email "you@example.com"
49
+ ```
50
+
51
+ ## Linux
52
+
53
+ ```bash
54
+ # Debian/Ubuntu
55
+ sudo apt update && sudo apt install git
56
+
57
+ # Fedora
58
+ sudo dnf install git
59
+
60
+ # Arch
61
+ sudo pacman -S git
62
+
63
+ # openSUSE
64
+ sudo zypper install git
65
+ ```
package/skills/github/SKILL.md CHANGED
@@ -6,6 +6,16 @@ requires: bin:gh
6
6
 
7
7
  # GitHub Skill
8
8
 
9
+ ## Preflight
10
+
11
+ Verify gh is available before proceeding:
12
+
13
+ ```bash
14
+ gh --version
15
+ ```
16
+
17
+ If missing, load `references/install.md` for installation and authentication instructions.
18
+
9
19
  Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` when not inside a git directory.
10
20
 
11
21
  ## Pull Requests
@@ -14,14 +24,40 @@ Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` whe
14
24
  # List open PRs
15
25
  gh pr list --repo owner/repo
16
26
 
27
+ # View a PR
28
+ gh pr view <number> --repo owner/repo
29
+
17
30
  # Check CI status
18
31
  gh pr checks <number> --repo owner/repo
19
32
 
20
- # View failed logs
33
+ # View failed CI logs
21
34
  gh run view <run-id> --repo owner/repo --log-failed
22
35
 
23
- # Review and approve
36
+ # Merge a PR
37
+ gh pr merge <number> --repo owner/repo --squash
38
+ gh pr merge <number> --repo owner/repo --merge
39
+ gh pr merge <number> --repo owner/repo --rebase
40
+ ```
41
+
42
+ ## Code review
43
+
44
+ ```bash
45
+ # Approve
24
46
  gh pr review <number> --approve --repo owner/repo
47
+
48
+ # Request changes
49
+ gh pr review <number> --request-changes --body "Please fix X" --repo owner/repo
50
+
51
+ # Leave a comment
52
+ gh pr review <number> --comment --body "Looks good overall" --repo owner/repo
53
+
54
+ # Add inline comment via API
55
+ gh api repos/owner/repo/pulls/<number>/comments \
56
+ --method POST \
57
+ --field body="Comment text" \
58
+ --field commit_id="<sha>" \
59
+ --field path="src/file.ts" \
60
+ --field line=42
25
61
  ```
26
62
 
27
63
  ## Issues
@@ -30,11 +66,31 @@ gh pr review <number> --approve --repo owner/repo
30
66
  # List issues
31
67
  gh issue list --repo owner/repo --state open
32
68
 
69
+ # View an issue
70
+ gh issue view <number> --repo owner/repo
71
+
33
72
  # Create issue
34
73
  gh issue create --title "Title" --body "Body" --repo owner/repo
35
74
 
36
- # Close issue
75
+ # Comment on an issue
76
+ gh issue comment <number> --body "Comment" --repo owner/repo
77
+
78
+ # Close / reopen
37
79
  gh issue close <number> --repo owner/repo
80
+ gh issue reopen <number> --repo owner/repo
81
+ ```
82
+
83
+ ## Releases
84
+
85
+ ```bash
86
+ # List releases
87
+ gh release list --repo owner/repo
88
+
89
+ # Create a release
90
+ gh release create v1.0.0 --repo owner/repo --title "v1.0.0" --notes "Release notes"
91
+
92
+ # Upload assets to a release
93
+ gh release upload v1.0.0 dist/app.zip --repo owner/repo
38
94
  ```
39
95
 
40
96
  ## API
@@ -51,4 +107,5 @@ Most commands support `--json` + `--jq`:
51
107
 
52
108
  ```bash
53
109
  gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
110
+ gh pr list --repo owner/repo --json number,title,author --jq '.[] | "\(.number): \(.title) by \(.author.login)"'
54
111
  ```
package/skills/github/references/install.md ADDED
@@ -0,0 +1,68 @@
1
+ # Installing gh (GitHub CLI)
2
+
3
+ ## macOS
4
+
5
+ Download the `.pkg` installer from the releases page — no Homebrew required:
6
+
7
+ https://github.com/cli/cli/releases/latest
8
+
9
+ Look for the file ending in `macOS_amd64.pkg` (Intel) or `macOS_arm64.pkg` (Apple Silicon). Double-click to install.
10
+
11
+ If you have Homebrew:
12
+
13
+ ```bash
14
+ brew install gh
15
+ ```
16
+
17
+ If you have MacPorts:
18
+
19
+ ```bash
20
+ sudo port install gh
21
+ ```
22
+
23
+ ## Windows
24
+
25
+ Download the `.msi` installer from https://github.com/cli/cli/releases/latest — this is the most straightforward path.
26
+
27
+ If winget is available:
28
+
29
+ ```powershell
30
+ winget install GitHub.cli
31
+ ```
32
+
33
+ If Chocolatey is available:
34
+
35
+ ```powershell
36
+ choco install gh
37
+ ```
38
+
39
+ ## Linux
40
+
41
+ Debian/Ubuntu — add GitHub's official apt repository:
42
+
43
+ ```bash
44
+ (type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \
45
+ && sudo mkdir -p -m 755 /etc/apt/keyrings \
46
+ && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
47
+ && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
48
+ && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
49
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
50
+ && sudo apt update \
51
+ && sudo apt install gh -y
52
+ ```
53
+
54
+ ```bash
55
+ # Fedora
56
+ sudo dnf install gh
57
+
58
+ # Arch
59
+ sudo pacman -S github-cli
60
+ ```
61
+
62
+ ## Post-install: authenticate
63
+
64
+ ```bash
65
+ gh auth login
66
+ ```
67
+
68
+ Follow the prompts — choose GitHub.com, then authenticate via browser (recommended) or paste a personal access token.
package/skills/skill-creator/SKILL.md CHANGED
@@ -25,6 +25,8 @@ name: skill-name
25
25
  description: What this skill does and when to use it. Be specific about triggers.
26
26
  requires: bin:tool,env:API_KEY # optional
27
27
  os: darwin,linux # optional, omit for all platforms
28
+ always: false # optional, set true to inject on every agent run
29
+ tags: category,label # optional, comma-separated
28
30
  ---
29
31
 
30
32
  # Skill Name
@@ -32,7 +34,7 @@ os: darwin,linux # optional, omit for all platforms
32
34
  Instructions for the agent...
33
35
  ```
34
36
 
35
- Only `name` and `description` are required in frontmatter.
37
+ Only `name` and `description` are required. All other frontmatter fields are optional.
36
38
 
37
39
  ## Writing good descriptions
38
40
 
package/skills/tmux/SKILL.md CHANGED
@@ -7,6 +7,16 @@ os: darwin,linux
7
7
 
8
8
  # tmux Skill
9
9
 
10
+ ## Preflight
11
+
12
+ Verify tmux is available before proceeding:
13
+
14
+ ```bash
15
+ tmux -V
16
+ ```
17
+
18
+ If missing, load `references/install.md` for installation instructions.
19
+
10
20
  Use tmux only when you need an interactive TTY. For non-interactive long-running tasks, prefer background execution instead.
11
21
 
12
22
  ## Quickstart
package/skills/tmux/references/install.md ADDED
@@ -0,0 +1,56 @@
1
+ # Installing tmux
2
+
3
+ tmux runs on macOS and Linux only. On Windows, use WSL2 (see below).
4
+
5
+ ## macOS
6
+
7
+ tmux has no official standalone installer for macOS. The available options are:
8
+
9
+ If you have Homebrew:
10
+
11
+ ```bash
12
+ brew install tmux
13
+ ```
14
+
15
+ If you have MacPorts:
16
+
17
+ ```bash
18
+ sudo port install tmux
19
+ ```
20
+
21
+ If neither is available, Homebrew is the recommended path. Install it with:
22
+
23
+ ```bash
24
+ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
25
+ ```
26
+
27
+ Then retry `brew install tmux`.
28
+
29
+ ## Linux
30
+
31
+ ```bash
32
+ # Debian/Ubuntu
33
+ sudo apt update && sudo apt install tmux
34
+
35
+ # Fedora
36
+ sudo dnf install tmux
37
+
38
+ # Arch
39
+ sudo pacman -S tmux
40
+
41
+ # openSUSE
42
+ sudo zypper install tmux
43
+ ```
44
+
45
+ ## Windows (WSL2)
46
+
47
+ tmux does not run natively on Windows. Use WSL2:
48
+
49
+ 1. Install WSL2 if not present:
50
+ ```powershell
51
+ wsl --install
52
+ ```
53
+ 2. Open the WSL2 terminal, then:
54
+ ```bash
55
+ sudo apt update && sudo apt install tmux
56
+ ```
package/skills/weather/SKILL.md CHANGED
@@ -6,6 +6,16 @@ requires: bin:curl
6
6
 
7
7
  # Weather Skill
8
8
 
9
+ ## Preflight
10
+
11
+ Verify curl is available before proceeding:
12
+
13
+ ```bash
14
+ curl --version
15
+ ```
16
+
17
+ If missing, load `references/install.md` for installation instructions.
18
+
9
19
  Two free services, no API keys needed.
10
20
 
11
21
  ## wttr.in (primary)
package/skills/weather/references/install.md ADDED
@@ -0,0 +1,51 @@
1
+ # Installing curl
2
+
3
+ curl is pre-installed on macOS and Windows 10 (version 1803+). Check first:
4
+
5
+ ```bash
6
+ curl --version
7
+ ```
8
+
9
+ Install only if the command is not found.
10
+
11
+ ## macOS
12
+
13
+ curl ships with every macOS installation. If the command is somehow missing, it likely indicates a system issue rather than a missing package. Try reinstalling Xcode Command Line Tools:
14
+
15
+ ```bash
16
+ xcode-select --install
17
+ ```
18
+
19
+ If you need a newer version and have Homebrew:
20
+
21
+ ```bash
22
+ brew install curl
23
+ ```
24
+
25
+ ## Windows
26
+
27
+ curl is bundled with Windows 10 version 1803+ as `curl.exe`. If missing:
28
+
29
+ Download from https://curl.se/windows/ and add the binary to your PATH.
30
+
31
+ If winget is available:
32
+
33
+ ```powershell
34
+ winget install cURL.cURL
35
+ ```
36
+
37
+ ## Linux
38
+
39
+ ```bash
40
+ # Debian/Ubuntu
41
+ sudo apt update && sudo apt install curl
42
+
43
+ # Fedora
44
+ sudo dnf install curl
45
+
46
+ # Arch
47
+ sudo pacman -S curl
48
+
49
+ # openSUSE
50
+ sudo zypper install curl
51
+ ```
package/skills/web/SKILL.md CHANGED
@@ -6,6 +6,16 @@ requires: bin:curl
6
6
 
7
7
  # Web Skill
8
8
 
9
+ ## Preflight
10
+
11
+ Verify curl is available before proceeding:
12
+
13
+ ```bash
14
+ curl --version
15
+ ```
16
+
17
+ If missing, load `references/install.md` for installation instructions.
18
+
9
19
  ## Fetch a web page
10
20
 
11
21
  ```bash
@@ -23,22 +33,99 @@ curl -s -X POST "https://api.example.com/items" \
23
33
  -H "Content-Type: application/json" \
24
34
  -d '{"name": "foo"}'
25
35
 
36
+ # PUT
37
+ curl -s -X PUT "https://api.example.com/items/1" \
38
+ -H "Content-Type: application/json" \
39
+ -d '{"name": "bar"}'
40
+
41
+ # DELETE
42
+ curl -s -X DELETE "https://api.example.com/items/1"
43
+
26
44
  # With auth header
27
45
  curl -s "https://api.example.com/data" \
28
46
  -H "Authorization: Bearer $TOKEN"
29
47
  ```
30
48
 
49
+ ## Form data & file upload
50
+
51
+ ```bash
52
+ # Submit a form (application/x-www-form-urlencoded)
53
+ curl -s -X POST "https://example.com/login" \
54
+ -d "username=alice&password=secret"
55
+
56
+ # Multipart file upload
57
+ curl -s -X POST "https://example.com/upload" \
58
+ -F "file=@/path/to/file.pdf" \
59
+ -F "description=My file"
60
+ ```
61
+
62
+ ## Cookies & sessions
63
+
64
+ ```bash
65
+ # Save cookies to a file
66
+ curl -s -c cookies.txt "https://example.com/login" \
67
+ -d "user=alice&pass=secret"
68
+
69
+ # Reuse saved cookies
70
+ curl -s -b cookies.txt "https://example.com/dashboard"
71
+ ```
72
+
31
73
  ## Download a file
32
74
 
33
75
  ```bash
34
76
  curl -sL "https://example.com/file.zip" -o /tmp/file.zip
77
+
78
+ # Resume interrupted download
79
+ curl -C - -L "https://example.com/large.zip" -o /tmp/large.zip
35
80
  ```
36
81
 
37
- ## Extract text from a page
82
+ ## Extract content from a page
83
+
84
+ Prefer Python for reliable HTML parsing over fragile sed/grep:
38
85
 
39
86
  ```bash
40
- # Strip HTML tags
41
- curl -sL "https://example.com" | sed 's/<[^>]*>//g' | sed '/^[[:space:]]*$/d'
87
+ curl -sL "https://example.com" | python3 -c "
88
+ import sys, html.parser
89
+
90
+ class TextExtractor(html.parser.HTMLParser):
91
+ skip = {'script', 'style'}
92
+ def __init__(self):
93
+ super().__init__()
94
+ self._tag = None
95
+ self.parts = []
96
+ def handle_starttag(self, tag, attrs):
97
+ self._tag = tag
98
+ def handle_data(self, data):
99
+ if self._tag not in self.skip and data.strip():
100
+ self.parts.append(data.strip())
101
+
102
+ p = TextExtractor()
103
+ p.feed(sys.stdin.read())
104
+ print('\n'.join(p.parts))
105
+ "
106
+ ```
107
+
108
+ ## Inspect response
109
+
110
+ ```bash
111
+ # Headers only
112
+ curl -sI "https://example.com"
113
+
114
+ # Show both headers and body
115
+ curl -sD - "https://example.com"
116
+
117
+ # Show HTTP status code only
118
+ curl -s -o /dev/null -w "%{http_code}" "https://example.com"
119
+ ```
120
+
121
+ ## HTTPS & certificates
122
+
123
+ ```bash
124
+ # Skip certificate verification (use only for testing)
125
+ curl -sk "https://self-signed.example.com"
126
+
127
+ # Use a specific CA certificate
128
+ curl -s --cacert /path/to/ca.crt "https://example.com"
42
129
  ```
43
130
 
44
131
  ## Tips
@@ -48,3 +135,4 @@ curl -sL "https://example.com" | sed 's/<[^>]*>//g' | sed '/^[[:space:]]*$/d'
48
135
  - `-I` fetches headers only
49
136
  - `--max-time 10` sets a timeout in seconds
50
137
  - `--compressed` requests gzip encoding automatically
138
+ - `-v` shows full request/response for debugging
package/skills/web/references/install.md ADDED
@@ -0,0 +1,51 @@
1
+ # Installing curl
2
+
3
+ curl is pre-installed on macOS and Windows 10 (version 1803+). Check first:
4
+
5
+ ```bash
6
+ curl --version
7
+ ```
8
+
9
+ Install only if the command is not found.
10
+
11
+ ## macOS
12
+
13
+ curl ships with every macOS installation. If the command is somehow missing, it likely indicates a system issue rather than a missing package. Try reinstalling Xcode Command Line Tools:
14
+
15
+ ```bash
16
+ xcode-select --install
17
+ ```
18
+
19
+ If you need a newer version and have Homebrew:
20
+
21
+ ```bash
22
+ brew install curl
23
+ ```
24
+
25
+ ## Windows
26
+
27
+ curl is bundled with Windows 10 version 1803+ as `curl.exe`. If missing:
28
+
29
+ Download from https://curl.se/windows/ and add the binary to your PATH.
30
+
31
+ If winget is available:
32
+
33
+ ```powershell
34
+ winget install cURL.cURL
35
+ ```
36
+
37
+ ## Linux
38
+
39
+ ```bash
40
+ # Debian/Ubuntu
41
+ sudo apt update && sudo apt install curl
42
+
43
+ # Fedora
44
+ sudo dnf install curl
45
+
46
+ # Arch
47
+ sudo pacman -S curl
48
+
49
+ # openSUSE
50
+ sudo zypper install curl
51
+ ```